Подключение OIDC-провайдера к кластеру

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

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

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

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

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

• Название подключения (обязательное поле) — имя подключения, отображается только в панели управления и не влияет на работу 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.

    

      

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

    

      

    
    unzip kubelogin_linux_amd64.zip
  

    

      

    
    chmod +x kubelogin
  

    

      

    
    sudo mv kubelogin /usr/local/bin/
  

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

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

    

      

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

  

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

    

      

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

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

    

      

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

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

    

      

    
    {
  "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.

Для настройки RBAC создадим манифест oidc-access.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.

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

    

      

    
    kubectl apply -f oidc-access.yaml
  

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

    

      

    
    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 и использовать читаемое имя, например:

    

      

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

  

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

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

    

      

    
    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=секрет

  

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

    

      

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

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

    

      

    
    kubectl get pods
  

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

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

    

      

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

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

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

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

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

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

    

      

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

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

    

      

    
    kubectl delete clusterrolebinding имя
  

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