Kubernetes on Abhinav Praveen's Blog

Using OIDC Authentication with Kubernetes, Keycloak and the OAuth 2.0 Device Authorization Grant

Sat, 14 Mar 2026 16:53:37 +0000

Intro

This page is an alternative/extension of my previous post which describes how to use the Device Authorization Grant with Kubernetes & Keycloak. With this approach the usage flow is as follows:

The user runs a token.sh script
The script prints a link to the Identity Provider for the user to click
The user clicks the link and permits information to be passed to the scripts
The script sets the identity token and refresh token in kubectl’s configuration
Future invocations of kubectl renew the ID Token with the Refresh Token if possible

This has been tested with RKE2 v1.35.1, kubectl 1.34.1, curl, jq, an Keycloak (v26.5.4) but this should work for any standard compliant Identity Provider.

Kubernetes API Server

Setting up the API Server is the same as before

The relevant documentation for this is: Authentication. I will assume that the StructuredAuthenticationConfiguration Kubernetes feature gate is enabled. This has been the default since Kubernetes v1.30.

Write an AuthenticationConfiguration like the following

apiVersion: apiserver.config.k8s.io/v1
kind: AuthenticationConfiguration
jwt:
- issuer:
 url: https://idp.example.com
 audiences:
 - k8s
 audienceMatchPolicy: MatchAny
 claimMappings:
 username:
 claim: upn
 prefix: "oidc:"
 groups:
 claim: groups
 prefix: "oidc:"
 uid:
 claim: sub
 userValidationRules:
 - expression: "!user.username.startsWith('system:')"
 message: 'username cannot used reserved system: prefix'
 - expression: "user.groups.all(group, !group.startsWith('system:'))"
 message: 'groups cannot used reserved system: prefix'

Here make sure that:

