OIDC Provider Setup

Last updated June 5, 2025

OpenID Connect (OIDC) is an authentication protocol built on top of OAuth 2.0. It allows you to configure user authentication in a Kubernetes cluster using authentication services such as Google, Keycloak, Dex, GitHub, and others.

Setting Up the OIDC Provider

You can configure the OIDC provider when creating a cluster in the step 5. OIDC Provider:

Or later via the Management section:

During setup, specify the following values:

Connection Name (required): The display name for the connection, shown only in the control panel, does not affect OIDC operation.
Issuer URL (required): The OIDC provider address. For example:
- https://<domain>/realms/<realm> for Keycloak
- https://accounts.google.com for Google
Client ID (required): The client ID registered with the OIDC provider.
Username Claim: Field in the ID token to be used by Kubernetes as the username (e.g., sub, preferred_username, or email).
Groups Claim: Field in the ID token containing the list of user groups. Used for group-based RBAC access control.

After entering the necessary parameters, click Save.

Installing kubelogin

The kubelogin utility is used to obtain an ID token from the provider and pass it to Kubernetes when executing commands via kubectl.

Linux

Download the archive with the latest version of the utility:

curl -LO https://github.com/int128/kubelogin/releases/latest/download/kubelogin_linux_amd64.zip

Unzip the archive:

unzip kubelogin_linux_amd64.zip

Make the binary executable:

chmod +x kubelogin

Move it to a system path so it can be run from any directory:

sudo mv kubelogin /usr/local/bin/

macOS

Install with Homebrew:

brew install kubelogin

Windows

Install with Chocolatey:

choco install kubelogin

Krew

If you use Krew, kubectl plugin manager, run the command:

kubectl krew install oidc-login

Getting a Token

Run the following command:

kubelogin get-token \
  --oidc-issuer-url=https://oidc-provider-address \
  --oidc-client-id=client_id \
  --oidc-client-secret=secret

A browser window will open prompting you to log in. After successful authentication, a token in JSON format will be displayed. For example:

{"kind":"ExecCredential","apiVersion":"client.authentication.k8s.io/v1beta1","spec":{"interactive":false},"status":{"expirationTimestamp":"2025-04-24T08:48:30Z","token":"eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJ3X3AxNzlsdkkzTnltWW01M09GZEpWeDJGeGJ6cGxoX2s5OHVFcmtjRmY4In0.eyJleHAiOjE3NDU0ODQ1MTAsImlhdCI6MTc0NTQ4NDQ1MSwiYXV0aF90aW1lIjoxNzQ1NDg0NDUwLCJqdGkiOiJkNTVmYjkzMy0zY2NlLTRkODYtYTcxZS1lNzc1ODZkN2E2ZGIiLCJpc3MiOiJodHRwczovL2tleWNsb2FrLm5kb2xnaWtoLnNpdGUvcmVhbG1zL21hc3RlciIsImF1ZCI6InRlc3QiLCJzdWIiOiIyY2U5NDk5Ni0zN2NlLTQ1NDEtOGFiOS00ZTk0MWE2YjhmYW123eXAiOiJJRCIsImF6cCI6InRlc3QiLCJub25jZSI6InhuWGNLMTlIVUprRTB0N3BXbVJ6NXJBWC0ya0h4NFpVaGdhbEJ2OW1QsfaiLCJzZXNzaW9uX3N0YXRlIjoiYjZmOWRmNmMtMjNhMS00OGU4LTkwMDQtOWJlYmFmNzY0OGU4IiwiYXRfaGFzaCI6IldocDAtQkdCTmhWNTUwc082eW9wS2ciLCJhY3IiOiIxIiwic2lkIjoiYjZmOWRmNmMtMjNhMS00OGU4LTkwMDQtOWJlYmFmNzY0OGU4IiwiZW1haWxfdmVyaWZpZWQiOmZhbHNlLCJuYW1lIjoidGVzdCB0ZXN0IiwicHJlZmVycmVkX3VzZXJuYW1lIjoidGVzdEBtYWlsLnJ1IiwiZ2l2ZW5fbmFtZSI6InRlc3QiLCJmYW1pbHlfbmFtZSI6InRlc3QiLCJlbWFpbCI6InRlc3RAbWFpbC5ydSJ9.GQjRT_gTjsdfuVwhPYCW5DlqL_pbXpiYItIxNvOs9G8jUldV-3LyntQa4Zf4OSwzKldiJ4wZDRa-8pGI-BwD3SO1RxhkbYm_yTFxXDguxNdjstrFcCfLaslhBPqelpKC7DbsIqSLRIoixihPynIEMhEZRxvlDwZuYmWwyn7zMztQyGHPam_ujICIddcODBDBHA2Ksw_ZNwMAoU0sdMlI3fjTJst_Mh3jgzQRpFctc7X75JCL37HcZ6HBb6_9SWfmKHGO3ivFGs1pKtX6XDay8zt65DaEKM41iTjCzr-nKQ1Qk16fRypgsUauSJp_UHiGMiAUHSz66hQdvUr1uByg"}}

