Kubernetes OIDC Authentication and RBAC Integration Design via Keycloak Identity Broker

This document details the design procedures and troubleshooting steps for configuring Keycloak as an OIDC identity broker to decouple direct binding to the Kubernetes API server while establishing fine-grained RBAC based on group claims.

In Kubernetes cluster operations, organizational growth demands single sign-on (SSO) integration between kubectl and multiple existing Identity Providers (such as Azure AD or Authentik). However, architectures that directly bind the kube-apiserver of each control plane to an upstream IdP cause IdP schema changes or tenant migrations to directly trigger reconfigurations across all clusters, leading to configuration sprawl and increased operational overhead.

To address this issue, an architecture is established that introduces Keycloak as an intermediate OpenID Connect (OIDC) identity broker, decoupling the authentication infrastructure from the control plane. This article outlines the procedure from configuring kube-apiserver OIDC flags to transparent group claim parsing, applying fine-grained RBAC policies, and verification steps.

1. Control Plane kube-apiserver OIDC Integration Configuration

To validate JWT tokens on the Kubernetes API server, add the OIDC authentication parameters to /etc/kubernetes/manifests/kube-apiserver.yaml on all control plane nodes. Updating the static Pod manifest will automatically restart the kube-apiserver Pod.

spec:
  containers:
  - command:
    - kube-apiserver
    - --oidc-issuer-url=https://keycloak.example.local/realms/kubernetes
    - --oidc-client-id=kubernetes
    - --oidc-username-claim=preferred_username
    - --oidc-groups-claim=groups
    - --oidc-ca-file=/etc/kubernetes/pki/keycloak-ca.crt

If Keycloak is operated under an internal private Certificate Authority (CA), the corresponding CA certificate must be placed at /etc/kubernetes/pki/keycloak-ca.crt on all control plane nodes. If the certificate path is incorrect, the kube-apiserver initialization process will halt.

2. Upstream Group Claim Propagation Configuration

To prevent manual dual management of user groups in Keycloak, group information issued by the upstream IdP is passed directly through to the JWT. Configuration must be synchronized across three layers.

Layer 1: Upstream IdP Group Serialization (Authentik Example)

Define a custom scope expression on the upstream IdP to sanitize group attributes into a comma-separated string or array format.

return ",".join([group.name for group in request.user.ak_groups.all()])

Layer 2: Keycloak Identity Provider Scope Configuration

In the Keycloak Admin Console, navigate to Identity Providers -> select the relevant Provider -> Advanced Settings -> Scopes and specify the following:

profile email groups

Layer 3: Keycloak Client Protocol Mapper Configuration

Add a Mapper under the kubernetes client settings to convert the incoming groups attribute to the outgoing JWT groups claim (JSON Array format).

3. Client-Side Authentication and Token Verification via kubelogin

On terminals operating in headless environments or via command-line interface, perform authentication via OAuth 2.0 Device Code Flow using the kubelogin plugin.

# Install and place the binary
curl -LO https://github.com/int128/kubelogin/releases/latest/download/kubelogin_linux_amd64.zip
unzip kubelogin_linux_amd64.zip
sudo mv kubelogin /usr/local/bin/kubectl-oidc_login

Execute token retrieval and payload decoding verification using the Device Code Flow.

kubectl oidc-login get-token \
  --oidc-issuer-url=https://keycloak.example.local/realms/kubernetes \
  --oidc-client-id=kubernetes \
  --oidc-client-secret=<client_secret> \
  --oidc-extra-scope=groups \
  --certificate-authority=./keycloak-ca.crt \
  --grant-type=device-code \
  | jq -r '.status.token' | cut -d. -f2 | base64 -d 2&gt;/dev/null \
  | jq '{preferred_username, groups}'

Expected extracted result:

{
  "preferred_username": "[email protected]",
  "groups": [
    "k8s-dev"
  ]
}

4. Fine-Grained RBAC Policy Definition

Access permissions are segregated based on the acquired groups claim. This design adopts a two-layer structure: k8s-admin (full privileges) and k8s-dev (read-only access restricted to specific namespaces and Node read access).

4.1 ClusterRoleBinding for Cluster Administrators

kubectl create clusterrolebinding oidc-k8s-admin \
  --clusterrole=cluster-admin \
  --group=k8s-admin

4.2 Namespace-Restricted Role / RoleBinding for Developers

Manifest granting read-only permissions exclusively within the development namespace team-a.

apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: namespace-viewer
  namespace: team-a
