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"}]
endUsage
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"
]
endThe 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, "")
endKubernetesServiceAccount.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 | |
|---|---|---|
| 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
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.