Keycloak как OIDC‑провайдер для Kubernetes: упорядочиваем доступы

Проблема традиционных методов аутентификации в кластере

В небольших проектах часто хватает простого kubeconfig с сертификатом cluster-admin. Такой подход удобен для быстрого старта, но по мере роста команды и количества сервисов он быстро превращается в точку отказа. Статические токены, вручную выдаваемые сертификаты и отдельные сервис‑аккаунты не позволяют контролировать, кто и какие операции выполняет в кластере. Отсутствие единой точки аудита усложняет соблюдение требований по соответствию (PCI‑DSS, GDPR, ISO 27001) и делает невозможным быстрое реагирование на инциденты.

Ключевые ограничения традиционного подхода:

• Отсутствие единого источника прав – каждый администратор хранит свои файлы kubeconfig, что приводит к разрозненным политикам.
• Сложности ревизии – нельзя отследить, какие пользователи имели доступ к конкретному namespace в прошлом.
• Отсутствие интеграции с корпоративными каталогами – LDAP/Active Directory остаются вне процесса авторизации.
• Неподдерживаемый процесс отзыва прав – отозвать доступ можно только вручную, пересоздавая сертификаты.

Для решения этих проблем Kubernetes предлагает нативную поддержку OpenID Connect (OIDC). Интеграция с OIDC позволяет делегировать аутентификацию внешнему Identity Provider (IdP) и использовать уже существующие механизмы управления пользователями и группами.

Почему именно Keycloak

Keycloak – открытая платформа управления идентификацией и доступом, разработанная Red Hat. Среди преимуществ, которые делают его предпочтительным IdP для Kubernetes:

Keycloak легко разворачивается в контейнере, поддерживает кластеризацию и может работать в том же Kubernetes‑кластере, где он обслуживает аутентификацию, что упрощает инфраструктурные зависимости.

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

1. Подготовка Keycloak

1. Создание Realm – отдельная «область» в Keycloak, в которой будут храниться пользователи и группы, связанные с кластером.
2. Регистрация клиента – в разделе Clients создаём клиент типа openid-connect. Важно задать:
   • Client ID – произвольный идентификатор, например k8s.
   • Access Type – confidential.
   • Valid Redirect URIs – https://kubernetes.default.svc.cluster.local/* (используется только для токен‑рефреша, поэтому можно задать wildcard).
   • Root URL – оставляем пустым.
3. Настройка маппинга ролей – в Mappers добавляем User Realm Role и/или Group Membership в виде claim‑ов realm_access.roles и groups. Эти claim‑ы будут использоваться Kubernetes для построения RBAC‑политик.
4. Включение HTTPS – Keycloak обязан обслуживаться по TLS, иначе API‑сервер отклонит запросы. Можно воспользоваться Ingress‑контроллером с сертификатом Let’s Encrypt.

2. Конфигурация API‑сервера

В манифесте kube-apiserver (обычно через kubeadm‑config или Helm‑чарт) задаём параметры OIDC:

--oidc-issuer-url=https://keycloak.example.com/auth/realms/k8s
--oidc-client-id=k8s
--oidc-username-claim=preferred_username
--oidc-groups-claim=groups
--oidc-ca-file=/etc/kubernetes/pki/ca.keycloak.crt

• oidc-issuer-url – URL Realm’а, откуда будет получаться открытый ключ JWKS.
• oidc-client-id – ID клиента, зарегистрированного в Keycloak.
• oidc-username-claim – атрибут, используемый как username в Kubernetes (обычно preferred_username или email).
• oidc-groups-claim – claim, содержащий список групп, которые будут сопоставлены с RBAC‑ролями.
• oidc-ca-file – корневой сертификат, позволяющий API‑серверу доверять сертификату Keycloak.

После перезапуска API‑сервера кластер начинает принимать JWT‑токены, подписанные Keycloak.

3. Привязка ролей к группам

Kubernetes использует ClusterRoleBinding и RoleBinding для связывания групп с правами. Пример связывания группы devops из Keycloak с ролью cluster-admin:

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: devops-admin
subjects:
- kind: Group
  name: devops   # точное имя группы из claim `groups`
  apiGroup: rbac.authorization.k8s.io
roleRef:
  kind: ClusterRole
  name: cluster-admin
  apiGroup: rbac.authorization.k8s.io

Таким образом, добавление или удаление пользователя из группы в Keycloak мгновенно меняет его права в кластере без необходимости менять kubeconfig.

Работа с клиентом kubectl

Пользователю необходимо получить OIDC‑токен. Самый простой способ – воспользоваться утилитой oidc-login (плагин для kubectl) или встроенным в kubectl механизмом --token. Пример конфигурации kubeconfig:

apiVersion: v1
clusters:
- cluster:
    server: https://k8s.example.com
    certificate-authority-data: <base64-CA>
  name: production
contexts:
- context:
    cluster: production
    user: alice
  name: alice@production
users:
- name: alice
  user:
    auth-provider:
      name: oidc
      config:
        client-id: k8s
        client-secret: <secret>
        id-token: <jwt>
        refresh-token: <jwt>
        idp-issuer-url: https://keycloak.example.com/auth/realms/k8s
        extra-scopes: email
current-context: alice@production

При первом запуске kubectl откроет браузерную страницу входа в Keycloak, после чего получит id-token и refresh-token. Дальнейшие запросы к API‑серверу будут автоматически обновлять токен.

Преимущества интеграции

• Централизованное управление – все пользователи и группы находятся в едином IdP, что упрощает процесс онбординга и офбординга.
• Аудит и соответствие – каждый вход фиксируется в журнале Keycloak, а в Kubernetes можно включить аудит‑логирование запросов.
• MFA и политики паролей – поддержка многофакторной аутентификации в Keycloak распространяется на доступ к кластеру без дополнительной настройки в Kubernetes.
• Гибкая маппинг‑логика – claim‑ы можно трансформировать с помощью мапперов, позволяя реализовать сложные схемы доступа (например, привязывать роли к подразделениям организации).
• Отзыв прав в реальном времени – удаление пользователя из группы в Keycloak моментально лишает его соответствующих прав в кластере.

Возможные подводные камни

• Синхронизация времени – JWT‑токены чувствительны к расхождению часов между клиентом, API‑сервером и Keycloak. Рекомендуется использовать NTP.
• Ограничения claim‑ов – Kubernetes принимает только один claim для групп; при необходимости агрегировать несколько источников групп следует использовать маппер в Keycloak.
• Производительность – при большом количестве запросов к API‑серверу может возникнуть нагрузка на JWKS‑endpoint. Кеширование публичных ключей в API‑сервере решает эту проблему.
• Обновление токенов – kubectl автоматически обновляет токен, но сторонние CI‑инструменты могут потребовать отдельного скрипта для получения refresh-token.

Интеграция Keycloak в качестве OIDC‑провайдера превращает Kubernetes из изолированного кластера в управляемый элемент корпоративной инфраструктуры, где аутентификация, аудит и контроль доступа находятся под единой политикой безопасности. Это позволяет масштабировать кластеры, поддерживать строгие требования к соответствию и сохранять гибкость разработки без компромиссов в области безопасности.