AshAuthentication.Strategy.KubernetesServiceAccount (AshAuthentication.Kubernetes v0.1.0)

Copy Markdown View Source

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.

Summary

Functions

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

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.

Types

t()

@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()

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

Functions

api(kubernetes_service_account)

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

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

audiences(kubernetes_service_account)

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

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

token_shaped?(token)

@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(entity, dsl_state)

Callback implementation for AshAuthentication.Strategy.Custom.transform/2.

verify(strategy, dsl_state)

Callback implementation for AshAuthentication.Strategy.Custom.verify/2.