Agent identity

The agent identity plane authenticates the agent making each hop. KAOS selects one actor-token issuer through security.agentAuth.identity.provider: serviceaccount, oidc, or aib. Every issuer must mint a JWT for the kaos-gateway audience.

ServiceAccount issuer

serviceaccount is the zero-dependency default. The operator creates an owned Kubernetes ServiceAccount for each Agent and mounts a projected token at /var/run/secrets/kaos-agent/token. AGENT_AUTH_TOKEN_FILE points the runtime to that path.

Kubelet mints and rotates the short-lived projected token. The runtime reads the file whenever it needs the actor token, so it sees rotated tokens without restarting. The token subject has the form system:serviceaccount:<namespace>:<serviceaccount-name>.

At startup, the operator discovers the Kubernetes issuer and JWKS from the API server. Gateway SecurityPolicy resources use localJWKS with those inline keys and require the kaos-gateway audience.

AIB issuer

aib uses the public Agentic Identity Broker as the actor-token issuer. The operator registers each Agent with AIB and writes its client id and client secret to a per-agent Secret. Agent pods receive the provider-neutral AGENT_AUTH_CLIENT_ID, AGENT_AUTH_CLIENT_SECRET_FILE, and AGENT_AUTH_TOKEN_ENDPOINT settings.

The runtime uses OAuth client_credentials to obtain a short-lived actor token. It caches the token until refresh is needed, rereads the mounted client-secret file so Secret rotation is visible, and refreshes and retries once after a gateway 401. AIB owns credential and token issuance; it does not make resource authorization decisions.

The configured AIB issuer is the token iss value used by all verifiers. The operator reads RFC 8414 metadata from /.well-known/oauth-authorization-server, requires its issuer to match exactly, and uses the advertised jwks_uri. Gateway SecurityPolicy resources require the kaos-gateway audience.

Public AIB v0.1.8 requires every Agent to reference a permission set. When KAOS installs the chart, the CLI idempotently seeds a scope-less kaos-identity-placeholder service and kaos-identity permission set. The operator attaches that set as mandatory. This bridge is identity-only and can be removed once AIB accepts agents without permission sets.

For local development, check out AIB at tag v0.1.8 and install with --aib-chart-path agentic-identity-broker/charts/agentic-identity-broker --aib-values operator/config/aib/values-dev.yaml. Those values use the published GHCR broker and migration images and contain fixed development keys; do not use them in production.

OIDC issuer

oidc provides agent OAuth identity through RFC 7591/7592 Dynamic Client Registration (DCR). Select it with --agent-auth-enabled keycloak; add --user-auth-enabled keycloak when Keycloak should also provide user identity.

The operator registers one confidential OAuth client per Agent, stores the returned client id, client secret, and registration metadata in a per-agent Secret, and delivers the provider-neutral token endpoint and credential settings to the Agent pod. The runtime uses client_credentials to obtain short-lived actor tokens for the kaos-gateway audience. An Agent finalizer keeps the owned credential Secret available during deletion; the operator sends the RFC 7592 client deletion first, removes the Secret second, and only then releases the Agent for garbage collection.

DCR needs one manual bootstrap step: create an initial access token in Keycloak and place it in the configured Secret before the operator starts. The CLI prints the exact command during installation, for example:

kubectl create secret generic kaos-oidc-registration \
  -n kaos-system --from-literal=token=<token>

The Secret name and key come from security.agentAuth.identity.oidc.registration.initialAccessTokenSecretRef. The operator pod remains pending until the Secret exists; the bootstrap credential is not created by KAOS.

Actor identity data

The operator publishes issuer data in the policy ConfigMap:

• data.kaos.jwks maps the exact actor-token issuer to its JWKS. The PDP selects this entry from iss and verifies the signature, exact issuer, RS256 algorithm, and kaos-gateway audience.
• data.kaos.agents maps a logical actor id such as kaos://agent/demo/researcher to its issuer-specific identity and autonomous status. ServiceAccount tokens use issuer_sub. Keycloak client-credentials tokens carry the DCR client_id in azp and a separate service-account UUID in sub, so OIDC mappings use issuer_azp. This resolves a verified token to the KAOS actor used by authorization and controls whether the Agent may self-subject.

ServiceAccount subjects require this mapping because their Kubernetes subject is not a KAOS resource id. Issuers that use the logical actor id directly as sub can be resolved without a mapping when no agent map is present.

The agent sends its token on every protected hop:

x-agent-authorization: Bearer <actor-jwt>

The runtime replaces the actor identity at each agent hop with the current agent's own token. The user subject, when present, is propagated independently.