The OpenID Connect .well-known/openid-configuration endpoint is immediately above the issuer URL (i.e. at https://idp.example.com/.well-known/openid-configuration). In Keycloak’s case, I have a realm called ‘machine’ so my well-known would be at: https://idp.example.com/realms/machine/.well-known/openid-configuration. That means that my issuer URL should be: https://idp.example.com/realms/machine.
Your Identity Provider is able to issue client ID Tokens with an audience of k8s or change it to if different audience if needed.
Your Identity Provider is able to provide a groups claim with your ID Token for use as Kubernetes groups. This may vary by Identity Provider.

Write the AuthenticationConfiguration to a file somehwere, say /path/to/authconf.yaml and start the Kubernetes API Server referring to it with: --authentication-config=/path/to/authconf.yaml

Client

Here, unlike the previous post, create a public client (i.e. one that does not have a client secret). The only authentication flow enabled should be the OAuth 2.0 Device Authorization Grant. The client ID should normally be the same as one of the audiences items in the configuration above – I will assume that it is k8s. Keycloak will insert this as the aud claim. Finally, set up the clients scopes so that issued ID Tokens contains a sub claim, upn claim, and a groups claim. On Keycloak, this can be done by assigning the predefined basic and microprofile-jwt scopes.

Token Fetch Script

A rough script to facilitate the device authorization flow is below:

#!/bin/bash
CACHE=/run/user/$(id -u)/k8s-oauth-cache
mkdir -p "$CACHE"

device_req() {
 curl -s -d client_id=k8s -d scope="openid basic microprofile-jwt" https://idp.example.com/realms/REALMNAME/protocol/openid-connect/auth/device
}

device_obt() {
 jq -r .device_code "$CACHE/device" | awk '{print "device_code="$1}' | curl -s -d grant_type="urn:ietf:params:oauth:grant-type:device_code" -d client_id=k8s --data @- https://idp.example.com/realms/REALMNAME/protocol/openid-connect/token
}

apply() {
 kubectl config set-credentials oidc --auth-provider oidc --auth-provider-arg=idp-issuer-url=https://idp.example.com/realms/REALMNAME --auth-provider-arg=client-id=k8s --auth-provider-arg=refresh-token="$(jq -r .refresh_token "$CACHE/token")" --auth-provider-arg=id-token="$(jq -r .id_token "$CACHE/token")"
 exit "$?"
}

device_req > "$CACHE/device"
INTERVAL="$(jq -r .interval "$CACHE/device")"
echo "Click on:" > /dev/stderr
jq .verification_uri_complete "$CACHE/device" > /dev/stderr
for i in $(seq 1 60)
do
 sleep "$INTERVAL"
 device_obt > "$CACHE/token"
 jq -e .id_token "$CACHE/token" > /dev/null && apply
 jq -e '.error=="slow_down"' "$CACHE/token" > /dev/null && INTERVAL="$((INTERVAL+5))"
done
exit 1

Replace REALMANME with the name of your realm. Don’t forget to make it executable.

`kubectl` Configuration

Finally we write a configuration file for kubectl (normally at ~/.kube/config). This will look similar to:

apiVersion: v1
clusters:
- cluster:
 certificate-authority-data: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
 server: https://kubernetes.default.svc.cluster.local:6443
 name: default
contexts:
- context:
 cluster: default
 user: oidc
 name: default
current-context: default
kind: Config
users:
- name: oidc

Using It

Now you can try the following

token.sh req

If everything is working, you will see a message like:

Click on:
"https://idp.example.com/realms/REALMNAME/device?user_code=XXXX-XXXX"

After clicking on the link and authenticating, your tokens will then be printed. You can then run K8S commands like kubectl auth whoami which will produce output similar to the below:

ATTRIBUTE VALUE
Username oidc:xxxxxxs
UID xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Groups [oidc:xxxxxxxxxxxxxx oidc:xxxxxxxxxxxxxxxxx oidc:xxxxxxxxxxxxxxxxxxxxx system:authenticated]
Extra: authentication.kubernetes.io/credential-id [JTI=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx]

This shows that you’ve inherited a username from the Identity Provider (prefixed with oidc:) and groups from the Identity Provider (prefixed with oidc:). You will need to put RBAC in place to permit your user to do things. I won’t go over that here.

Using OIDC Authentication with Kubernetes

Sun, 08 Mar 2026 01:32:37 +0000

Intro

This is a quick post to go over how you can configure Kubernetes to authenticate clients with OpenID Connect authentication. This has some advantages over alternatives like using X509 Client Certificate verification like:

Revoking old or leaked credentials is easier; just update the client’s client secret
Clients can be centrally managed at your Identity Provider including by providing groups for use in RBAC
You don’t need to modify the CA authority that’s probably already been set up by your Kubernetes distribution

In this post, we’ll do this without using ’non-standard’ tools. We’ll do this by:

Configuring the Kubernetes API Server to communicate with the Identity Provider
Setting up a client with the Identity Provider and storing the client secret locally
Writing a short script to obtain an ID Token from the Identity Provider
Configuring kubectl to call the script to obtain the ID Token

All we’ll need for this is Kubernetes (tested on RKE2 v1.35.1), kubectl (tested with 1.34.1), curl, jq, and an OpenID Connect compliant Identity Provider. This post will be tailored towards Keycloak (v26.5.4) but this should work for any Identity Provider.

Note that if you’re willing to use kubelogin as a kubectl plugin, you would not need to store the client secret locally; instead you would authenticate directly with your Identity Provider in a standard browser flow. You wouldn’t need to write a script to obtain an ID Token either.

Kubernetes API Server

Write an AuthenticationConfiguration like the following

apiVersion: apiserver.config.k8s.io/v1
kind: AuthenticationConfiguration
jwt:
- issuer:
 url: https://idp.example.com
 audiences:
 - k8s
 audienceMatchPolicy: MatchAny
 claimMappings:
 username:
 claim: sub
 prefix: "oidc:"
 groups:
 claim: groups
 prefix: "oidc:"
 uid:
 claim: sub
 userValidationRules:
 - expression: "!user.username.startsWith('system:')"
 message: 'username cannot used reserved system: prefix'
 - expression: "user.groups.all(group, !group.startsWith('system:'))"
 message: 'groups cannot used reserved system: prefix'

Here make sure that:

The OpenID Connect .well-known/openid-configuration endpoint is immediately above the issuer URL (i.e. at https://idp.example.com/.well-known/openid-configuration). In Keycloak’s case, I have a realm called ‘machine’ so my well-known would be at: https://idp.example.com/realms/machine/.well-known/openid-configuration. That means that my issuer URL should be: https://idp.example.com/realms/machine.
Your Identity Provider is able to issue client ID Tokens with an audience of k8s or change it to if different audience if needed.
Your Identity Provider is able to provide a groups claim with your ID Token for use as Kubernetes groups. This may vary by Identity Provider.

Write the AuthenticationConfiguration to a file somehwere, say /path/to/authconf.yaml and start the Kubernetes API Server referring with: --authentication-config=/path/to/authconf.yaml

Client

Note that here we are using a client and not a regular user account on the Identity Provider. This better represents the authentication flow of programmatic authentication (AKA M2M) instead of a human entering a username and password. kubelogin would be a better choice if you wanted to authenticate actual user accounts.

Create a client on your Identity Provider. ‘Client authentication’ or ‘confidential access’ should be turned on. Additionally ‘Service account roles’ or ‘Client Credentials Grant’ should be turned on. Finally, set up the clients scopes so that issued ID Tokens contain a groups claim, a sub claim and an aud (audience) claim with the issuer audiences value from the AuthenticationConfiguration above.

You can do this on Keycloak by assosciating the client with the pre-existing microprofile-jwt scope (providing groups through client service account roles), basic scope, and by creating a custom client scope (named, say, k8s), configuring a new mapper with the “Audience” name and including a custom audience with, in the above example, the value k8s. Assign the k8s client scope to the client you created.

Save the client id and secret for the client; we’ll use them in the next section. I will assume they are respectively $CLIENT_ID and $CLIENT_SECRET. Also note the claims your client needs to get the groups claim and the correct audience. This should also include the standard openid scope. That means that for Keycloak, we have SCOPES=openid microprofile-jwt k8s

Token Fetch Script

The script for this is quite simple. First, go to the Well Known endpoint of your Identity Provider (https://idp.example.com/.well-known/openid-configuration) and find the value for the token_endpoint key. I will assume that it is https://idp.example.com/protocol/openid-connect/token. Now we can write the script:

#!/bin/bash
curl -s -d grant_type=client_credentials -d client_id="$CLIENT_ID" -d client_secret="$CLIENT_SECRET" -d scope="$SCOPES" https://idp.example.com/protocol/openid-connect/token |\
jq '{"status": {"token": .id_token, "expirationTimestamp": (now + .expires_in) | todate}, "apiVersion": "client.authentication.k8s.io/v1", "kind": "ExecCredential"}'

I will assume this script is at /path/to/token.sh. Don’t forget to make it executable.

This script uses a generated ID token to authenticate the Kubernetes API. It it isn’t required by the specification for the Identity Provider (https://datatracker.ietf.org/doc/html/rfc6749#section-4.4) to return an ID token for a Client Credentials flow. KeyCloak does provide an ID token for the above request. If your Identity Provider provides a JWT access token with the correct claims and audience, you can use that instead.

All jq does here is format the ID Token into an ExecCredential object. Using it is nice because it prevents any malicious or accidental JSON syntax breakage but you could remove it if you wanted to. Also, here, we’re writing the client secret to a file. You might prefer to use a different approach to store or cache it (e.g. GPG).

`kubectl` Configuration

Finally we write a configuration file for kubectl (normally at ~/.kube/config). This will look similar to:

apiVersion: v1
clusters:
- cluster:
 certificate-authority-data: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
 server: https://kubernetes.default.svc.cluster.local:6443
 name: default
contexts:
- context:
 cluster: default
 user: oidc
 name: default
current-context: default
kind: Config
users:
- name: oidc
 user:
 exec:
 apiVersion: client.authentication.k8s.io/v1
 command: /path/to/token.sh
 interactiveMode: Never

Using It

Now you can try the following

kubectl auth whoami

If everything is working, you will see output like:

ATTRIBUTE VALUE
Username oidc:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
UID xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Groups [oidc:xxxxxxxxxxxxxx oidc:xxxxxxxxxxxxxxxxx oidc:xxxxxxxxxxxxxxxxxxxxx system:authenticated]
Extra: authentication.kubernetes.io/credential-id [JTI=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx]

Kubernetes on Abhinav Praveen's Blog

Using OIDC Authentication with Kubernetes, Keycloak and the OAuth 2.0 Device Authorization Grant

Intro

Kubernetes API Server

Client

Token Fetch Script

kubectl Configuration

Using It

Using OIDC Authentication with Kubernetes

Intro

Kubernetes API Server

Client

Token Fetch Script

kubectl Configuration

Using It

`kubectl` Configuration

`kubectl` Configuration