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, groupsystem: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
| Method | Set with | Who uses it | Ends when |
|---|---|---|---|
| X.509 client cert | --client- | break-glass | at expiry, or rotate the CA |
| ServiceAccount token | --service- | Pods | bound ones die with their Pod or Secret |
| Bootstrap token | --enable- | node join | delete the token Secret |
| Static token file | --token- | not recommended | edit the file, restart |
| OIDC / JWT | --oidc-* or --authentication- | people | at exp. No revocation |
| Webhook | --authentication- | a service | after the cache TTL (2m) |
| Authenticating proxy | --requestheader- | a front proxy | at 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,nbfchecked too
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}/, checks offline. Issuer : https, not --service- (fatal, 1.30+).
4.One kubectl request
- kubectl runs the exec plugin named in kubeconfig.
- kubelogin returns a cached ID token, refreshes it, or opens a browser login.
- kubectl sends
Authorization: Bearer <id_token>. - The authenticator matches
iss, checks the signature with cached JWKS, thenaudandexp. - Claims become username, groups, uid and extra, with prefixes.
- RBAC allows it, or the request is authenticated but
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:mastersskips RBAC and cannot be revoked short of rotating the CA. Keep it offline.
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.
1.Flags or a file, never both
- Legacy
--oidc-*flags : supported, not deprecated. One issuer, one audience. --authentication-:config AuthenticationConfigurationinapiserver., GA since 1.34, gate removed in 1.37.config. k8s.io/ v1
- Any
--oidc-*flag plus any config file, even one with onlyanonymous, stops the API server : mutually exclusive. - The removed
Structuredgate on 1.37 : unrecognized feature gate.Authentication Configuration
| Topic | Flags | File |
|---|---|---|
| Issuers, audiences | one each, audience = --oidc- | up to 64 issuers; many audiences with MatchAny |
| Username prefix | <issuer># unless the claim is email; - disables | no default : prefix required with claim |
| Claim rules, maps | --oidc-; claim names only | claim or CEL, plus uid, extra |
| Change | restart the API server | hot reload |
| Signing algs | --oidc-, default RS256 | all known algs (RS, ES, PS) |
| IdP CA | --oidc- (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
- CEL :
claimsin claim rules and mappings,userin user rules. An empty username fails. - Prefixes stop IdP
system:names and clashes. File : no defaulting,prefix: ""= none. - Flags,
--oidc-unset, claim notusername- prefix email:<issuer>#(<claim value> subdefault). Groups prefix : no default (notoidc:as the CLI docs say). - Email (1.33) :
claims.emailin the username needsclaims.in it, an extra or a claim rule :email_verified 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.
anonymouscannot change. Write atomically.- 10s success cache : a token works up to 10s after a reload.
Check apiserver_ (kubectl get --raw /metrics).
5.On k3s
- File on every server node, mode 0600.
- In
/etc/, a list item underrancher/ k3s/ config.yaml kube-:apiserver- arg - authentication-.config=<path> - Drop
oidc-*entries and the oldStructuredgate.Authentication Configuration systemctl restart k3sonce; later edits reload.- Keep an
anonymousblock : with this flag k3s dropsanonymous-, so anonymous is enabled.auth=false
Never the k3s ServiceAccount issuer https://.
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
ExecCredentialwithstatus.tokenandexpirationTimestamp. 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(or18000). Cache :~/.kube/(disk; keyring optional).cache/ oidc-login
- IdP client : public with PKCE, no secret on laptops. Register
http://andlocalhost:8000 http://exactly.localhost:18000 - Ask for the
groupsscope; its mapper : Keycloak.
3.RBAC for OIDC groups
- Bind
kind: Groupwith 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
| Situation | What happens | What to do |
|---|---|---|
| Logout | works until exp, plus the 10s cache | short tokens, end the IdP session, oidc-login clean |
| Removed from a group | takes effect at the next refresh | keep tokens short |
| IdP down | issued tokens work; logins, refreshes fail | a break-glass cert, offline |
| API server up before the IdP | tokens fail, oidc: authenticator not initialized, 10s retries | wait : 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(httpsonly, keys still fromjwks_uri) does not fix it cheaply.
5.Commands
| Command | Does |
|---|---|
kubectl auth whoami | who the API server thinks you are |
kubectl auth can-i list pods --as=oidc:alice --as-group=oidc:k8s-viewers | test 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 clean | delete the local token cache (disk, keyring) |
curl -s <issuer>/ | check issuer and jwks_uri |
kubectl auth whoami. Tokens cannot be revoked : keep them short, keep a break-glass cert.