Стадия жизненного цикла модуля: General Availability

Пример конфигурации модуля

В примере добавляется способ прямого доступа к API-серверу для kubeconfig, который пользователи генерируют в веб-интерфейсе Deckhouse.

apiVersion: deckhouse.io/v1alpha1
kind: ModuleConfig
metadata:
  name: user-authn
spec:
  version: 3
  enabled: true
  settings:
    kubeconfigGenerator:
    - id: direct
      masterURI: https://192.0.2.10:6443
      description: "Direct access to kubernetes API"

Примеры настройки провайдера

В примерах ниже <DEX_DOMAIN> — домен Dex. Это значение publicDomainTemplate, в котором %s заменено на dex, например dex.example.com.

Проверка подключения провайдера

На странице провайдера в веб-интерфейсе Deckhouse доступно действие «Проверить подключение». Оно создаёт ресурс DexProviderCheck и ждёт, пока контроллер user-authn запишет результат проверки в его status.

Проверка выполняется, чтобы убедиться в следующем:

  • указанный DexProvider существует и включён;
  • эндпоинт Dex discovery внутри кластера доступен;
  • эндпоинт внешнего провайдера доступен.

Для OIDC-провайдеров дополнительно читаются discovery-документ и JWKS. Для LDAP-провайдеров проверяется доступность TCP/TLS/StartTLS и, если включён Kerberos, наличие секрета с keytab. Также проверяется, что провайдер принимает учётные данные клиента или сервисной учётной записи (GitHub, GitLab, Bitbucket Cloud, Crowd, OIDC, bind в LDAP), и выводятся предупреждения об отключённой проверке TLS и о сертификатах, срок действия которых скоро истекает. Проверка не выполняет полный сценарий входа и не проверяет пароль тестового пользователя.

Чтобы выполнить проверку без веб-интерфейса, создайте DexProviderCheck:

apiVersion: deckhouse.io/v1
kind: DexProviderCheck
metadata:
  name: check-github
spec:
  providerName: github

Затем посмотрите его статус:

d8 k get dexproviderchecks check-github -o yaml

Ограничение идентичностей провайдера

Пользователь, вошедший через DexProvider, получает email и группы, которые сообщает провайдер. Email служит именем пользователя в Kubernetes. Поэтому провайдер даёт своим пользователям все права, уже выданные в кластере этим email и группам.

Чтобы ограничить их, используйте spec.allowedIdentities. Списки emails и emailDomains ограничивают email, и для любого другого email Dex отказывает во входе. Список groups ограничивает группы. Dex оставляет в токене только перечисленные группы и отказывает во входе, если не осталось ни одной.

Ограничения действуют для провайдера любого типа в дополнение к фильтрам групп этого типа (oidc.allowedGroups, gitlab.groups, crowd.groups, bitbucketCloud.teams без includeTeamGroups, github.orgs[].teams в каждой организации, saml.allowedGroups вместе с filterGroups: true). Имена групп сравниваются точно. Вложенность объектов Group список не расширяет, так как токен внешнего провайдера содержит только те группы, которые сообщил провайдер.

Dex проверяет ограничения при входе, при каждом запросе с refresh-токеном и при базовой аутентификации в API-сервере через LDAP-провайдер. Refresh-токен, который не проходит ограничения, Dex отзывает. Поэтому сужение ограничений завершает текущие сессии исключённых пользователей, и им нужно войти заново. Для провайдеров Crowd и OIDC basic-auth-proxy проверяет учётные данные напрямую у провайдера, поэтому при базовой аутентификации ограничения не действуют.

Те же ограничения определяют, кто может создать или изменить провайдер. Нужно иметь право назначать все роли, уже выданные email и группам, которые провайдер может сообщить. Провайдер без ограничения по email может сообщить email пользователя с ролью SuperAdmin, поэтому создать или изменить его может только SuperAdmin. Провайдер Crowd или OIDC с enableBasicAuth: true считается провайдером без ограничения по email, потому что базовая аутентификация через него выполняется в обход ограничений. Создать такой провайдер или включить enableBasicAuth в существующем может только SuperAdmin.

Пример провайдера, ограниченного доменом email и группой:

apiVersion: deckhouse.io/v1
kind: DexProvider
metadata:
  name: contractors
spec:
  type: OIDC
  displayName: Contractors
  oidc:
    issuer: https://idp.contractor.example
    clientID: dex
    clientSecret: secret
  allowedIdentities:
    emailDomains: [contractor.example]
    groups: [contractors]

Без проверки выполняются: смена clientSecret или bindPW, изменение displayName, выключение провайдера, сужение ограничений, повторное применение того же манифеста и удаление провайдера. Любое другое изменение проверяется как подключение нового провайдера, в том числе включение выключенного провайдера.

Если проверка не пройдена, в ошибке перечислены роли, которые провайдер мог бы получить, например:

dexproviders.deckhouse.io "corp": the provider can assert identities that already carry roles [user-authz:super-admin]; the requester's can-assign range is basic<=ClusterAdmin and does not cover them. Narrow spec.allowedIdentities (emails, emailDomains, groups) or ask a SuperAdmin

Префикс для групп провайдера

Кластер знает группы, которые сообщает провайдер, по их именам, поэтому правило для группы admins действует на каждого участника любой группы admins. Если два провайдера, например каталог LDAP и GitLab, сообщают группу с одним именем, участники обеих получают права по этому правилу.

spec.groupPrefix объекта DexProvider добавляет префикс перед каждой группой, которую утверждает провайдер, независимо от его типа. При groupPrefix: corp-ldap: группа admins каталога называется corp-ldap:admins в токенах, в правилах (субъекты объектов AuthorizationRule) и в allowedGroups объектов DexClient и DexAuthenticator. Префикс отделяет группы провайдеров друг от друга, только когда свой префикс есть у каждого провайдера, который может сообщить такие имена. Провайдер без префикса передаёт имена групп как есть (OIDC, команда GitHub вида org:team, GitLab, SAML и локальные группы) и может сообщить имя, которое начинается с префикса. Если правила опираются на группы с префиксом, задайте префикс каждому провайдеру.

Следующий провайдер добавляет к группам каталога LDAP префикс corp-ldap::

apiVersion: deckhouse.io/v1
kind: DexProvider
metadata:
  name: corp-ldap
spec:
  type: LDAP
  displayName: Corp
  groupPrefix: "corp-ldap:"
  allowedIdentities:
    groups:
    - "corp-ldap:admins"
    - "corp-ldap:developers"
  ldap:
    host: ldap.example.com:636
    userSearch:
      baseDN: ou=people,dc=example,dc=com
      username: mail
      idAttr: DN
      emailAttr: mail

При настройке префикса учитывайте следующее:

  • Префикса по умолчанию нет. Префикс переименовывает группы, а правила, написанные для старых имён, перестают действовать на пользователей провайдера и лишают их доступа. Существующий провайдер получает префикс только когда вы его зададите. Сначала перепишите правила, затем задайте префикс.
  • Переписать нужно субъекты ClusterAuthorizationRule и AuthorizationRule, группы ClusterRoleBinding и RoleBinding, auth.allowedUserGroups в ModuleConfig модулей openvpn, documentation, istio, cilium-hubble и deckhouse-tools (эти модули собирают DexAuthenticator из этой настройки), allowedIdentities.groups DexProvider и allowedGroups объектов DexAuthenticator и DexClient.
  • После того как префикс задан или изменён, пользователи провайдера входят заново, и новые токены содержат префикс.
  • Уже выданные access- и ID-токены сохраняют старые имена только до истечения срока их действия. Правило, которое всё ещё называет группу без префикса, в том числе правило cluster-admin, перестаёт совпадать, как только этих токенов не останется.
  • Токен, который под Dex со старой конфигурацией выдаёт позже чем через 30 минут после смены, может сохранить старые имена. Правила, переписанные под префикс, к ним не подходят.
  • Списки, которые называют группы Dex, принимают имена с префиксом: allowedIdentities.groups провайдера и allowedGroups объектов DexClient и DexAuthenticator. Каждое имя в allowedIdentities.groups должно начинаться с groupPrefix, иначе API отклоняет манифест, потому что Dex добавляет префикс до сравнения.
  • Настройки групп в блоке типа провайдера (например, oidc.allowedGroups, gitlab.groups, crowd.groups и ldap.groupSearch) относятся к группам провайдера идентификации и принимают его имена, без префикса.
  • Группа, которая уже начинается с префикса, сохраняет своё имя.
  • Префикс заканчивается двоеточием, как corp-ldap:, и отличается от префикса любого другого DexProvider и от префиксов групп любого TokenExchangeProvider. Ни один из двух префиксов не может начинаться с другого. Admission-вебхуки отклоняют префикс, который это нарушает, какой бы из объектов ни создавался или менялся последним.
  • Префикс не может начинаться с system:, который зарезервирован за API-сервером Kubernetes, или с peering:, который зарезервирован для ServiceAccount неймспейса d8-peering. Его нельзя задать вместе с enableBasicAuth у провайдера OIDC или Crowd, потому что basic-auth-proxy проверяет учётные данные у такого провайдера напрямую и передаёт его группы как есть, поэтому префикс к ним не применился бы. Базовая аутентификация провайдера LDAP идёт через Dex и получает префикс.
  • С префиксом провайдер может утвердить только группы, которые начинаются с него. Поэтому проверка того, кто может создать или изменить провайдер («Ограничение идентичностей провайдера»), из ролей, выданных группам, учитывает только роли групп с этим префиксом.

GitHub

В примере представлены настройки провайдера для интеграции с GitHub.

apiVersion: deckhouse.io/v1
kind: DexProvider
metadata:
  name: github
spec:
  type: Github
  displayName: My Company GitHub
  # Опционально: временно отключить провайдер, не удаляя CR
  # enabled: false
  github:
    clientID: plainstring
    clientSecret: plainstring

В организации GitHub зарегистрируйте OAuth-приложение. Для этого перейдите в Settings → Developer settings → OAuth Apps → New OAuth App и укажите в Authorization callback URL адрес https://<DEX_DOMAIN>/callback.

Полученные Client ID и Client Secret укажите в DexProvider.

Если в организации ограничен доступ сторонних приложений, запросите одобрение в Settings → Applications → Authorized OAuth Apps → <APPLICATION_NAME> → Send Request и попросите владельца организации подтвердить запрос.

