OIDC login for kubectl

The problem with shared kubeconfigs

Handing out copies of admin.conf means: no individual accountability, no MFA, no offboarding (the cert keeps working), and cluster-admin for everyone. OIDC fixes all four.

How the flow works

you ──kubectl──► kubelogin ──browser──► IdP (Keycloak / Dex / Entra / Okta): password + MFA
                     ◄──────── ID token (signed JWT: email, groups, expiry) ───────
kubectl ──Bearer <ID token>──► API server: checks signature, issuer, audience, expiry
                                          → user "oidc:asha@example.com", groups ["oidc:platform-admins"]
                                          → RBAC decides

Step 1: the identity provider

In Keycloak (as an example):

1. Create a realm, e.g. platform.
2. Create a client kubernetes (OpenID Connect, public client or confidential; allow http://localhost:8000 as a redirect URI for kubelogin).
3. Add a "Group Membership" mapper to the client with token claim name groups (full group path off), so tokens carry groups.
4. Create groups (platform-admins, developers) and users, and enable MFA (OTP or WebAuthn) in the realm's authentication flow.

The issuer URL is then https://sso.example.com/realms/platform. Dex is a lighter alternative that federates to GitHub, LDAP, SAML or another OIDC provider.

Step 2: the API server

Add the OIDC flags to kube-apiserver (on kubeadm, via apiServer.extraArgs in the cluster configuration, or by editing the static pod manifest):

--oidc-issuer-url=https://sso.example.com/realms/platform
--oidc-client-id=kubernetes
--oidc-username-claim=email
--oidc-username-prefix=oidc:
--oidc-groups-claim=groups
--oidc-groups-prefix=oidc:

The issuer must be reachable over HTTPS from the API server with a certificate it trusts (add --oidc-ca-file for a private CA). Recent Kubernetes versions also offer a structured authentication configuration file that can trust several issuers and map claims with CEL. Prefer it on new clusters where your version supports it.

Step 3: RBAC for IdP groups

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: oidc-platform-admins
subjects:
  - kind: Group
    name: "oidc:platform-admins"          # prefix + IdP group name
    apiGroup: rbac.authorization.k8s.io
roleRef:
  kind: ClusterRole
  name: cluster-admin
  apiGroup: rbac.authorization.k8s.io
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: oidc-developers-edit
  namespace: shop
subjects:
  - kind: Group
    name: "oidc:developers"
    apiGroup: rbac.authorization.k8s.io
roleRef:
  kind: ClusterRole
  name: edit
  apiGroup: rbac.authorization.k8s.io

Joining or leaving the developers group in the IdP now changes cluster access, with no YAML change.

Step 4: kubectl with kubelogin

Install kubelogin (for example with kubectl krew install oidc-login), then add a user that runs it:

users:
  - name: oidc
    user:
      exec:
        apiVersion: client.authentication.k8s.io/v1beta1
        command: kubectl
        args:
          - oidc-login
          - get-token
          - --oidc-issuer-url=https://sso.example.com/realms/platform
          - --oidc-client-id=kubernetes
        interactiveMode: IfAvailable

$ kubectl --user=oidc get pods -n shop      # opens the browser once; token cached and refreshed
$ kubectl --user=oidc auth whoami
ATTRIBUTE   VALUE
Username    oidc:asha@example.com
Groups      [oidc:developers system:authenticated]

Now the kubeconfig you share contains no secrets: just the cluster address and how to log in.

Recap

• OIDC: the IdP authenticates (password + MFA), Kubernetes validates the token and applies RBAC.
• API server: --oidc-issuer-url, --oidc-client-id, username/groups claims and prefixes (or the structured config file).
• Bind IdP groups in RBAC; access follows group membership.
• kubelogin handles the browser login and tokens; kubeconfigs contain no secrets.