AshAuthentication.Kubernetes

Copy Markdown View Source

An AshAuthentication 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.

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

Usage

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:

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:

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

Verifiers

:token_review (default):oidc_jwks
Checkssignature, expiry, audience, bound Pod still existssignature, iss, audience, exp/nbf, sub vs claims
Costone API call per verdict (cached)none per token; JWKS cached, refetched on unknown kid
RBACsystem:auth-delegatorread /openid/v1/jwks (system:service-account-issuer-discovery)
Deleted podrefused 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

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.