GitLab

В примере представлены настройки провайдера для интеграции с GitLab.

apiVersion: deckhouse.io/v1
kind: DexProvider
metadata:
  name: gitlab
spec:
  type: Gitlab
  displayName: Dedicated GitLab
  gitlab:
    baseURL: https://gitlab.example.com
    clientID: plainstring
    clientSecret: plainstring
    groups:
    - administrators
    - users

В GitLab создайте новое приложение.

Для этого:

  • self-hosted — перейдите в Admin area → Application → New application, укажите в Redirect URI (Callback URL) адрес https://<DEX_DOMAIN>/callback и в Scopes выберите read_user и openid;
  • cloud GitLab.com — под главной учётной записью проекта перейдите в User Settings → Application → New application, укажите в Redirect URI (Callback URL) адрес https://<DEX_DOMAIN>/callback и в Scopes выберите read_user и openid;
  • GitLab 16 и выше — при создании приложения включите опцию Trusted/Trusted applications are automatically authorized on GitLab OAuth flow.

Полученные Application ID и Secret укажите в DexProvider.

Atlassian Crowd

В примере представлены настройки провайдера для интеграции с Atlassian Crowd.

apiVersion: deckhouse.io/v1
kind: DexProvider
metadata:
  name: crowd
spec:
  type: Crowd
  displayName: Crowd
  crowd:
    baseURL: https://crowd.example.com/crowd
    clientID: plainstring
    clientSecret: plainstring
    groups:
    - administrators
    - users

В соответствующем проекте Atlassian Crowd создайте новое Generic-приложение. Для этого перейдите в Applications → Add application.

Полученные Application Name и Password укажите в DexProvider.

Группы Crowd указывайте в DexProvider в нижнем регистре.

Bitbucket Cloud

В примере представлены настройки провайдера для интеграции с Bitbucket.

apiVersion: deckhouse.io/v1
kind: DexProvider
metadata:
  name: bitbucket
spec:
  type: BitbucketCloud
  displayName: Bitbucket
  bitbucketCloud:
    clientID: plainstring
    clientSecret: plainstring
    includeTeamGroups: true
    teams:
    - administrators
    - users

В меню команды Bitbucket создайте новый OAuth consumer. Для этого перейдите в Settings → OAuth consumers → New application, укажите в Callback URL адрес https://<DEX_DOMAIN>/callback и разрешите доступ для Account: Read и Workspace membership: Read.

Полученные Key и Secret укажите в DexProvider.

OIDC (OpenID Connect)

Аутентификация через OIDC-провайдера требует регистрации клиента (или создания приложения). Сделайте это по документации вашего провайдера (например, Okta, Keycloak, Gluu или Blitz).

Полученные clientID и clientSecret укажите в DexProvider.

Keycloak

После выбора realm для настройки, добавления пользователя в Users и создания клиента в разделе Clients с включенной аутентификацией, которая необходима для генерации clientSecret, выполните следующие шаги:

  • Создайте в разделе Client scopes scope с именем groups, и назначьте ему предопределённое сопоставление groups («Client scopes» → «Client scope details» → «Mappers» → «Add predefined mappers»).
  • В созданном ранее клиенте добавьте данный scope во вкладке Client scopes («Clients → «Client details» → «Client Scopes» → «Add client scope»).
  • В полях «Valid redirect URIs», «Valid post logout redirect URIs» и «Web origins» конфигурации клиента укажите https://<DEX_DOMAIN>/*.

В примере представлены настройки провайдера для интеграции с Keycloak:

apiVersion: deckhouse.io/v1
kind: DexProvider
metadata:
  name: keycloak
spec:
  type: OIDC
  displayName: My Company Keycloak
  oidc:
    issuer: https://keycloak.my-company.com/realms/myrealm # Используйте имя вашего realm
    clientID: plainstring
    clientSecret: plainstring
    insecureSkipEmailVerified: true
    getUserInfo: true
    scopes:
      - openid
      - profile
      - email
      - groups

Если в Keycloak не используется подтверждение учетных записей по email, для корректной работы с ним в качестве провайдера аутентификации внесите изменения в настройку Client scopes одним из следующих способов:

  • Удалите сопоставление Email verified («Client Scopes» → «Email» → «Mappers»). Это необходимо для корректной обработки значения true в поле insecureSkipEmailVerified и правильной выдачи прав пользователям с неподтвержденным email.

  • Если отредактировать или удалить сопоставление Email verified невозможно, создайте отдельный Client Scope с именем email_dkp (или любым другим) и добавьте в него два сопоставления:

    • email: «Client Scopes» → email_dkp → «Add mapper» → «From predefined mappers» → email;
    • email verified: «Client Scopes» → email_dkp → «Add mapper» → «By configuration» → «Hardcoded claim». Укажите следующие поля:
      • «Name»: email verified;
      • «Token Claim Name»: emailVerified;
      • «Claim value»: true;
      • «Claim JSON Type»: boolean.

    После этого в клиенте, зарегистрированном для кластера Deckhouse Platform, в разделе «Clients» для Client scopes замените значение email на email_dkp.

    В ресурсе DexProvider укажите параметр insecureSkipEmailVerified: true и в поле .spec.oidc.scopes замените название Client Scope на email_dkp, следуя примеру:

        scopes:
          - openid
          - profile
          - email_dkp
          - groups
    

При insecureSkipEmailVerified: true Dex принимает неподтверждённые email-адреса. Права выдаются по email, поэтому используйте этот параметр, только если провайдер не позволяет пользователям указывать произвольный email.

Okta

В примере представлены настройки провайдера для интеграции с Okta:

apiVersion: deckhouse.io/v1
kind: DexProvider
metadata:
  name: okta
spec:
  type: OIDC
  displayName: My Company Okta
  oidc:
    issuer: https://my-company.okta.com
    clientID: plainstring
    clientSecret: plainstring
    getUserInfo: true

Blitz Identity Provider

При регистрации приложения в Blitz Identity Provider укажите https://<DEX_DOMAIN>/callback в качестве URL для перенаправления пользователя после авторизации.

В примере представлены настройки провайдера для интеграции с Blitz Identity Provider:

apiVersion: deckhouse.io/v1
kind: DexProvider
metadata:
  name: blitz
spec:
  displayName: Blitz Identity Provider
  oidc:
    basicAuthUnsupported: false
    claimMapping:
      email: email
      groups: your_claim # Claim для получения групп пользователя, группы пользователя настраиваются на стороне провайдера Blitz Identity Provider
    clientID: clientID
    clientSecret: clientSecret
    getUserInfo: true
    insecureSkipVerify: false
    issuer: https://yourdomain.idblitz.ru/blitz
    promptType: consent 
    scopes:
    - profile
    - openid
    userIDKey: sub
    userNameKey: email
  type: OIDC

Чтобы корректно отрабатывал выход из приложений (происходил отзыв токена и требовалась повторная авторизация), нужно установить login в значении параметра promptType.

Для обеспечения гранулированного доступа пользователя к приложениям необходимо:

  • добавить параметр allowedUserGroups в ModuleConfig нужного приложения;
  • добавить группы к пользователю (наименования групп должны совпадать как на стороне Blitz, так и на стороне Deckhouse).

Пример для Prometheus:

apiVersion: deckhouse.io/v1alpha1
kind: ModuleConfig
metadata:
  name: prometheus
spec:
  version: 2
  settings:
    auth:
      allowedUserGroups:
        - adm-grafana-access
        - grafana-access

LDAP

В примере представлены настройки провайдера для интеграции с Active Directory:

apiVersion: deckhouse.io/v1
kind: DexProvider
metadata:
  name: active-directory
spec:
  type: LDAP
  displayName: Active Directory
  ldap:
    host: ad.example.com:636
    rootCAData: |
      -----BEGIN CERTIFICATE-----
      MIIFaDC...
      -----END CERTIFICATE-----

    bindDN: cn=dex-readonly,cn=users,dc=example,dc=com
    bindPW: <PASSWORD>

    usernamePrompt: Email Address

    enableBasicAuth: true

    userSearch:
      baseDN: cn=Users,dc=example,dc=com
      filter: "(objectClass=person)"
      username: userPrincipalName
      idAttr: DN
      emailAttr: userPrincipalName
      nameAttr: cn

    groupSearch:
      baseDN: cn=Users,dc=example,dc=com
      filter: "(objectClass=group)"
      userMatchers:
      - userAttr: DN
        groupAttr: member
      nameAttr: cn

Для настройки аутентификации создайте в LDAP сервисную учётную запись с правами только на чтение. Укажите её DN и пароль в параметрах bindDN и bindPW объекта DexProvider. Пароль в bindPW указывается в открытом виде. Хешированные пароли не поддерживаются.

Если в LDAP разрешено анонимное чтение, bindDN и bindPW можно не указывать.

Вложенные группы

По умолчанию Dex добавляет в токен только группы, в которые пользователь входит напрямую. Группа, в которую входит группа пользователя, не добавляется. Чтобы добавлять группы верхних уровней, задайте в параметре recursionGroupAttr в userMatchers атрибут группы, в котором хранятся её участники. Тогда Dex ищет группы, в которые входит каждая найденная группа, уровень за уровнем, и добавляет их к группам пользователя. Цикл из групп завершает поиск.

Следующий groupSearch добавляет группы всех уровней через атрибут member:

    groupSearch:
      baseDN: cn=Users,dc=example,dc=com
      filter: "(objectClass=group)"
      userMatchers:
      - userAttr: DN
        groupAttr: member
        recursionGroupAttr: member
      nameAttr: cn

Dex выполняет ещё один поиск для каждой группы каждого уровня при каждом входе и каждом обновлении токенов. Ограничьте baseDN и filter в groupSearch и учитывайте, что вход при глубокой иерархии может занимать больше времени.

Вход по одному из нескольких атрибутов

userSearch.username задаёт один атрибут, с которым сравнивается введённое имя пользователя. Чтобы пользователи могли входить по логину или по email, перечислите атрибуты в userSearch.usernames вместо username (задайте один из двух параметров). Dex ищет запись, в которой совпадает любой из них. Если имени соответствует больше одной записи, вход отклоняется.

