Kubernetes Authentication Configuration

Kubernetes Authentication Configuration refers to the concrete set of API server flags, configuration files, and structured configuration objects that determine which authenticators are active on a cluster and how each one is parameterized. Where authentication management is the ongoing practice of operating identity for a cluster, authentication configuration is the specific mechanical surface — command-line flags, YAML files, and API objects — through which that practice is implemented and changed.

Flag-Based Configuration

Legacy Per-Method Flags

Historically, each authenticator is enabled through its own dedicated kube-apiserver flag: --client-ca-file for certificates, --oidc-issuer-url and related --oidc-* flags for OIDC, --token-auth-file for static tokens, and --authentication-token-webhook-config-file for webhook validation. These flags are read once at API server startup, so any change requires a restart of every API server instance in the control plane.

kube-apiserver \
  --client-ca-file=/etc/kubernetes/pki/ca.crt \
  --oidc-issuer-url=https://accounts.example.com \
  --oidc-client-id=kubernetes \
  --oidc-username-claim=email \
  --oidc-groups-claim=groups \
  --authentication-token-webhook-config-file=/etc/kubernetes/webhook-authn.yaml

Limitations of Flag-Based Configuration

Because flags support only a single OIDC issuer and a fixed set of claim mappings, clusters that need to authenticate against multiple identity providers, or apply different claim-to-identity transformations per provider, cannot express that requirement through flags alone.

Structured Authentication Configuration

The AuthenticationConfiguration API

Newer Kubernetes versions support a dedicated AuthenticationConfiguration file, referenced via --authentication-config, which allows multiple JWT-based authenticators (including several OIDC issuers) to be declared in a single structured document, each with its own issuer, audience, and claim-mapping rules, including CEL expressions for advanced claim transformation.

apiVersion: apiserver.config.k8s.io/v1
kind: AuthenticationConfiguration
jwt:
- issuer:
    url: https://accounts.example.com
    audiences: ["kubernetes"]
  claimMappings:
    username:
      claim: email
      prefix: "oidc:"
    groups:
      claim: groups
      prefix: "oidc:"
- issuer:
    url: https://partner-idp.example.org
    audiences: ["k8s-partner"]
  claimMappings:
    username:
      claim: sub

CEL-Based Claim Validation

The structured configuration format supports Common Expression Language rules for validating or transforming claims beyond simple field mapping, such as rejecting tokens whose claims do not satisfy an organizational policy before identity is even established.

Webhook Authenticator Configuration

Kubeconfig-Style Webhook File

The webhook authenticator's configuration file uses the same shape as a kubeconfig, specifying the external service's endpoint and the client certificate the API server should use when calling it, plus an optional cache TTL controlling how long a given token's validation result is reused before re-checking with the webhook.

apiVersion: v1
kind: Config
clusters:
- name: webhook-authn
  cluster:
    server: https://authn.internal/validate
current-context: webhook
contexts:
- name: webhook
  context:
    cluster: webhook-authn

ServiceAccount Token Configuration

Issuer and Signing Key Flags

Service account token issuance is configured independently of the human-facing authenticators, through --service-account-issuer, --service-account-signing-key-file, and --service-account-key-file, which together determine the issuer claim embedded in tokens and the key material used to sign and later verify them.

kube-apiserver \
  --service-account-issuer=https://kubernetes.default.svc \
  --service-account-signing-key-file=/etc/kubernetes/pki/sa.key \
  --service-account-key-file=/etc/kubernetes/pki/sa.pub

Applying Configuration Changes Safely

Rolling Restarts

Because most authentication configuration is read only at process start, applying a change to a highly-available control plane requires restarting each API server instance sequentially, ensuring at least one instance remains serving requests throughout the rollout to avoid an availability gap.

Staged Rollout of Trust Material

When introducing a new OIDC issuer, a new CA, or new signing keys, configuring the API server to accept both the old and new trust material simultaneously during a transition period avoids invalidating credentials issued under the previous configuration before clients have had a chance to obtain new ones.

Validating Configuration Before Rollout

Testing a new AuthenticationConfiguration file against a non-production API server instance, or using the API server's built-in validation on startup, catches malformed claim mappings or unreachable OIDC issuers before they cause an outage on the production control plane.