To decode and view the token payload, use:

echo "token" | cut -d '.' -f2 | base64 -d | jq

Example output:

 {
  "exp": 1745480015,
  "iat": 1745479955,
  "auth_time": 1745479955,
  "jti": "4d9d243a-f62d-4150-94eb-5c535d2c0ea8",
  "iss": "https://keycloak.hostman.com/realms/master",
  "aud": "test-user",
  "sub": "2ce94996-37ce-4541-8ab9-4e941a6b8faa",
  "typ": "ID",
  "azp": "test-user",
  "nonce": "ubNzQ6KRI746Ab1WPGG3Z5tONUPDPx-sSud4aLKDlT4",
  "session_state": "e0933444-3a04-4e17-885c-1a7f93e0ebb3",
  "at_hash": "QpL9mrseqRikRIVEhdQrBQ",
  "acr": "1",
  "sid": "e0933444-3a04-4e17-885c-1a7f93e0ebb3",
  "email_verified": false,
  "name": "Hostman",
  "preferred_username": "test@example.com",
  "given_name": "test",
  "family_name": "test",
  "email": "test@example.com"
}

The name of the claim you configured as the "Username claim" will appear here (default is sub).

Configuring RBAC

RBAC (Role-Based Access Control) is a mechanism in Kubernetes that manages user permissions. It is used to define which resources a user can view or modify. You can find more details in the official documentation.

To configure RBAC, create a manifest file named oidc-access.yaml with the following content:

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: keycloak-cluster-role
rules:
  - apiGroups: ["*"]
    resources: ["*"]
    verbs: ["*"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: keycloak-cluster-role-binding
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: keycloak-cluster-role
subjects:
  - kind: User
    name: "https://oidc-provider#sub"
    apiGroup: rbac.authorization.k8s.io

Specify the value of the sub field from the token in the name parameter. This will grant full (cluster-admin) access to the specific user authenticated via OIDC.

Apply the manifest:

kubectl apply -f oidc-access.yaml

If you want to grant read-only access to resources, for example, to pods in the default namespace, apply the following manifest:

apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: readonly-pods
  namespace: default
rules:
  - apiGroups: [""]
    resources: ["pods"]
    verbs: ["get", "list", "watch"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: readonly-pods-binding
  namespace: default
roleRef:
  kind: Role
  name: readonly-pods
  apiGroup: rbac.authorization.k8s.io
subjects:
  - kind: User
    name: "https://oidc-provider#sub"
    apiGroup: rbac.authorization.k8s.io

If you specified a “Username claim” with a value such as preferred_username when setting up the OIDC provider in the control panel, Kubernetes will use it as the username. In this case, you can simplify subjects.name and use a readable name, for example:

subjects:
  - kind: User
    name: "test@example.com"
    apiGroup: rbac.authorization.k8s.io

Configuring kubectl to Use OIDC

Add the OIDC user to your kubeconfig to connect to the cluster via OIDC:

kubectl config set-credentials oidc \
  --exec-api-version=client.authentication.k8s.io/v1 \
  --exec-interactive-mode=IfAvailable \
  --exec-command=kubelogin \
  --exec-arg=get-token \
  --exec-arg=--oidc-issuer-url=https://oidc-provider-address \
  --exec-arg=--oidc-client-id=client_id \
  --exec-arg=--oidc-client-secret=secret

Set the current context to use this user:

kubectl config set-context --current --user=oidc

Verify:

kubectl get pods

A browser window will prompt for login. After successful authentication, the command should run without errors. If access is denied, check the RBAC rules.

If everything works fine, you can exclusively use OIDC and disable certificate-based auth. To do this, comment out or remove the certificate credentials from kubeconfig:

# - name: xg60398-1032513
#   user:
# client-certificate-data: LS0tLS1CRUdJTiBD…
# client-key-data: LS0tLS1CRUdJ…

Disabling the OIDC Provider

To disable the OIDC provider:

Go to the Kubernetes section
Click on the cluster and go to the Management tab.
Click Edit next to the OIDC provider.
Click Delete.

After removal, all users authenticated via OIDC will lose access. However, RBAC rules will remain and must be removed manually.

To find linked role bindings:

kubectl get rolebindings --all-namespaces -o yaml | grep -B5 https://oidc-provider-address

To delete them:

kubectl delete clusterrolebinding <name>

To restore access, if kubeconfig was set up for OIDC, revert to the certificate-based authentication settings or download the kubeconfig from the control panel.

Setting Up the OIDC Provider Copy link

Installing kubelogin Copy link