Следующий userSearch позволяет входить по sAMAccountName или userPrincipalName:

    userSearch:
      baseDN: cn=Users,dc=example,dc=com
      filter: "(objectClass=person)"
      usernames: [sAMAccountName, userPrincipalName]
      idAttr: DN
      emailAttr: userPrincipalName
      nameAttr: cn

Настройка базовой аутентификации

Чтобы включить доступ к Kubernetes API с использованием базовой аутентификации (Basic Authentication) по учетным записям LDAP:

  1. Убедитесь, что в конфигурации модуля control-plane-manager включен параметр apiserver.publishAPI.
  2. Установите enableBasicAuth: true в DexProvider типа LDAP.

В кластере может быть только один провайдер аутентификации с включённым параметром enableBasicAuth.

После настройки пользователи смогут обращаться к Kubernetes API с помощью kubectl, используя свой логин и пароль в LDAP.

Пример kubeconfig для пользователя:

apiVersion: v1
kind: Config
clusters:
- name: my-cluster
  cluster:
    server: https://api.example.com
    # Путь к CA сертификату или insecure-skip-tls-verify: true
    certificate-authority: /path/to/ca.crt
users:
- name: ldap-user
  user:
    username: janedoe@example.com
    password: userpassword
contexts:
- name: default
  context:
    cluster: my-cluster
    user: ldap-user
current-context: default

Kerberos (SPNEGO) SSO для LDAP

Dex поддерживает аутентификацию без отображения формы ввода логина/пароля, которая реализуется с помощью механизма Kerberos (SPNEGO) для LDAP‑коннектора. При использовании этого механизма браузер, доверяющий хосту Dex, отправляет Authorization: Negotiate …, Dex валидирует Kerberos‑билет по keytab, пропускает форму вводу логина/пароля, сопоставляет principal с LDAP‑именем, получает группы и завершает OIDC‑поток.

Principal, сопоставленный с именем пользователя, сравнивается со всеми атрибутами из userSearch.usernames (или с username, если задан он) тем же фильтром, что и вход по паролю. При usernameFromPrincipal: UserPrincipalName principal сравнивается в виде user@REALM, при Localpart или SAMAccountName — в виде части до @. Значение должно совпадать с атрибутом собственной записи пользователя. Перечисляйте только атрибуты с уникальными в каталоге значениями, согласованные с usernameFromPrincipal. Если значение другой записи совпадёт с principal, у этого пользователя перестанет работать SSO (multiple results). Principal, не совпавший ни с одним атрибутом своей записи, будет сопоставлен с записью другого пользователя. Пароль на этом пути не проверяется.

Минимальный пример (расширение спецификации LDAP‑провайдера):

apiVersion: deckhouse.io/v1
kind: DexProvider
metadata:
  name: active-directory
spec:
  type: LDAP
  displayName: Active Directory
  ldap:
    host: ad.example.com:636
    bindDN: cn=dex-readonly,cn=users,dc=example,dc=com
    bindPW: <PASSWORD>
    userSearch:
      baseDN: cn=Users,dc=example,dc=com
      username: sAMAccountName
      idAttr: uid
      emailAttr: mail
      nameAttr: cn
    groupSearch:
      baseDN: cn=Users,dc=example,dc=com
      nameAttr: cn
      userMatchers:
      - userAttr: uid
        groupAttr: memberUid
    kerberos:
      enabled: true
      keytabSecretName: dex-kerberos-keytab   # Секрет в неймспейсе `d8-user-authn` с ключом 'krb5.keytab'.
      expectedRealm: EXAMPLE.COM              # Опционально, проверка realm (без учёта регистра).
      usernameFromPrincipal: SAMAccountName   # Localpart|SAMAccountName|UserPrincipalName
      fallbackToPassword: false               # По умолчанию false; если true — при отсутствии/ошибке заголовка `Authorization: Negotiate` будет показана форма ввода логина/пароля.

Примечания:

  • Секрет dex-kerberos-keytab должен находиться в неймспейсе d8-user-authn и содержать ключ krb5.keytab.
  • Один под Dex может обслуживать несколько LDAP+Kerberos провайдеров. У каждого — свой keytab. krb5.conf не требуется (Dex проверяет билеты офлайн по keytab).
  • В DexProvider с enabled: true должен быть указан keytabSecretName, иначе объект не сохранится. Чтобы выключить Kerberos и оставить его настройки, укажите enabled: false.

SAML

В примере представлены настройки провайдера для интеграции с SAML 2.0 Identity Provider (например, AD FS, Okta, Keycloak).

apiVersion: deckhouse.io/v1
kind: DexProvider
metadata:
  name: saml-provider
spec:
  type: SAML
  displayName: Корпоративный SAML
  saml:
    ssoURL: https://saml-idp.example.com/saml/sso
    rootCAData: |
      -----BEGIN CERTIFICATE-----
      MIIFaDC...
      -----END CERTIFICATE-----
    entityIssuer: https://dex.example.com/callback
    ssoIssuer: https://saml-idp.example.com
    usernameAttr: name
    emailAttr: email
    groupsAttr: groups
    nameIDPolicyFormat: persistent

Для настройки SAML Identity Provider:

  1. Зарегистрируйте Dex как Service Provider (SP) у вашего провайдера идентификации со следующими параметрами:
    • ACS URL (Assertion Consumer Service): https://<DEX_DOMAIN>/callback
    • Entity ID: https://<DEX_DOMAIN>/callback
    • Формат идентификатора имени: persistent или emailAddress
  2. Настройте сопоставление атрибутов в провайдере идентификации для отправки атрибутов email, name (имя пользователя) и groups в SAML assertion.

  3. Экспортируйте сертификат подписи провайдера идентификации и укажите его в поле rootCAData ресурса DexProvider.

SAML не поддерживает refresh-токены. Dex кеширует данные пользователя из первого SAML-утверждения (assertion) и возвращает их при последующих запросах с refresh-токеном. Время жизни сессии ограничивается параметром модуля refreshTokenAbsoluteLifetime.

Настройка OAuth2-клиента в Dex для подключения приложения

Этот вариант настройки подходит приложениям, которые могут выполнять OAuth2-аутентификацию самостоятельно, без OAuth2-прокси. Чтобы такие приложения могли работать с Dex, используется DexClient.

apiVersion: deckhouse.io/v1
kind: DexClient
metadata:
  name: myname
  namespace: mynamespace
spec:
  redirectURIs:
  - https://app.example.com/callback
  - https://app.example.com/callback-reserve
  allowedGroups:
  - Everyone
  - admins
  trustedPeers:
  - opendistro-sibling

В authorization code flow Dex принимает только метод S256 Proof Key for Code Exchange (PKCE). Приложение, которое отправляет code_challenge с code_challenge_method=plain или без code_challenge_method (по умолчанию в OAuth2 это plain), получает перенаправление на свой redirect URI с ошибкой invalid_request «Unsupported PKCE challenge method». Такое приложение должно перейти на S256. PKCE остаётся необязательным, и приложение, которое не отправляет code_challenge, входит без него. Device flow (/device/code) эта проверка не затрагивает. Dex принимает для него plain, потому что секретом служит сам device code.

Списки разрешённых групп и адресов электронной почты в DexClient проверяются при входе и при каждом обновлении refresh-токена. Изменение списков запрещает дальнейшее обновление сессий, которые больше им не соответствуют; таким пользователям нужно войти заново.

После создания такого ресурса в Dex будет зарегистрирован клиент с идентификатором (clientID) dex-client-myname@mynamespace.

Пароль доступа к клиенту (clientSecret) сохранится в секрете:

apiVersion: v1
kind: Secret
metadata:
  name: dex-client-myname
  namespace: mynamespace
type: Opaque
data:
  clientSecret: c2VjcmV0

Предоставление приложению доступа к Kubernetes API

Ресурс DexClient или DexAuthenticator можно настроить для получения токенов, которые принимает API-сервер Kubernetes. Для этого установите на ресурсе одну из следующих аннотаций со значением "true":

  • dexclient.deckhouse.io/allow-access-to-kubernetes — для DexClient;
  • dexauthenticator.deckhouse.io/allow-access-to-kubernetes — для DexAuthenticator.

Пример настройки ресурса DexClient:

apiVersion: deckhouse.io/v1
kind: DexClient
metadata:
  name: myname
  namespace: mynamespace
  annotations:
    dexclient.deckhouse.io/allow-access-to-kubernetes: "true"
spec:
  redirectURIs:
  - https://app.example.com/callback

Аннотация регистрирует клиента в качестве доверенного (trusted peer) для привилегированного OAuth2-клиента kubernetes, что позволяет ему запрашивать ID-токены, предназначенные для API-сервера. В таком токене имя пользователя определяется значением claim email, а группы — значением claim groups. В результате приложение обращается к API-серверу от имени прошедшего аутентификацию пользователя и с предоставленными ему правами.

Предоставляемый таким образом доступ действует на уровне всего кластера, хотя DexClient и DexAuthenticator являются namespaced-объектами. По этой причине добавить аннотацию или изменить её значение на "true" может только субъект, которому разрешено действие create для субресурса dexclients/allow-access-to-kubernetes (для DexClient) или dexauthenticators/allow-access-to-kubernetes (для DexAuthenticator) в неймспейсе объекта. Это право входит в роль d8:system-capability:user-authn:edit и в уровень доступа ClusterAdmin. Чтобы выдать право в одном неймспейсе, создайте Role с действием create для этих субресурсов и привяжите её через RoleBinding в этом неймспейсе. Прав на создание объектов DexClient или DexAuthenticator недостаточно.

Добавление аннотации ограничено независимо от указанного значения, включая "false". Это необходимо для совместимости с версиями Deckhouse Platform до 1.77, в которых доступ предоставляется при наличии аннотации независимо от её значения. Если доступ к API-серверу Kubernetes не требуется, не добавляйте аннотацию.

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

Ограничение провайдеров приложения

По умолчанию на странице входа приложения показываются все DexProvider кластера и встроенные пользователи (User). Чтобы оставить только часть из них, перечислите их имена в spec.allowedProviders объекта DexClient или DexAuthenticator. Имя DexProvider — это его metadata.name. Встроенные пользователи называются local.

В следующем DexAuthenticator вход в приложение разрешён только через провайдера corp-ldap и встроенным пользователям:

apiVersion: deckhouse.io/v1
kind: DexAuthenticator
metadata:
  name: admin-panel
  namespace: team
