# AshAuthentication.Kubernetes

An [AshAuthentication](https://hexdocs.pm/ash_authentication) strategy that
signs an in-cluster workload in by its **projected Kubernetes service-account
token** — no minted API keys, no secrets to deliver or rotate. The kubelet
issues and rotates the token; your app verifies it and maps the
`<namespace>/<serviceaccount>` identity to an actor that your Ash policies
authorize.

```elixir
def deps do
  [{:ash_authentication_kubernetes, "~> 0.1.0"}]
end
```

## Usage

```elixir
defmodule MyApp.Accounts.Workload do
  use Ash.Resource,
    domain: MyApp.Accounts,
    authorizers: [Ash.Policy.Authorizer],
    extensions: [AshAuthentication, AshAuthentication.Strategy.KubernetesServiceAccount]

  authentication do
    strategies do
      kubernetes_service_account :kubernetes do
        audiences ["my-service", "my-service-read"]
        verifier :token_review            # or :oidc_jwks, or {MyVerifier, opts}
        cache_ttl 60_000
        api {MyApp.Accounts.WorkloadIdentities, :kube_api, []}
        identity_mapper MyApp.Accounts.WorkloadIdentities
      end
    end
  end

  attributes do
    attribute :id, :string, primary_key?: true, allow_nil?: false, public?: true
    attribute :role, :atom, public?: true
  end

  policies do
    bypass AshAuthentication.Checks.AshAuthenticationInteraction do
      authorize_if always()
    end
  end
end

defmodule MyApp.Accounts.WorkloadIdentities do
  @behaviour AshAuthentication.Strategy.KubernetesServiceAccount.IdentityMapper

  @impl true
  def map_identity(%{namespace: "ci", name: "builder"} = identity, _strategy),
    do: {:ok, %{id: "ci/builder", role: :publisher}}

  def map_identity(_identity, _strategy), do: :error

  def kube_api,
    do: [
      token_file: "/var/run/secrets/my-app/kube/token",
      ca_file: "/var/run/secrets/my-app/kube/ca.crt"
    ]
end
```

The strategy is bearer-only (like `api_key`): it adds no routes. It
generates a `sign_in_with_<name>` read action; your plug calls it and sets
the actor:

```elixir
strategy = AshAuthentication.Info.strategy!(MyApp.Accounts.Workload, :kubernetes)

case AshAuthentication.Strategy.action(strategy, :sign_in, %{token: bearer}, []) do
  {:ok, actor} -> Ash.PlugHelpers.set_actor(conn, actor)
  {:error, %AshAuthentication.Strategy.KubernetesServiceAccount.UnavailableError{}} -> send_resp(conn, 503, "")
  {:error, _} -> send_resp(conn, 401, "")
end
```

`KubernetesServiceAccount.token_shaped?/1` distinguishes a service-account
JWT from other bearers when one endpoint accepts several kinds.

The workload side is a projected volume:

```yaml
volumes:
  - name: my-service-token
    projected:
      sources:
        - serviceAccountToken: {path: token, audience: my-service, expirationSeconds: 3600}
```

## Verifiers

| | `:token_review` (default) | `:oidc_jwks` |
|---|---|---|
| Checks | signature, expiry, audience, **bound Pod still exists** | signature, `iss`, audience, `exp`/`nbf`, `sub` vs claims |
| Cost | one API call per verdict (cached) | none per token; JWKS cached, refetched on unknown `kid` |
| RBAC | `system:auth-delegator` | read `/openid/v1/jwks` (`system:service-account-issuer-discovery`) |
| Deleted pod | refused once its verdict expires (`cache_ttl`) | valid until `exp` |

Verdicts are cached per token (SHA-256, never the token) for `cache_ttl`,
never past `exp`, with single-flight refresh near expiry. During an outage a
cached verdict keeps serving until it expires; with nothing cached the result
is `UnavailableError` — answer 503, not 401. Refusals are not cached. Only
verification is cached: the identity mapper runs on every sign-in, so
allowlist changes apply at once.

`api` options: `api` (base URL, default `https://kubernetes.default.svc`),
`token_file` (your own projected token; required for TokenReview), `ca_file`,
`issuer` and `jwks_uri` / `jwks_ttl` (JWKS), `req_options`.

Telemetry: `[:ash_authentication_kubernetes, :verify, :start | :stop | :exception]`
with `strategy` and `result` (`:ok | :unauthenticated | :unavailable`).

## Releasing

Forgejo is the only home. Push a signed `v<version>` tag matching `@version`;
the homelab's in-cluster Argo CI (`hex-publish` WorkflowTemplate, triggered by
the tag webhook) runs the gates and publishes to Hex.

## Development

```sh
nix develop    # C toolchain for bcrypt_elixir; Elixir from the host
mix test       # includes a fake API server (TokenReview + JWKS) over real HTTP
```

MIT licensed.
