Identity and trust

OIDC Authentication for the API Server

1.No users, only strings

  • Kubernetes has no user objects. Every authenticator returns four attributes : username, UID, groups, extra. They mean nothing until RBAC matches them.
  • Success adds group system:authenticated. Anonymous : system:anonymous, group system:unauthenticated.
  • First success wins; the API server does not guarantee the order. Docs : ServiceAccount tokens plus at least one method for people.
  • See RBAC, API Machinery. Workloads : SPIFFE.

2.Ways in, and when each one ends

MethodSet withWho uses itEnds when
X.509 client cert--client-ca-filebreak-glassat expiry, or rotate the CA
ServiceAccount token--service-account-*Podsbound ones die with their Pod or Secret
Bootstrap token--enable-bootstrap-token-authnode joindelete the token Secret
Static token file--token-auth-filenot recommendededit the file, restart
OIDC / JWT--oidc-* or --authentication-configpeopleat exp. No revocation
Webhook--authentication-token-webhook-config-filea serviceafter the cache TTL (2m)
Authenticating proxy--requestheader-client-ca-filea front proxyat the proxy

X.509 : CN = user, each O = a group. v1.37 has no certificate revocation. Issuing them : cert-manager, Private PKI.

3.What an ID token is

  • issequals the issuer URL exactly, trailing slash too
  • subthe subject : stable but opaque
  • audone entry must match an audience
  • expexpiry; iat, nbf checked too
ID token, not access token

kubelogin sends the id_token; its aud is the client id. A Keycloak access token usually shows aud: account, so it fails the audience check. See Keycloak.

Also mapped : email, preferred_username, groups. IdP-signed; the API server caches the jwks_uri keys from {issuer}/.well-known/openid-configuration, checks offline. Issuer : https, not --service-account-issuer (fatal, 1.30+).

4.One kubectl request

  1. kubectl runs the exec plugin named in kubeconfig.
  2. kubelogin returns a cached ID token, refreshes it, or opens a browser login.
  3. kubectl sends Authorization: Bearer <id_token>.
  4. The authenticator matches iss, checks the signature with cached JWKS, then aud and exp.
  5. Claims become username, groups, uid and extra, with prefixes.
  6. RBAC allows it, or the request is authenticated but Forbidden.

Then Admission. The login itself : Keycloak.

kubectl kubelogin token cache exec id_token only with no refreshable token browser login at IdP code + PKCE Bearer id_token API server match iss, verify with JWKS check aud, exp claims to user, groups no call to the IdP per request cached keys RBAC allowed 403 Forbidden

5.Why OIDC for people

  • One identity per person, groups managed in the IdP, short-lived tokens.
  • Not a shared admin cert : k3s's CN=system:admin, O=system:masters skips RBAC and cannot be revoked short of rotating the CA. Keep it offline.
Seen in practice

No OIDC at the API server: people use a client-cert context, and SSO users reach RBAC only through a web UI that impersonates their email and groups. Pitfall : empty claims make the UI act as its own ServiceAccount, often cluster-admin. Do better : validate claims with CEL before impersonating, and keep client certs for break-glass.

In short : The API server never logs anyone in. It checks a signed ID token against the issuer's keys, turns its claims into a username and groups, and RBAC decides what they may do.

1.Flags or a file, never both

  • Legacy --oidc-* flags : supported, not deprecated. One issuer, one audience.
  • --authentication-config : AuthenticationConfiguration in apiserver.config.k8s.io/v1, GA since 1.34, gate removed in 1.37.
  • Any --oidc-* flag plus any config file, even one with only anonymous, stops the API server : mutually exclusive.
  • The removed StructuredAuthenticationConfiguration gate on 1.37 : unrecognized feature gate.
TopicFlagsFile
Issuers, audiencesone each, audience = --oidc-client-idup to 64 issuers; many audiences with MatchAny
Username prefix<issuer># unless the claim is email; - disablesno default : prefix required with claim
Claim rules, maps--oidc-required-claim; claim names onlyclaim or CEL, plus uid, extra
Changerestart the API serverhot reload
Signing algs--oidc-signing-algs, default RS256all known algs (RS, ES, PS)
IdP CA--oidc-ca-file (a path)certificateAuthority (PEM), see Private PKI

2.A minimal v1 file

apiVersion: apiserver.config.k8s.io/v1
kind: AuthenticationConfiguration
anonymous:
  enabled: true
  conditions: [{path: /livez},
    {path: /readyz}, {path: /healthz}]
jwt:
- issuer:
    url: https://auth.example.com/realms/demo
    audiences: [kubernetes]
  claimValidationRules:
  - expression: 'claims.azp == "kubernetes"'
  claimMappings:
    username: {claim: preferred_username,
               prefix: "oidc:"}
    groups: {claim: groups, prefix: "oidc:"}
    uid: {claim: sub}
  userValidationRules:
  - expression: "!user.username.startsWith('system:')"
    message: no system names

apiserver.k8s.io is the wrong group : no kind "AuthenticationConfiguration" is registered. username.claim: email rejects a token with email_verified: false.