spec:
  applicationDomain: panel.example.com
  applicationIngressClassName: nginx
  allowedProviders:
  - corp-ldap
  - local

Dex скрывает остальных провайдеров на странице входа и отказывает во входе через них, даже если пользователь откроет адрес провайдера напрямую. Если в списке один провайдер, пользователь сразу направляется к нему, без страницы выбора. Dex проверяет провайдера и при каждом обновлении refresh-токена и обмене токенов приложения, поэтому токен, выданный через провайдера, которого больше нет в списке, перестаёт обновляться, и пользователю нужно войти заново.

Список работает вместе с остальными ограничениями: allowedEmails и allowedGroups приложения и allowedIdentities провайдера. Пользователь должен пройти все. Пустой или отсутствующий список разрешает всех провайдеров. Исключение — trustedPeers. Доверенный клиент может запросить токен с аудиторией этого клиента через провайдера, который разрешён самому доверенному клиенту, и allowedProviders этого клиента для такого токена не проверяется. То же исключение действует для allowedEmails и allowedGroups.

Пользователям, которые вошли в приложение через убранный из списка провайдер, нужно войти заново, даже если провайдер вернут в список. При включённом sessions.enabled Dex сохраняет браузерную сессию такого пользователя. Когда провайдер вернётся в список, пользователь может войти по этой сессии без ввода учётных данных, пока сессия действует.

Имя, которому не соответствует ни один DexProvider, принимается с предупреждением. Войти через него никто не сможет, пока провайдер не создан. Поэтому DexAuthenticator или DexClient, которые GitOps-инструмент применил раньше своего провайдера, не приводят к ошибке.

Обмен токенов других издателей

TokenExchangeProvider позволяет Dex обменивать токен другого издателя на свой токен (обмен токенов по RFC 8693). API-сервер Kubernetes принимает токен Dex так же, как токен любого другого пользователя Dex. Типичные издатели — CI-системы, Dex соседнего кластера и издатель токенов ServiceAccount другого кластера.

Dex принимает токен, если выполнены все условия:

  • Подпись проверяется ключами издателя из его discovery-документа (keys.discovery) или заданными в объекте (keys.jwks).
  • Если в заголовке токена есть kid, подпись проверяется только ключом с этим kid.
  • Claim iss равен issuer, и срок действия токена не истёк.
  • Токен действует не дольше subjectTokenMaxLifetime (по умолчанию 24 часа), считая от iat до exp, а у токена без iat — от текущего момента до exp. Claim exp обязателен.
  • Claim aud совпадает с одной из записей audiences.
  • Claims из claimValidation несут требуемые значения.
  • DexClient, который отправляет запрос, указан в clients.

Субъект называется по identity. Имя пользователя состоит из префикса и значения claim, группы берутся из claims так же. API-сервер берёт имя пользователя из claim email. Без identity.email именем пользователя в кластере становится результат identity.username, с identity.email — результат identity.email. Субъекты RBAC указывают это имя.

Пример для пользователей соседнего кластера A. Dex кластера A выпускает токены для своего DexClient cluster-b в неймспейсе d8-user-authn, поэтому aud равен dex-client-cluster-b@d8-user-authn. В кластере B DexClient cluster-a-exchange, который их обменивает, должен иметь аннотацию dexclient.deckhouse.io/allow-access-to-kubernetes. Примените в кластере B следующий манифест:

apiVersion: deckhouse.io/v1alpha1
kind: TokenExchangeProvider
metadata:
  name: cluster-a
spec:
  issuer: https://dex.cluster-a.example.com/
  keys:
    discovery:
      caData: |
        -----BEGIN CERTIFICATE-----
        <CA_OF_CLUSTER_A>
        -----END CERTIFICATE-----
  audiences:
  - exact: dex-client-cluster-b@d8-user-authn
  identity:
    username:
      claim: email
      prefix: "cluster-a:"
    groups:
    - claim: groups
      prefix: "cluster-a:"
  allowedIdentities:
    emailDomains:
    - example.com
  clients:
  - dexClient:
      name: cluster-a-exchange
      namespace: d8-user-authn

Клиент обменивает токен через эндпоинт /token Dex, указывая в connector_id значение status.connectorID объекта. Пример для CI-систем — в разделе «Доступ для CI/CD».

Особенности TokenExchangeProvider:

  • Служит только для обмена токенов и не показывается на странице входа.
  • DexClient, указанный в spec.clients, может обменивать токены через провайдер, даже если провайдер не перечислен в его allowedProviders.
  • Токен издателя принимается только как JWT ID-токен. Access-токены не принимаются.
  • Изменение объекта применяется без перезапуска Dex и действует на новые обмены. Токены Dex, выданные раньше, действуют до истечения срока. Досрочно они отклоняются, если провайдер теряет коннектор, то есть если объект удалён или создан заново с тем же именем либо провайдер уступил имена провайдеру, созданному раньше (PrefixConflict). Отклонение действует при том же условии, что и после удаления объекта (условие описано ниже). Когда PrefixConflict снят, провайдер получает коннектор с новым status.connectorID.
  • Изменение, отклонённое как неверное (InvalidSpec, например некорректный ключ или caData без сертификата), не применяется. Провайдер работает с прежней спецификацией, пока её не исправят.
  • Каждый префикс обязателен и заканчивается двоеточием. Префикс отделяет субъектов провайдера от людей и от субъектов других провайдеров. Два провайдера не могут выдавать одинаковые имена. Провайдер, у которого префикс имени пользователя или группы пересекается с префиксом провайдера, созданного раньше, не готов (PrefixConflict) и ничего не обменивает, пока конфликт не устранён.
  • С keys.discovery провайдер становится готовым только после того, как прочитаны discovery-документ и ключи издателя. Иначе он не готов (DiscoveryFailed) и проверяется снова раз в минуту; коннектор при этом всё равно записывается, поэтому изменение, сужающее доступ, применяется сразу. Discovery-документ читается только по https.
  • После удаления объекта API Kubernetes в течение нескольких секунд отклоняет все токены, выданные через него, если в модуле user-authz включён параметр enableMultiTenancy и в кластере работает Kubernetes 1.34 или новее. В остальных случаях эти токены действуют до истечения срока (параметр idTokenTTL).
  • Имена пользователей и групп с префиксом peering: зарезервированы для ServiceAccount неймспейса d8-peering. Их не может утверждать ни DexProvider, ни другой TokenExchangeProvider.
  • Объектами TokenExchangeProvider управляет роль d8:system-capability:user-authn:edit, которую несут роль d8:subsystem:iam:manager и включающие её роли, а в упрощённой ролевой модели — уровень доступа ClusterAdmin. Тот, кто создаёт TokenExchangeProvider, выбирает издателя, его ключи и имена, а значит может получить токен за любого пользователя или группу вне зарезервированных префиксов. Это право равносильно праву действовать от имени любого пользователя. Выдавайте его только администраторам кластера. Коннекторы и отзывы Dex в неймспейсе d8-user-authn пишет модуль; изменять их может только администратор кластера.

Обмен токенов через DexProvider устарел и по умолчанию выключен. DexProvider типа OIDC или Gitlab обменивает токены только с spec.tokenExchange.enabled: true. Параметр можно только выключить, установить true может только сам модуль. При обновлении с релиза, в котором этого параметра нет, модуль один раз выставляет его существующим провайдерам OIDC и Gitlab. Он выставляет true, если есть DexClient с аннотацией dexclient.deckhouse.io/allow-access-to-kubernetes, чтобы кластер, который мог обменивать токены, продолжал это делать, иначе false. DexAuthenticator с доступом к Kubernetes не учитывается. Его oauth2-proxy токены не обменивает, а обмен с его client secret не сохраняется. Параметр и обмен токенов через DexProvider будут удалены после следующего LTS-релиза.

Пока DexProvider обменивает токены, срабатывает алерт D8UserAuthnDexProviderTokenExchangeDeprecated. Перенесите обмен на TokenExchangeProvider, как описано в разделе «Переход с DexProvider», затем установите spec.tokenExchange.enabled: false.

Браузерные сессии Dex

По умолчанию Dex не запоминает пользователя между входами: каждое приложение, отправляющее пользователя в Dex, получает форму входа. При включённых браузерных сессиях Dex запоминает пользователя, вошедшего в браузере. Чтобы включить сессии, задайте параметр sessions.enabled:

apiVersion: deckhouse.io/v1alpha1
kind: ModuleConfig
metadata:
  name: user-authn
spec:
  version: 3
  enabled: true
  settings:
    sessions:
      enabled: true

Что меняется при включённых сессиях:

  • Веб-интерфейсы Deckhouse используют общий вход: пользователь вводит пароль и второй фактор один раз и открывает остальные без них. Это приложения объектов DexAuthenticator в неймспейсах d8-*. Пользовательские объекты DexAuthenticator и DexClient общий вход не используют. Чтобы отключить общий вход, задайте sessions.sso равным None. Общий вход действует, пока браузер использует любое из этих приложений, но не дольше sessions.absoluteLifetime. Если в течение sessions.validIfNotUsedFor они не использовались, следующее приложение снова запросит пароль. Пользователь внешнего провайдера использует общий вход, пока данные пользователя, сохранённые в Dex, актуальны: если в течение sessions.identityRefresh.maxAge не было ни входа, ни обновления токенов приложения, следующее приложение снова запросит пароль.
  • Форма входа показывает флажок «Запомнить меня». С ним сессия сохраняется после закрытия браузера.
  • Когда пользователь выходит из приложения объекта DexAuthenticator, DexAuthenticator отправляет браузер в Dex, и Dex завершает сессию. За несколько секунд браузер выходит из всех приложений объектов DexAuthenticator, в которые вошёл через эту сессию. Если приложение и Dex находятся на разных сайтах (разных регистрируемых доменах), Dex просит пользователя подтвердить выход. Приложение выполняет выход переходом браузера: запрос из скрипта (fetch, XHR) не следует перенаправлению в Dex, и сессия Dex остаётся.
  • Выход из Dex не завершает сессию во внешнем OIDC-провайдере: провайдер может снова впустить пользователя без пароля. Чтобы завершать сессию и у провайдера, включите параметр upstreamLogout провайдера или задайте promptType: login, чтобы пароль запрашивался при каждом входе.
  • Dex снова получает данные пользователя (например, группы) у провайдера, когда сохранённые данные старше sessions.identityRefresh.maxAge. Если провайдер отвечает, что пользователя больше нет или ему закрыт доступ, Dex завершает все сессии и токены этого пользователя этого провайдера.

