# `AshAuthentication.Strategy.KubernetesServiceAccount`
[🔗](https://git.jakeschurch.com/jake/ash_authentication_kubernetes/src/tag/v0.1.0/lib/ash_authentication/strategy/kubernetes_service_account.ex#L1)

Sign an in-cluster workload in by its projected Kubernetes service-account
token.

    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"]
            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

It is a bearer-only strategy, like AshAuthentication's `api_key`: no
routes and no phases, one `:sign_in` action. The transformer generates
`sign_in_with_<name>` (a manual read with a sensitive `token` argument);
callers run it through `AshAuthentication.Strategy.action/4` and use the
record as the actor:

    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{}} -> 503
      {:error, _authentication_failed} -> 401
    end

`token_shaped?/1` tells a service-account JWT from other bearers when one
route accepts several kinds.

## Verification

`verifier` picks how a token is checked (`AshAuthentication.Strategy.KubernetesServiceAccount.TokenVerifier`):

  * `:token_review` (default) — the API server's TokenReview checks the
    signature, expiry, the requested `audiences` and that the bound Pod
    still exists, so a deleted pod's token stops working within `cache_ttl`.
    Needs `system:auth-delegator` and one round trip per verdict.
  * `:oidc_jwks` — verifies locally against the issuer's JWKS (fetched and
    cached; refetched on an unknown `kid`). No round trip per token and no
    RBAC beyond reading the JWKS, but a deleted pod's token stays valid
    until its `exp`.
  * `{module, options}` — your own.

Verdicts are cached per token (SHA-256) for `cache_ttl` milliseconds and
never past the token's `exp`; near expiry one request re-verifies while the
rest keep the cached verdict. During an outage a cached verdict serves until
it expires; with nothing cached the result is `UnavailableError`, never a
verdict. Refusals are not cached.

## Identity mapping

The verified identity (`namespace`, `name`, `username`, `uid`, the
`audiences` granted, `expires_at`, `extra`) goes to `identity_mapper`
(`AshAuthentication.Strategy.KubernetesServiceAccount.IdentityMapper`) on
every sign-in, which answers the actor's attributes or refuses. Only the
verification is cached, so an allowlist change applies at once. The actor
carries the identity as `__metadata__.kubernetes_service_account`.

# `t`

```elixir
@type t() :: %AshAuthentication.Strategy.KubernetesServiceAccount{
  __spark_metadata__: Spark.Dsl.Entity.spark_meta(),
  api: keyword() | mfa() | nil,
  audiences: [String.t()] | mfa(),
  cache_ttl: pos_integer(),
  identity_mapper: module(),
  name: atom(),
  resource: Ash.Resource.t(),
  sign_in_action_name: atom(),
  verifier: verifier()
}
```

# `verifier`

```elixir
@type verifier() :: :token_review | :oidc_jwks | {module(), keyword()}
```

# `api`

```elixir
@spec api(t()) :: keyword()
```

API options, resolving an MFA at runtime. See `AshAuthentication.Strategy.KubernetesServiceAccount.Api`.

# `audiences`

```elixir
@spec audiences(t()) :: [String.t()]
```

The audiences tokens must carry (one of), resolving an MFA at runtime.

# `token_shaped?`

```elixir
@spec token_shaped?(String.t()) :: boolean()
```

Whether `token` is shaped like a Kubernetes service-account JWT: an
asymmetric `alg` and a `kubernetes.io` claim. Unverified — only for routing
a bearer to this strategy rather than another verifier.

# `transform`

# `verify`

---

*Consult [api-reference.md](api-reference.md) for complete listing*