rules:
- apiGroups: ["", "apps", "batch"]
  resources: ["*"]
  verbs: ["get", "list", "watch"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: k8s-dev-viewer
  namespace: team-a
subjects:
- kind: Group
  name: k8s-dev
  apiGroup: rbac.authorization.k8s.io
roleRef:
  kind: Role
  name: namespace-viewer
  apiGroup: rbac.authorization.k8s.io

4.3 Node Resource Read Permission Segregation for Developers

Because Node is a non-namespaced resource, a cluster-level ClusterRole and ClusterRoleBinding are required.

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: node-viewer
rules:
- apiGroups: [""]
  resources: ["nodes"]
  verbs: ["get", "list", "watch"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: k8s-dev-node-viewer
subjects:
- kind: Group
  name: k8s-dev
  apiGroup: rbac.authorization.k8s.io
roleRef:
  kind: ClusterRole
  name: node-viewer
  apiGroup: rbac.authorization.k8s.io

5. Client Kubeconfig Configuration and Auditing via SelfSubjectAccessReview

To maintain automatic authentication on developer workstations, configure kubeconfig using the Exec credential plugin format.

# 1. Register cluster connection configuration
kubectl config set-cluster my-k8s \
  --server=https://api.k8s.example.local:6443 \
  --certificate-authority=./cluster-ca.crt

# 2. Configure exec credential plugin
kubectl config set-credentials oidc-user \
  --exec-api-version=client.authentication.k8s.io/v1beta1 \
  --exec-command=kubectl \
  --exec-arg=oidc-login --exec-arg=get-token \
  --exec-arg=--oidc-issuer-url=https://keycloak.example.local/realms/kubernetes \
  --exec-arg=--oidc-client-id=kubernetes \
  --exec-arg=--oidc-extra-scope=groups \
  --exec-arg=--grant-type=device-code

# 3. Bind context
kubectl config set-context my-k8s --cluster=my-k8s --user=oidc-user
kubectl config use-context my-k8s

Verify permission evaluation behavior using the SelfSubjectAccessReview API.

curl -sk https://api.k8s.example.local:6443/apis/authorization.k8s.io/v1/selfsubjectaccessreviews \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "apiVersion": "authorization.k8s.io/v1",
    "kind": "SelfSubjectAccessReview",
    "spec": {
      "resourceAttributes": {
        "namespace": "kube-system",
        "verb": "get",
        "resource": "pods"
      }
    }
  }' | jq '.status.allowed'

Troubleshooting

Common failure patterns and their solutions during identity broker configuration are summarized below.

1. Infinite Redirect Loop Behind a Reverse Proxy

This occurs in environments where TLS is terminated at a load balancer or reverse proxy, causing Keycloak to fail to recognize proxy headers, treat requests as HTTP context, and strip Secure cookie attributes. When using the Gateway API, inject the X-Forwarded-Proto header using an HTTPRoute resource.

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: keycloak-route
  namespace: keycloak
spec:
  rules:
  - filters:
    - type: RequestHeaderModifier
      requestHeaderModifier:
        set:
        - name: X-Forwarded-Proto
          value: https
        - name: X-Forwarded-Port
          value: "443"

2. The groups Claim in the Token is null

This is caused by missing the groups scope in the request, or an array conversion mismatch in the Keycloak protocol mapper. Either join group names into a string on the Authentik side before sending, or enable the Multivalued option in Keycloak’s Mapper settings.

3. PKIX Path Building Failed Error

This occurs during upstream IdP certificate verification when intermediate CA certificates are not registered in the Keycloak truststore. The issuing root or intermediate CA certificate must be imported into Keycloak instead of the server certificate.

Operational Verification Protocol Logs

Example log outputs for Pod health and API response verification on a control plane node.

$ kubectl get pod -n kube-system -l component=kube-apiserver
NAME                                         READY   STATUS    RESTARTS   AGE
kube-apiserver-control-plane-01              1/1     Running   0          4m12s

$ curl -skI https://api.k8s.example.local:6443/livez
HTTP/2 200 
content-type: text/plain; charset=utf-8
x-content-type-options: nosniff
date: Sun, 15 Nov 2026 10:15:30 GMT

Operational Notes

💡 Architectural Decoupling: By deploying Keycloak as an intermediate broker, zero reconfiguration is required on the Kubernetes control plane side even when migrating upstream IdPs.

⚠️ Claim Propagation Consistency: For successful groups claim propagation, the scope definition on the IdP side, the protocol mapping in Keycloak, and the flag definitions in kube-apiserver must match precisely across all three locations.

🛠️ Explicit Segregation of Cluster-Scoped Resources: Read permissions for non-namespaced cluster resources such as Node strictly require explicit definitions of ClusterRoleBinding rather than namespace-specific Role objects.

</client_secret>

Built with Hugo
Theme Stack designed by Jimmy
Privacy Policy Disclaimer Contact