Что не меняется:

  • Токены для kubectl (kubeconfig, d8 login) выдаются только после интерактивного входа и никогда — по сессии браузера.
  • Приложение объекта DexAuthenticator остаётся доступным в течение keepUsersLoggedInFor, даже когда сессия Dex заканчивается по времени жизни или из-за неактивности. Завершает его только выход.

Сколько длится сессия

Сессия Dex завершается при первом из событий:

  • прошло sessions.absoluteLifetime с момента входа (по умолчанию неделя), как бы активно ни использовался браузер;
  • сессию не использовали в течение sessions.validIfNotUsedFor (по умолчанию сутки);
  • пользователь вышел или администратор завершил сессию;
  • браузер закрыт, если при входе пользователь не выбрал «Запомнить меня».

Браузер использует сессию, когда входит через неё в приложение и когда приложение, вошедшее через неё, обновляет свои токены: приложение объекта DexAuthenticator или объекта DexClient с refreshTokenLifetime: Session. Такое приложение обновляет токены каждые idTokenTTL, пока оно открыто и отправляет запросы. Закрытое приложение или приложение в браузере спящего компьютера сессию не использует.

Со значениями по умолчанию пользователь, работающий каждый день, вводит пароль и второй фактор раз в неделю и ещё раз после перерыва дольше суток, например после выходных. Ночь сессия переживает.

Когда сессия завершается, уже открытые приложения остаются доступными в течение keepUsersLoggedInFor, но вход в другой веб-интерфейс снова запрашивает пароль.

Чтобы запрашивать пароль чаще, уменьшите sessions.validIfNotUsedFor, например до 1h: тогда пользователь снова вводит пароль после каждого перерыва в час. sessions.validIfNotUsedFor не может быть больше sessions.absoluteLifetime; если задан только sessions.absoluteLifetime и он меньше суток, неиспользуемая сессия завершается через sessions.absoluteLifetime.

Выход из приложения объекта DexClient

Приложение объекта DexClient выводит пользователя из Dex, отправляя браузер на адрес https://dex.<PUBLIC_DOMAIN>/logout с параметрами client_id и post_logout_redirect_uri. Dex возвращает браузер только на адреса из параметра postLogoutRedirectURIs объекта DexClient:

https://dex.example.com/logout?client_id=dex-client-myapp@mynamespace&post_logout_redirect_uri=https%3A%2F%2Fmyapp.example.com%2F

Чтобы узнавать о завершении сессии пользователя, приложение может задать backchannelLogoutURI. Dex отправляет уведомление один раз, без повторов, когда пользователь выходит из сессии, провайдер отвечает, что пользователя больше нет, сессию завершает операция UserOperation или самообслуживание в веб-интерфейсе или пользователя удаляют; о сессии, завершённой вне Dex, — в течение нескольких секунд. Приложение, которому важно не пропустить завершение, может также проверять свои токены на эндпоинте интроспекции Dex (/token/introspect), который отвечает, что токены завершённой сессии или устройства неактивны.

Приложение, запрашивающее офлайн-доступ (refresh-токены), получает их только после интерактивного входа. С параметром refreshTokenLifetime: Session приложение может впустить пользователя по сессии браузера, а его токены перестают действовать, когда пользователь выходит из этой сессии.

Локальная аутентификация

Локальная аутентификация обеспечивает проверку и управление доступом пользователей с возможностью настройки парольной политики, поддержкой двухфакторной аутентификации (2FA) и управлением группами.
В параметрах модуля можно настроить сложность паролей, историю паролей, ротацию паролей, блокировку после неудачных попыток входа и ограничение частоты неудачных попыток с одного IP-адреса. Внешняя система аутентификации не требуется.

Создание пользователя

Рекомендуемый способ создания локального пользователя — команда d8 iam user create. Она поддерживает интерактивный ввод пароля, автоматическую генерацию пароля, добавление в группы и TTL для временных пользователей.

Примеры:

Интерактивный ввод пароля (по умолчанию если stdin — терминал):

d8 iam user create anton --email anton@abc.com

Автогенерация пароля (сгенерированный пароль показывается в выводе команды один раз):

d8 iam user create anton --email anton@abc.com --generate-password

Пароль из stdin (для CI/CD пайплайнов):

echo "s3cret" | d8 iam user create anton --email anton@abc.com --password-stdin

Готовый bcrypt-хеш (например от htpasswd):

d8 iam user create anton --email anton@abc.com --password-hash '$2y$10$abcdef...'

Создать пользователя и добавить в группы (с автосозданием групп):

d8 iam user create anton --email anton@abc.com --generate-password --member-of admins --create-groups

Создать временного пользователя с TTL:

d8 iam user create anton --email anton@abc.com --generate-password --ttl 24h

Предпросмотр манифеста без применения:

d8 iam user create anton --email anton@abc.com --generate-password --dry-run -o yaml

В качестве альтернативы можно создать ресурс User вручную. Придумайте пароль и укажите его хеш-сумму, закодированную в base64, в поле password. Email-адрес должен быть в нижнем регистре.

Для вычисления хеш-суммы пароля воспользуйтесь командой:

echo -n '3xAmpl3Pa$$wo#d' | htpasswd -BinC 10 "" | cut -d: -f2 | tr -d '\n' | base64 -w0; echo

Если команда htpasswd недоступна, установите соответствующий пакет:

  • apache2-utils — для дистрибутивов, основанных на Debian;
  • httpd-tools — для дистрибутивов, основанных на CentOS;
  • apache2-htpasswd — для ALT Linux.

Обратите внимание, что в приведенном примере указан ttl.

apiVersion: deckhouse.io/v1
kind: User
metadata:
  name: admin
spec:
  email: admin@yourcompany.com
  # echo -n '3xAmpl3Pa$$wo#d' | htpasswd -BinC 10 "" | cut -d: -f2 | tr -d '\n' | base64 -w0; echo
  password: 'JDJ5JDEwJGRNWGVGUVBkdUdYYVMyWDFPcGdZdk9HSy81LkdsNm5sdU9mUkhnNWlQdDhuSlh6SzhpeS5H'
  ttl: 24h

Чтобы пользователь сменил пароль при первом входе, укажите requirePasswordChangeOnFirstLogin: true. Поле задаётся только при создании User.

Правила авторизации предоставляют права пользователю на основе email из выданного токена. По этой причине нельзя создать ресурс User, у которого значение spec.email совпадает с субъектом типа User в существующем ресурсе AuthorizationRule или ClusterAuthorizationRule. Это предотвращает незаметное предоставление прав новому пользователю.

Если совпадение необходимо, например, если правило авторизации было создано заранее, укажите другой email или установите для пользователя аннотацию user-authz.deckhouse.io/allow-authorization-rule-collision: "true". Аннотация только подтверждает совпадение имени. Назначить грант по-прежнему можно, только если запрашивающий покрывает роли или они входят в его диапазон can-assign.

При сопоставлении email приводится к нижнему регистру, поскольку в таком виде он записывается в токен. Например, Admin@Example.com совпадает с субъектом admin@example.com.

Ограничение не распространяется на уже существующих пользователей, чей email совпадает с субъектами правил авторизации. Такие пользователи продолжают работать, а при обнаружении совпадения выводится предупреждение.

Учитывайте это ограничение при декларативном управлении пользователями и правилами авторизации. Если пользователь и соответствующее правило создаются одновременно, правило может быть создано раньше пользователя, в результате чего создание пользователя будет отклонено. Чтобы разрешить такое совпадение, добавьте аннотацию user-authz.deckhouse.io/allow-authorization-rule-collision: "true" в манифест User.

При удалении пользователя соответствующий субъект из правила авторизации не удаляется автоматически. Пока он остаётся в правиле, права продолжают предоставляться для указанного email, а система выводит предупреждение об отсутствии соответствующего пользователя. Если впоследствии будет создан пользователь с тем же email, он получит эти права. Если такое поведение не требуется, удалите соответствующий субъект из правила авторизации.

Удаление пользователя

Для удаления локального пользователя используйте команду d8 iam user delete. По умолчанию команда также удаляет пользователя из всех ресурсов Group, в которых он состоит.

Примеры:

Удалить пользователя (и автоматически удалить из всех групп):

d8 iam user delete anton

Удалить пользователя, оставив ссылки в группах:

d8 iam user delete anton --keep-memberships

При удалении пользователя, вручную или по истечении ttl, модуль завершает сессии пользователя так же, как операция Logout (подробнее — в разделе «Жизненный цикл и побочные эффекты UserOperation»), и удаляет его секрет 2FA (TOTP) и блокировку в Dex. Пользователь, созданный заново с тем же именем, не наследует сессии, секрет 2FA и блокировку.

Операции над локальным пользователем

Операции сброса пароля, принудительной смены пароля, сброса 2FA, блокировки, разблокировки и выхода выполняются через ресурс UserOperation. В поле initiatorType указывается, кто инициировал операцию: администратор (admin) или сам пользователь (self).

Не меняйте User.spec.password после создания User (например, с помощью d8 k edit). Это поле нельзя изменить, и оно не обновляет учётные данные в Dex. Сбрасывайте пароль через UserOperation или d8 iam user reset-password.

Административные операции

Для административных действий над локальными пользователями используйте команды d8 iam user. Они создают ресурс UserOperation с initiatorType: admin, дожидаются выполнения операции и выводят результат.

Удалить или пересоздать локального пользователя либо выполнить над ним UserOperation (ResetPassword, RequirePasswordChange, Reset2FA, Lock, Unlock, Logout) можно, только если вы можете назначить все роли, уже выданные email или группам пользователя (покрывающие права или явный диапазон can-assign). initiatorType: self эту проверку не обходит. То же правило действует для объектов DexProvider. Подробнее — в разделе «Ограничение идентичностей провайдера».

После сброса пароля администратором операцией ResetPassword пользователь один раз входит с этим паролем. Затем Dex просит пользователя задать новый пароль, соответствующий парольной политике. Чтобы новый пароль продолжал действовать, укажите в UserOperation resetPassword.requirePasswordChange: false.

Пример интерактивного сброса пароля:

d8 iam user reset-password admin

Пример сброса пароля с чтением нового пароля из stdin:

