---
title: "Подключение OIDC-провайдера к кластеру Kubernetes"
description: "Подключение OIDC-провайдера к кластеру Kubernetes. Документация и инструкции по использованию и настройке облачных сервисов Timeweb Cloud."
---

> Полный индекс документации для ИИ-агентов: [llms.txt](https://timeweb.cloud/llms.txt).

OpenID Connect (OIDC) — это протокол аутентификации, работающий на основе OAuth 2.0. С его помощью можно настроить авторизацию пользователей в кластере Kubernetes через сервисы аутентификации, такие как Google, Keycloak, Dex, GitHub и другие.

## Настройка OIDC-провайдера

Подключение OIDC-провайдера можно настроить при создании кластера — в разделе «Дополнения»:

![Screenshot 05 27 25 18:34:35](https://content.timeweb.com/assets/b86268c7-3755-41db-a660-d3226e281145.png?width=420&height=623)

Или позже — в разделе «Управление» в панели управления уже созданным кластером. Для настройки нажмите кнопку «Подключить».

![Selection 273](https://content.timeweb.com/assets/8b96f033-819c-4f3d-a85f-b0d510dc8c4e.png?width=1915&height=957)

При настройке укажите значения:

-   **Название подключения** (обязательное поле) — имя подключения, отображается только в панели управления и не влияет на работу OIDC.
-   **Issuer URL** (обязательное поле) — адрес OIDC-провайдера. Обычно это URL вида `https://<домен>/realms/<realm>` для Keycloak или `https://accounts.google.com` для Google. 
-   **Client ID** (обязательное поле) — идентификатор клиента, зарегистрированного у провайдера OIDC.
-   **Username claim** — имя поля в ID-токене, которое Kubernetes будет использовать в качестве имени пользователя (например, `sub`, `preferred_username` или `email`).
-   **Groups claim** — имя поля в ID-токене, содержащего список групп пользователя. Используется для настройки доступа через RBAC по группам.

После указания необходимых параметров нажмите на кнопку «Сохранить».

## Установка kubelogin

Утилита `kubelogin` используется для получения ID-токена от провайдера и передачи его Kubernetes при выполнении команд через `kubectl`.

Linux

Скачайте архив с последней версией утилиты:

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

Распакуйте архив:

```shell
unzip kubelogin_linux_amd64.zip
```

Сделайте бинарный файл исполняемым:

```shell
chmod +x kubelogin
```

Переместите его в системный путь, чтобы можно было запускать из любой директории:

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

macOS

Выполните установку с помощью Homebrew:

```shell
brew install kubelogin
```

Windows

Установите утилиту через Chocolatey:

```shell
choco install kubelogin
```

Krew

Если вы используете Krew — менеджер плагинов для `kubectl`, выполните:

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

## Получение токена

Для получения токена выполните команду:

```shell
kubelogin get-token \
  --oidc-issuer-url=https://адрес_oidc-провайдера \
  --oidc-client-id=id_клиента \
  --oidc-client-secret=секрет
```

После запуска откроется окно авторизации. Введите логин и пароль пользователя, которому необходимо выдать доступ. После успешной авторизации будет выведен токен в формате JSON.

```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"}}
```

Для просмотра содержимого токена выполните:

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

В результате будет показан объект с полями, например:

```js
{
  "exp": 1745480015,
  "iat": 1745479955,
  "auth_time": 1745479955,
  "jti": "4d9d243a-f62d-4150-94eb-5c535d2c0ea8",
  "iss": "https://keycloak.timeweb.cloud/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": "Timeweb Cloud",
  "preferred_username": "test@example.com",
  "given_name": "test",
  "family_name": "test",
  "email": "test@example.com"
}
```

Одно из имен этих параметров вы указывали при настройке OIDC-провайдера в панели управления; по умолчанию используется `sub`.

## Настройка RBAC

RBAC (Role-Based Access Control) — это механизм в Kubernetes, который управляет правами пользователей. Он используется для определения того, какие ресурсы может просматривать или изменять пользователь. Более полную информацию вы можете найти [в официальной документации Kubernetes](https://kubernetes.io/docs/reference/access-authn-authz/rbac/).

Для настройки RBAC создадим манифест `oidc-access.yaml` со следующим содержанием:

```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-провайдера#sub"
    apiGroup: rbac.authorization.k8s.io
```

Укажите значение поля `sub` из токена в параметре `name`. Это даст полные права (`cluster-admin`) конкретному пользователю, авторизованному через OIDC.

Примените манифест:

```shell
kubectl apply -f oidc-access.yaml
```

Если вы хотите выдать доступ только на чтение ресурсов, например, подов в неймспейсе default, примените такой манифест:

```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-провайдера#sub"
    apiGroup: rbac.authorization.k8s.io
```

Такой манифест позволит пользователю только просматривать поды в неймспейсе default, не давая доступ к другим ресурсам или пространствам имен.

Если при настройке OIDC-провайдера в панели управления вы указали «Username claim» со значением, например, `preferred_username`, то Kubernetes будет использовать его как имя пользователя. В этом случае вы можете упростить `subjects.name` и использовать читаемое имя, например:

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

## Настройка kubectl для работы с OIDC

Для подключения к кластеру через OIDC добавьте пользователя в `kubeconfig`:

```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-провайдера \
  --exec-arg=--oidc-client-id=id_клиента \
  --exec-arg=--oidc-client-secret=секрет
```

И назначьте текущий контекст:

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

Проверьте, что всё работает, выполнив:

```shell
kubectl get pods
```

Откроется окно браузера с запросом на вход. После авторизации команда должна выполниться без ошибок. Если возникает ошибка доступа — убедитесь, что пользователю выданы необходимые права через RBAC.

Если все работает корректно, вы можете отключить авторизацию по сертификатам в `kubeconfig`, чтобы использовать только OIDC. Для этого закомментируйте или удалите строки с данными клиента:

```yaml
# - name: nt94542-1032513
#   user:
# client-certificate-data: LS0tLS1CRUdJTiBD…
# client-key-data: LS0tLS1CRUdJ…
```

Это позволит использовать OIDC как единственный механизм аутентификации для выбранного пользователя.

## Отключение OIDC-провайдера

Чтобы отключить OIDC-провайдера, перейдите в раздел «Управление» в панели управления кластером. Нажмите кнопку «Изменить» рядом с пунктом «OIDC-провайдер», затем — «Удалить».

После отключения провайдера все пользователи, подключенные через него, потеряют доступ к кластеру. При этом созданные правила RBAC сохраняются — их необходимо удалить вручную.

Найти связанные привязки ролей можно с помощью команды:

```shell
kubectl get rolebindings --all-namespaces -o yaml | grep -B5 https://адрес_oidc-провайдера
```

Удалить объекты можно командой:

```shell
kubectl delete clusterrolebinding имя
```

Чтобы восстановить доступ, если в `kubeconfig` была указана OIDC-аутентификация, верните настройки с авторизацией по сертификатами или скачайте `kubeconfig` из панели управления.