---
title: "OIDC Provider Setup for Kubernetes | Hostman Docs"
description: "See how to set up OIDC provider with Hostman’s step-by-step guide. Learn secure identity and access management integration."
---

> For the complete documentation index for AI agents, see [llms.txt](https://hostman.com/llms.txt).

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**:

![2d16ba1e 08c3 455d 9fa4 2a37be0b84a4](https://content.hostman.com/assets/567b9a59-b091-4e4d-80f8-db71c08afc16.png?width=624&height=664)

Or later via the **Management** section:

![7501ec4f A753 4e3c 8311 82d35b2e4801](https://content.hostman.com/assets/b3d6331e-4dd7-41aa-a9f2-ab32f37bd791.png?width=1383&height=869)

During setup, specify the following values:

-   **Connection Name** (required): The display name for the connection, shown only in the dashboard, 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:

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

Unzip the archive:

```shell
unzip kubelogin_linux_amd64.zip
```

Make the binary executable:

```shell
chmod +x kubelogin
```

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

```shell
sudo mv kubelogin /usr/local/bin/
```

#### macOS

Install with Homebrew:

```shell
brew install kubelogin
```

#### Windows

Install with Chocolatey:

```shell
choco install kubelogin
```

#### Krew

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

```shell
kubectl krew install oidc-login
```

## Getting a Token

Run the following command:

```shell
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:

```shell
{"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:

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

Example output:

```shell
 {
  "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](https://kubernetes.io/docs/reference/access-authn-authz/rbac/).

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

```yaml
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:

```shell
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:

```yaml
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 dashboard, Kubernetes will use it as the username. In this case, you can simplify `subjects.name` and use a readable name, for example:

```yaml
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:

```shell
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:

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

Verify:

```shell
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`:

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

## Disabling the OIDC Provider

To disable the OIDC provider:

1.  Go to the Kubernetes section
2.  Click on the cluster and go to the **Management** tab.
3.  Click **Edit** next to the **OIDC provider**.
4.  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:

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

To delete them:

```shell
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 dashboard.