echo "N3wPa$$wo#d" | d8 iam user reset-password admin --password-stdin

Пример сброса пароля с автоматической генерацией нового пароля:

d8 iam user reset-password admin --generate-password

Если пароль уже захеширован, передайте bcrypt-хеш без кодирования в Base64:

d8 iam user reset-password admin --password-hash '$2y$10$abcdef...'

Пример сброса 2FA:

d8 iam user reset2fa admin

Пример блокировки пользователя на 30 минут:

d8 iam user lock admin 30m

Команда d8 iam user lock блокирует локального пользователя и принимает длительность в секундах, минутах или часах, например 30s, 10m или 1h. Чтобы заблокировать пользователя на несколько дней (lock.for: 7d) или бессрочно (lock.for: permanent), создайте UserOperation, как описано в разделе «Ручное создание UserOperation».

Разблокировка пользователя:

d8 iam user unlock admin

По умолчанию команды ожидают завершения операции. Чтобы только создать UserOperation и вывести его имя, используйте флаг --wait=false.

Операции, которые выполняет сам пользователь

В веб-интерфейсе Deckhouse Platform пользователь может выйти на всех устройствах, а локальный пользователь — сменить пароль. Веб-интерфейс создаёт UserOperation с initiatorType: self для пользователя, который вошёл в систему:

  • При выходе на всех устройствах создаётся операция Logout. Она завершает все сессии пользователя, включая файлы kubeconfig и сессию в веб-интерфейсе. Базовая аутентификация в API Kubernetes через LDAP-провайдер продолжает работать по паролю.
  • При смене пароля создаётся операция RequirePasswordChange. При следующем входе Dex запрашивает текущий пароль и новый, соответствующий парольной политике. Операция не завершает сессии.

Смена пароля доступна только для локальных учётных записей (встроенный коннектор Local). Пользователи, которые входят через внешние провайдеры аутентификации, меняют пароль в соответствующей системе.

Пользователь также видит устройства, на которых выполнен вход в его учётную запись (поле status.sessions его объекта UserAccount), и может выходить на них по одному:

  • При выходе на одном устройстве создаётся операция Logout с полем logout.session для браузера или logout.grant для другого устройства, например файла kubeconfig. Остальные устройства сохраняют свои сессии. Выход на устройстве, на котором вход уже завершён, например по истечении сессии, выполняется успешно.
  • При выходе на остальных устройствах создаётся операция Logout с полем logout.exceptSession или logout.exceptGrant. Сохраняется только устройство, с которого действует пользователь.

Выход на всех устройствах, выход на остальных устройствах или на другом устройстве и смена пароля доступны только на доверенном устройстве — том, на котором вход выполнен не меньше devices.trustedAfter назад (по умолчанию 24 часа). С устройства, на котором вход выполнен позже, можно выйти только на нём самом. Поэтому тот, кто только что вошёл с украденным паролем, не может ни выкинуть владельца, ни сменить пароль, а владелец видит новое устройство в списке на доверенном устройстве и завершает на нём вход. Пользователь без доверенного устройства обращается к администратору: операции администратора не ограничены. С devices.trustedAfter: 0s каждое устройство доверенное сразу.

Возраст устройства считается от первого входа из его браузера, а не только от последнего. При входе Dex выдаёт браузеру долгоживущую cookie и запоминает, когда впервые увидел вход в учётную запись из этого браузера (поле knownSince). Браузер, из которого вышли и снова вошли, сохраняет свой возраст. Dex забывает браузер, и следующий вход из него считается новым, если:

  • последний вход из браузера завершили с другого устройства или это сделал администратор. Пока в браузере есть другая действующая сессия или токен учётной записи, он остаётся знакомым;
  • пользователь вышел на остальных устройствах: забываются все браузеры, кроме текущего, независимо от того, выполнен ли в них вход;
  • пользователь вышел на всех устройствах либо администратор заблокировал пользователя, сбросил пароль, сбросил 2FA или завершил его сеансы;
  • у учётной записи запомненных браузеров больше, чем devices.rememberedBrowsers (по умолчанию 20): забывается браузер, который дольше всех не появлялся. С 0 Dex не помнит браузеры, и каждый вход — новое устройство.

У того, кто входит с украденным паролем, в браузере нет этой cookie, поэтому для него устройство новое. От украденной сессии это не защищает: возраст берётся у сессии или токена запроса, поэтому у скопированной cookie Dex или веб-интерфейса возраст устройства владельца.

Если пароль мог быть украден, действуйте с доверенного устройства в таком порядке:

  1. Запросите смену пароля.
  2. Сразу выйдите на этом устройстве и войдите снова: Dex попросит текущий и новый пароль. Браузер сохраняет свой возраст.
  3. Только после этого выйдите на остальных устройствах. Текущий браузер остаётся знакомым и доверенным, а со всех остальных устройств, в том числе с устройства злоумышленника, выполняется выход.

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

Не начинайте с выхода на всех устройствах: после него текущий браузер тоже становится новым и в течение devices.trustedAfter не может ни запросить смену пароля, ни выкинуть устройство, которое снова вошло с украденным паролем.

Без 2FA для входа в учётную запись достаточно скомпрометированного пароля. Включите 2FA параметром twoFactor.

Ручное создание UserOperation

Когда CLI d8 iam user недоступен (например, в CI/CD или скриптах автоматизации), создайте ресурс UserOperation напрямую. Используйте apiVersion: deckhouse.io/v1 и укажите initiatorType: admin.

Не храните UserOperation в GitOps-репозитории. Модуль удаляет операцию через retention.userOperations, а созданная заново операция выполняется снова.

Пример — сброс пароля локального пользователя (в newPasswordHash указывается bcrypt-хеш без кодирования в Base64; модуль кодирует его автоматически):

apiVersion: deckhouse.io/v1
kind: UserOperation
metadata:
  name: reset-password-admin
spec:
  user: admin
  type: ResetPassword
  initiatorType: admin
  resetPassword:
    newPasswordHash: "$2y$10$..."

Пример — блокировка локального пользователя на 1 час:

apiVersion: deckhouse.io/v1
kind: UserOperation
metadata:
  name: lock-admin-1h
spec:
  user: admin
  type: Lock
  initiatorType: admin
  lock:
    for: "1h"

Пример — бессрочная блокировка:

apiVersion: deckhouse.io/v1
kind: UserOperation
metadata:
  name: lock-admin-permanent
spec:
  user: admin
  type: Lock
  initiatorType: admin
  lock:
    for: "permanent"

Пример — разблокировка:

apiVersion: deckhouse.io/v1
kind: UserOperation
metadata:
  name: unlock-admin
spec:
  user: admin
  type: Unlock
  initiatorType: admin

Пример — сброс 2FA:

apiVersion: deckhouse.io/v1
kind: UserOperation
metadata:
  name: reset-2fa-admin
spec:
  user: admin
  type: Reset2FA
  initiatorType: admin

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

apiVersion: deckhouse.io/v1
kind: UserOperation
metadata:
  name: require-password-change-admin
spec:
  user: admin
  type: RequirePasswordChange
  initiatorType: admin

Пример — завершение всех сессий пользователя во всех приложениях и файлах kubeconfig:

apiVersion: deckhouse.io/v1
kind: UserOperation
metadata:
  name: logout-admin
spec:
  user: admin
  type: Logout
  initiatorType: admin

Пример — выход пользователя на одном устройстве с сохранением сессий на остальных. Возьмите id устройства из поля status.sessions объекта UserAccount пользователя (подробнее — в разделе Просмотр состояния учётной записи). Для устройства вида Browser укажите его в поле logout.session, для устройства вида Grant, например файла kubeconfig, — в поле logout.grant:

apiVersion: deckhouse.io/v1
kind: UserOperation
metadata:
  name: logout-admin-kubeconfig
spec:
  user: admin
  type: Logout
  initiatorType: admin
  logout:
    grant: qx3w2ttiyq5ovzvbuehdcbbse

Если у пользователя нет такой сессии или refresh-токена, например сессия истекла или пользователь уже вышел на этом устройстве, операция ничего не завершает и завершается со статусом Succeeded и сообщением the user has no such session или the user has no such grant. Операция не проверяет, принадлежит ли идентификатор другому пользователю: сессия другого пользователя даёт тот же результат и продолжает действовать. Берите идентификатор из объекта UserAccount того пользователя, который указан в spec.user или spec.target.

Операции над внешними пользователями

Для пользователей внешних провайдеров любого типа (LDAP, Atlassian Crowd, OIDC, SAML, GitHub, GitLab, Bitbucket Cloud) вместо spec.user используется поле spec.target. Для внешних пользователей поддерживаются операции Lock, Unlock, Logout и Reset2FA. Второй фактор может быть только у пользователей провайдеров LDAP и Atlassian Crowd. Для пользователя провайдера другого типа Reset2FA только завершает сессии.

Операция находит учётную запись пользователя по email, который провайдер сообщил при последнем входе пользователя. Поля connectorID и userID сужают поиск до одного провайдера и одного идентификатора пользователя. Блокировка действует на одну пару из провайдера и пользователя. Она блокирует только найденную учётную запись и не блокирует локального пользователя или пользователя другого провайдера с тем же email. Локальный пользователь указывается только в spec.user. Dex проверяет блокировку при каждом входе через провайдер, при каждом запросе с refresh-токеном, при обмене токена и при базовой аутентификации в API-сервере через LDAP-провайдер. Для провайдеров Crowd и OIDC basic-auth-proxy проверяет учётные данные напрямую у провайдера, поэтому при базовой аутентификации блокировка не действует.

Операция завершается ошибкой, если ни у одной учётной записи нет этого email (пользователь ещё ни разу не входил) или если подходит несколько учётных записей. В этом случае укажите connectorID, а если у провайдера несколько пользователей с этим email, то и userID.

Блокировка действует на идентификатор пользователя, который провайдер возвращает при входе, поэтому этот идентификатор должен оставаться одним и тем же при каждом входе пользователя. Для SAML-провайдера укажите в параметре nameIDPolicyFormat значение persistent или emailAddress либо не задавайте параметр (тогда Dex запрашивает persistent). При значении transient провайдер возвращает новый идентификатор при каждом входе. Тогда блокировка не действует при следующем входе пользователя, а после второго входа пользователя операция завершается ошибкой, так как этот email есть у нескольких пользователей провайдера.