3.Claims to user

JWT claims claimValidationRules claimMappings username, groups, uid, extra + prefix userValidationRules UserInfo RBAC false 401 false 401
  • CEL : claims in claim rules and mappings, user in user rules. An empty username fails.
  • Prefixes stop IdP system: names and clashes. File : no defaulting, prefix: "" = none.
  • Flags, --oidc-username-prefix unset, claim not email : <issuer>#<claim value> (sub default). Groups prefix : no default (not oidc: as the CLI docs say).
  • Email (1.33) : claims.email in the username needs claims.email_verified in it, an extra or a claim rule : claims.?email_verified.orValue(true) == true.

4.Reload

  • Bad parse or validation : the old config stays.
  • A valid file applies once every new issuer answers discovery within 1 minute, else failed to update authentication config.
  • anonymous cannot change. Write atomically.
  • 10s success cache : a token works up to 10s after a reload.

Check apiserver_authentication_config_controller_automatic_reloads_total{status="failure"} (kubectl get --raw /metrics).

5.On k3s

  1. File on every server node, mode 0600.
  2. In /etc/rancher/k3s/config.yaml, a list item under kube-apiserver-arg : - authentication-config=<path>.
  3. Drop oidc-* entries and the old StructuredAuthenticationConfiguration gate.
  4. systemctl restart k3s once; later edits reload.
  5. Keep an anonymous block : with this flag k3s drops anonymous-auth=false, so anonymous is enabled.

Never the k3s ServiceAccount issuer https://kubernetes.default.svc.<cluster-domain>.

In short : Flags or the file, never both. The file maps claims with CEL, needs explicit prefixes and reloads once the issuer answers. On k3s it goes in kube-apiserver-arg with its own anonymous block.

1.Exec credential plugins

  • kubeconfig users[].user.exec : command, apiVersion (client.authentication.k8s.io/v1), args, installHint, provideClusterInfo.
  • interactiveMode (Never, IfAvailable, Always) is required in v1.
  • The plugin prints an ExecCredential with status.token and expirationTimestamp. kubectl caches it until expiry or a 401.

kuberc credentialPluginPolicy: Allowlist (entries keyed command; name deprecated in 1.36) refuses other plugins.

users:
- name: oidc
  user:
    exec:
      apiVersion: client.authentication.k8s.io/v1
      command: kubectl
      interactiveMode: IfAvailable
      args: [oidc-login, get-token,
        --oidc-issuer-url=<issuer>,
        --oidc-client-id=kubernetes,
        --oidc-extra-scope=groups]

2.kubelogin

  • kubectl oidc-login : int128/kubelogin v1.36.4 (not the AKS tool). Versions do not track Kubernetes.
  • Auth code + PKCE on 127.0.0.1:8000 (or 18000). Cache : ~/.kube/cache/oidc-login (disk; keyring optional).
  • IdP client : public with PKCE, no secret on laptops. Register http://localhost:8000 and http://localhost:18000 exactly.
  • Ask for the groups scope; its mapper : Keycloak.

3.RBAC for OIDC groups

IdP group k8s-viewers groups: "k8s-viewers" + prefix "oidc:" oidc:k8s-viewers ClusterRoleBinding subject kind: Group ClusterRole view Full group path ON "/k8s-viewers" never matches
  • Bind kind: Group with the prefixed name. RBAC rules : RBAC and Service Accounts.
  • Check with kubectl auth whoami : the final username and groups, after prefixes.
$ kubectl auth whoami
ATTRIBUTE   VALUE
Username    oidc:alice
Groups      [oidc:k8s-viewers system:authenticated]

Groups can vanish after a refresh (kubelogin may not resend extra scopes) : run whoami after one too.

4.Operations

SituationWhat happensWhat to do
Logoutworks until exp, plus the 10s cacheshort tokens, end the IdP session, oidc-login clean
Removed from a grouptakes effect at the next refreshkeep tokens short
IdP downissued tokens work; logins, refreshes faila break-glass cert, offline
API server up before the IdPtokens fail, oidc: authenticator not initialized, 10s retrieswait : certs and SA tokens still work
  • The API server process must reach the issuer (host network on k3s). An in-cluster issuer is a bootstrap loop; discoveryURL (https only, keys still from jwks_uri) does not fix it cheaply.

5.Commands

CommandDoes
kubectl auth whoamiwho the API server thinks you are
kubectl auth can-i list pods --as=oidc:alice --as-group=oidc:k8s-viewerstest RBAC for an OIDC identity (impersonation)
kubectl oidc-login setup --oidc-issuer-url=<issuer> --oidc-client-id=<client>log in, print the ID token claims
kubectl oidc-login cleandelete the local token cache (disk, keyring)
curl -s <issuer>/.well-known/openid-configurationcheck issuer and jwks_uri
In short : kubelogin, an exec plugin, caches the ID token. Bind the prefixed group and check with kubectl auth whoami. Tokens cannot be revoked : keep them short, keep a break-glass cert.