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.
You can configure the OIDC provider when creating a cluster in the step 5. Addons:
Or later via the Management section:
During setup, specify the following values:
https://<domain>/realms/<realm>
for Keycloakhttps://accounts.google.com
for Googlesub
, preferred_username
, or email
).After entering the necessary parameters, click Save.
The kubelogin utility is used to obtain an ID token from the provider and pass it to Kubernetes when executing commands via kubectl
.
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/
Install with Homebrew:
brew install kubelogin
Install with Chocolatey:
choco install kubelogin
If you use Krew, kubectl
plugin manager, run the command:
kubectl krew install oidc-login
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
).
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-провайдера#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-провайдера#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
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…
To disable the OIDC provider:
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.