Пример — блокировка внешнего пользователя по connectorID + email на 30 минут:

apiVersion: deckhouse.io/v1
kind: UserOperation
metadata:
  name: lock-external-user
spec:
  target:
    connectorID: my-ldap
    email: jane.doe@example.org
  type: Lock
  initiatorType: admin
  lock:
    for: "30m"

Пользователи удалённого провайдера

Если DexProvider удалить и создать заново под тем же именем в течение 30 дней, второй фактор и блокировка его пользователей сохранятся. Если создать его позже, 2FA пользователя, который не входил 30 дней, регистрируется заново при первом входе. Пользователь, блокировка которого ещё действует, сохраняет блокировку и второй фактор до её окончания.

Жизненный цикл и побочные эффекты UserOperation

Использование объекта UserOperation имеет следующие особенности:

  • UserOperation — одноразовый объект. После создания модуль обрабатывает его и записывает результат в status.phase (Succeeded или Failed).
  • Операции автоматически удаляются через retention.userOperations (по умолчанию 24 часа).
  • UserOperation выполняется один раз. Изменения спецификации после создания игнорируются.
  • Для нового действия нужно создать новый UserOperation.

Операции Lock, ResetPassword, Reset2FA и Logout сразу завершают сессии пользователя:

  • Dex отклоняет все refresh-токены, коды авторизации и сессии браузера, которые он выдал пользователю до операции. Приложения и файлы kubeconfig просят пользователя войти заново.
  • DexAuthenticator перестаёт принимать сессии пользователя в течение нескольких секунд.
  • API Kubernetes отклоняет ID-токены, выданные пользователю до операции, в течение нескольких секунд, если в модуле user-authz включён параметр enableMultiTenancy и в кластере работает Kubernetes 1.34 или новее. В остальных случаях эти ID-токены действуют в API Kubernetes до истечения их срока (параметр idTokenTTL).
  • Базовая аутентификация в API Kubernetes через LDAP-провайдер заново проверяет пароль в Dex. После Logout она продолжает работать по паролю.

Unlock и RequirePasswordChange не завершают сессии. Секрет 2FA пользователя удаляет только Reset2FA. Операция Lock запрещает вход, запросы с refresh-токеном и обмен токена до окончания блокировки. Что отозвала операция, показывает её поле status.revocation.

Проверка статуса операции

Для проверки статуса операции выполните следующие действия:

  1. Получите список всех операций:

    d8 k get useroperations
    
  2. Получите полный статус операции:

    d8 k get useroperation <имя> -o yaml
    
  3. Получите только статус завершения:

    d8 k get useroperation <имя> -o jsonpath='{.status.phase}'
    

Просмотр состояния учётной записи

Для каждого локального пользователя и каждого пользователя, входившего через внешний провайдер, модуль ведёт объект UserAccount. В нём видно, когда пользователь входил последний раз, настроил ли он 2FA, заблокирована ли учётная запись, до какого времени и сколько неудачных попыток входа учтено. Не создавайте и не изменяйте объекты UserAccount.

Чтобы посмотреть учётные записи, выполните:

d8 k get useraccounts

В поле status.sessions перечислены устройства, на которых выполнен вход в учётную запись. Первыми идут устройства с самой свежей активностью: браузеры, выполнившие вход в Dex (вид Browser), и устройства с refresh-токеном, не привязанным к действующей сессии Dex в браузере, например файлы kubeconfig (вид Grant). Для каждого устройства видны приложения, адрес клиента и User-Agent при последнем входе, время входа, час последней активности и время, когда сеанс устройства закончится, если им больше не пользоваться (endsAt). Адрес клиента верный, только если его видит Ingress-контроллер (подробнее — в разделе Какой адрес клиента видит Dex?). Чтобы посмотреть устройства учётной записи, выполните:

d8 k get useraccount <ИМЯ> -o jsonpath='{range .status.sessions[*]}{.kind}{"\t"}{.id}{"\t"}{.clients}{"\t"}{.ipAddress}{"\t"}{.lastActivity}{"\t"}{.endsAt}{"\n"}{end}'

Пока браузерные сессии Dex выключены, каждый вход в приложение DexAuthenticator — отдельное устройство.

Максимальное количество устройств, на которых пользователь может одновременно оставаться авторизованным в одном приложении, задаётся параметром devices.maxPerApplication (по умолчанию 10). Браузер считается одним устройством для всех доменов приложения, а каждый файл kubeconfig — отдельным устройством. Если пользователь входит с нового устройства, а лимит из devices.maxPerApplication уже исчерпан, сеанс завершается на том устройстве, которым дольше всего не пользовались. Доверенные устройства (доверенными устройства становятся по истечении времени, указанного в параметре devices.trustedAfter) отключаются в последнюю очередь.

Автоматическая блокировка

Если число неудачных попыток входа превышает passwordPolicy.lockout.maxAttempts, Dex блокирует пользователя на время lockout.lockDuration, после чего снимает блокировку автоматически. Для пользователей LDAP и Crowd это работает, только если тип провайдера указан в lockout.applyToConnectors. UserOperation для такой блокировки Dex не создаёт. Чтобы разблокировать пользователя раньше, выполните d8 iam user unlock или создайте UserOperation с типом Unlock.

Пока локальный пользователь или пользователь LDAP или Crowd заблокирован, Dex отказывает во входе по паролю независимо от того, верен ли пароль: после автоматической блокировки — с кодом 429 и страницей «Account temporarily locked», при блокировке администратором — с кодом 403 и страницей «Account locked by an administrator». Страница смены пароля отказывает заблокированному пользователю так же. Автоматическая блокировка не сокращает блокировку, которая заканчивается позже, в том числе блокировку администратора.

Добавление пользователя в группу

Пользователи могут быть объединены в группы для управления правами доступа. Рекомендуемый способ управления группами — команда d8 iam group.

Примеры:

Создать группу:

d8 iam group create admins

Добавить пользователя в группу:

d8 iam group add-member admins user anton

Добавить вложенную группу:

d8 iam group add-member admins group devops

Удалить пользователя из группы:

d8 iam group remove-member admins user anton

Удалить группу:

d8 iam group delete admins

В качестве альтернативы можно создать ресурс Group вручную. Пример манифеста ресурса Group для группы:

apiVersion: deckhouse.io/v1alpha1
kind: Group
metadata:
  name: admins
spec:
  name: admins
  members:
    - kind: User
      name: admin

Здесь members — список членов: kind: User с name = User.metadata.name, либо вложенная kind: Group с name = Group.spec.name (имя в токене, не metadata.name).

Вложенные группы не должны образовывать цикл. Изменение ресурса Group отклоняется, если после него группа становится членом самой себя напрямую или через другие группы. Если цикл в иерархии уже есть, изменения, которые не создают нового цикла, принимаются с предупреждением. В предупреждении указан путь цикла, в котором каждая группа является членом предыдущей. Чтобы разорвать цикл, удалите одну из этих групп из списка членов предыдущей группы.

Имя группы записывается в выданный токен без изменений. При этом оно неотличимо от имени группы, полученного от внешнего провайдера аутентификации. Поэтому нельзя создать ресурс Group, если значение spec.name совпадает с субъектом типа Group в существующем ресурсе AuthorizationRule или ClusterAuthorizationRule. Это предотвращает незаметное предоставление прав участникам новой группы.

Если совпадение необходимо, переименуйте группу или установите на ней аннотацию user-authz.deckhouse.io/allow-authorization-rule-collision: "true".

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

Ограничение не распространяется на уже существующие группы, имена которых совпадают с субъектами правил авторизации. Такие группы продолжают работать, а при обнаружении совпадения выводится предупреждение.

Учитывайте это ограничение при декларативном управлении группами и правилами авторизации. Если группа и соответствующее правило создаются одновременно, правило может быть создано раньше группы, в результате чего создание группы будет отклонено. Чтобы разрешить такое совпадение, добавьте аннотацию user-authz.deckhouse.io/allow-authorization-rule-collision: "true" в манифест Group.

При удалении группы соответствующий субъект из правила авторизации не удаляется автоматически. Пока он остаётся в правиле, права продолжают предоставляться группе с указанным именем. Группа, впоследствии созданная с тем же именем, получит эти права. Если такое поведение не требуется, удалите соответствующий субъект из правила авторизации.

Просмотр пользователей и групп

Для просмотра пользователей, групп и их прав (группы, выданные права, уровень доступа) используйте команды d8 iam get и d8 iam list.

Примеры:

Список всех пользователей с их правами:

d8 iam list users

Детали для конкретного пользователя (группы, выданные права, уровень доступа):

d8 iam get user anton

Список всех групп:

d8 iam list groups

Детали для конкретной группы (участники, выданные права):

d8 iam get group admins

Парольная политика

Настройки парольной политики позволяют контролировать сложность пароля, ротацию и блокировку пользователей:

apiVersion: deckhouse.io/v1alpha1
kind: ModuleConfig
metadata:
  name: user-authn
spec:
  version: 3
  enabled: true
  settings:
    passwordPolicy:
      complexityLevel: Fair
      passwordHistoryLimit: 10
      lockout:
        lockDuration: 15m
        maxAttempts: 3
      rotation:
        interval: "30d"

Описание полей:

  • complexityLevel — уровень сложности пароля: None, Low, Fair, Good, Excellent или Custom;
  • custom — пользовательские правила сложности (используются только при complexityLevel: Custom):
    • custom.minLength — минимальное количество символов в пароле;
    • custom.specialCharacters — если true, требуется хотя бы один специальный символ;
    • custom.numbers — если true, требуется хотя бы одна цифра;
    • custom.capitalized — если true, требуется хотя бы одна заглавная буква;
    • custom.repeatedChars — если true, запрещается более 2 одинаковых символов подряд;
  • passwordHistoryLimit — число предыдущих паролей, которые хранит система, чтобы предотвратить их повторное использование;
  • lockout — настройки блокировки при превышении лимита неудачных попыток входа:
    • lockout.maxAttempts — лимит неудачных попыток;
    • lockout.lockDuration — длительность блокировки пользователя;
    • lockout.applyToConnectors — типы внешних провайдеров, на пользователей которых также распространяется блокировка: LDAP, Crowd. На локальных пользователей блокировка распространяется всегда;
  • rotation — настройки ротации паролей:
    • rotation.interval — период обязательной смены пароля.

Чтобы ограничить число неудачных попыток входа с одного IP-адреса, используйте параметр rateLimit.

Если локальный пользователь входит с паролем, который нужно сменить, Dex вместо приложения открывает страницу смены пароля. Пароль нужно сменить после сброса администратором операцией ResetPassword, если он не соответствует правилам сложности и если он старше rotation.interval. Страница запрашивает только новый пароль, дважды, потому что форма входа только что проверила текущий. При включённой 2FA Dex сначала запрашивает код и открывает страницу смены пароля только после него, поэтому тот, кто знает только пароль, сменить его не сможет. После смены пароля вход продолжается обычным образом и открывает приложение.

Страница смены пароля открывается только в рамках входа, который на неё привёл, и в том же браузере. Если открыть её в другом браузере или после истечения времени входа, Dex её не откроет, и пользователь входит заново.

Пример с пользовательскими правилами сложности:

apiVersion: deckhouse.io/v1alpha1
kind: ModuleConfig
metadata:
  name: user-authn
spec:
  version: 3
  enabled: true
  settings:
    passwordPolicy:
      complexityLevel: Custom
      custom:
        minLength: 10
        specialCharacters: true
        numbers: false
        capitalized: true
        repeatedChars: false
      passwordHistoryLimit: 10

Двухфакторная аутентификация (2FA)

2FA позволяет повысить уровень безопасности, требуя ввести код из приложения-аутентификатора TOTP (например, Google Authenticator) или использовать ключ безопасности (WebAuthn) при входе. Его можно требовать у локальных пользователей и у пользователей провайдеров LDAP и Atlassian Crowd.

apiVersion: deckhouse.io/v1alpha1
kind: ModuleConfig
metadata:
  name: user-authn
spec:
  version: 4
  enabled: true
  settings:
    twoFactor:
      enabled: true
      issuerName: "awesome-app"
      providerTypes: [Local, LDAP]

Описание полей:

  • enabled — включает или отключает 2FA;
  • issuerName — имя, которое будет отображаться в приложении-аутентификаторе при добавлении аккаунта (при WebAuthn — в окне браузера, который регистрирует ключ);
  • methods — вторые факторы: TOTP (по умолчанию), WebAuthn или оба. Подробнее в разделе «Несколько методов»;
  • require — как сочетаются два метода из methods. Обязателен при двух методах и не допускается при одном;
  • providerTypeOverrides — другие methods для одного типа провайдеров. Подробнее в разделе «Несколько методов»;
  • webAuthn — параметры метода WebAuthn. Подробнее в разделе «Ключи безопасности (WebAuthn)»;
  • providerTypes — типы провайдеров, пользователи которых должны проходить второй фактор: Local (встроенные пользователи), LDAP и Crowd. Второй фактор запрашивается у пользователей каждого провайдера перечисленного типа. Провайдеры OIDC, SAML, GitHub, GitLab и Bitbucket Cloud в списке отсутствуют. Второй фактор для них настраивается на стороне провайдера идентификации.

Параметр twoFactor заменяет staticUsers2FA, который охватывал только локальных пользователей. ModuleConfig версии 3 с staticUsers2FA продолжает работать, потому что модуль преобразует его.

После включения 2FA каждый пользователь должен пройти процесс регистрации в приложении-аутентификаторе при первом входе. Пока он этого не сделал, любой, кто знает пароль, может зарегистрировать своё устройство, поэтому попросите пользователей войти сразу после включения 2FA.

Dex запрашивает код (или ключ) при входе через провайдера перечисленного типа, кроме случая, когда действует браузерная сессия Dex. Входы через остальные провайдеры проходят без кода. Включение 2FA для типа провайдера не завершает refresh-токены и браузерные сессии Dex, выданные раньше. Refresh-токен продолжает выдавать токены без кода до своего истечения (по умолчанию до refreshTokenAbsoluteLifetime, 4380h), а браузерная сессия, созданная до изменения, проходит без кода. После включения выполните UserOperation типа Logout для пользователей провайдеров перечисленных типов.

У базовой аутентификации в API Kubernetes (enableBasicAuth у провайдера LDAP или Crowd) нет страницы для ввода кода, поэтому она невозможна для провайдера перечисленного типа. Модуль отклоняет настройки, которые включают 2FA, пока такой провайдер существует, и провайдера, который включает enableBasicAuth, пока 2FA охватывает его тип. Чтобы использовать и то и другое, выдавайте пользователям API Kubernetes файл kubeconfig через веб-интерфейс вместо базовой аутентификации.

Ключи безопасности (WebAuthn)

При methods: [WebAuthn] Dex просит пользователя коснуться ключа безопасности (например, YubiKey) или подтвердить вход с помощью Touch ID либо Windows Hello устройства вместо ввода кода. Ключ подтверждает вход только для домена, к которому он привязан, поэтому поддельная страница входа на другом домене не получит ответа, который можно использовать повторно.

Следующие настройки требуют от пользователей ключ безопасности:

apiVersion: deckhouse.io/v1alpha1
kind: ModuleConfig
metadata:
  name: user-authn
spec:
  version: 4
  enabled: true
  settings:
    twoFactor:
      enabled: true
      methods: [WebAuthn]
      issuerName: "Example"
      webAuthn:
        rpID: example.com

Принцип работы метода:

  • Ключ привязан к домену, который задаёт параметр rpID. По умолчанию это домен адреса Dex (dex.<PUBLIC_DOMAIN>). Чтобы ключи сохранились при смене publicDomainTemplate, задайте в rpID стабильный родительский домен адреса Dex, например example.com для dex.example.com. Смена rpID или смена publicDomainTemplate без заданного rpID делает все зарегистрированные ключи непригодными. Пользователь с таким ключом не может ни войти, ни зарегистрировать новый. Сбросьте второй фактор пользователя через UserOperation типа Reset2FA, и пользователь зарегистрирует ключ заново при следующем входе.
  • Dex принимает ключ безопасности любого производителя и модели и не проверяет, что это за ключ.
  • Браузер должен поддерживать WebAuthn.
  • Пользователь регистрирует ключ при первом входе после включения метода, как пользователь TOTP регистрирует приложение. Максимальное количество ключей, которое может быть у пользователя, указывается в параметре webAuthn.maxCredentials (по умолчанию 3). Ключ добавляется кнопкой «Добавить ключ» на странице подтверждения входа ключом, после того как вход подтвердил уже зарегистрированный ключ. До регистрации любой, кто знает пароль, может зарегистрировать свой ключ, поэтому попросите пользователей войти сразу после включения.
  • Удалить один ключ нельзя. Если какой-то из ключей был утерян или скомпрометирован, сбросьте метод WebAuthn пользователя операцией Reset2FA. До этого такой ключ продолжает подтверждать вход для того, кто знает пароль. Операция удаляет все ключи пользователя, и при следующем входе он регистрирует ключи заново.
  • При смене методов секрет TOTP и ключи, которые были у пользователя, остаются до Reset2FA, поэтому, если метод снова запрашивается, они возвращаются.

Несколько методов

Если в параметре methods указано два метода, параметр require задаёт, как они сочетаются. При Any пользователь проходит один из них. При первом входе пользователь выбирает метод и регистрирует его. Дальше Dex запрашивает зарегистрированный метод, сначала последний использованный, а пользователь, который зарегистрировал оба, может войти другим способом. Пользователь, у которого зарегистрирован один метод, не может зарегистрировать второй при входе, потому что иначе любой, кто знает пароль, мог бы добавить свой метод. Чтобы пользователь сменил метод, удалите зарегистрированный операцией Reset2FA. При All пользователь проходит оба метода, сначала код, затем ключ. Пользователь, у которого есть только один из них, сначала подтверждает вход им и только потом регистрирует второй.

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

apiVersion: deckhouse.io/v1alpha1
kind: ModuleConfig
metadata:
  name: user-authn
spec:
  version: 4
  enabled: true
  settings:
    twoFactor:
      enabled: true
      methods: [TOTP, WebAuthn]
      require: Any
      webAuthn:
        rpID: example.com

Версия Deckhouse Platform без require: Any отклоняет такие настройки. Перед откатом на неё переключите require на All или оставьте один метод.

providerTypeOverrides задаёт другие методы для одного типа провайдеров из providerTypes, например ключ для пользователей провайдеров LDAP и код для локальных пользователей:

apiVersion: deckhouse.io/v1alpha1
kind: ModuleConfig
metadata:
  name: user-authn
spec:
  version: 4
  enabled: true
  settings:
    twoFactor:
      enabled: true
      methods: [TOTP]
      providerTypes: [Local, LDAP, Crowd]
      providerTypeOverrides:
      - providerType: LDAP
        methods: [WebAuthn]
      - providerType: Crowd
        methods: [TOTP, WebAuthn]
        require: All
      webAuthn:
        rpID: example.com

Тип без записи использует methods и require. Каждый тип указывается один раз, и только тип из providerTypes.

Второй фактор учётной записи

UserAccount показывает в status.twoFactor методы methods и require, которые требуются от пользователей её типа провайдера, а в enrolled — есть ли они у учётной записи. totp и webAuthn показывают секрет TOTP и число ключей учётной записи, в том числе для метода, который больше не запрашивается; такие не учитываются в enrolled.

Чтобы пользователь заново зарегистрировал второй фактор, например после потери устройства, сбросьте его 2FA. Для локального пользователя используйте команду d8 iam user reset2fa <USERNAME> или UserOperation с типом Reset2FA и spec.user. Для пользователя внешнего провайдера используйте UserOperation с типом Reset2FA и spec.target. Без других параметров операция удаляет все методы. Чтобы удалить один, укажите его в spec.reset2FA.methods:

apiVersion: deckhouse.io/v1
kind: UserOperation
metadata:
  name: reset-key-jane
spec:
  type: Reset2FA
  initiatorType: admin
  user: jane
  reset2FA:
    methods: [WebAuthn]

Операция также завершает сессии пользователя. Остальные операции, включая Lock и ResetPassword, второй фактор сохраняют.

Выдача прав пользователю или группе

Чтобы выдать права пользователю или группе, привяжите одну из ролей модуля user-authz через RoleBinding или ClusterRoleBinding, указав в качестве субъекта email пользователя или имя группы. Подробнее — в описании гранулярной ролевой модели.