Стадия жизненного цикла модуля: 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.groupsDexProvider и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.
- «Name»:
После этого в клиенте, зарегистрированном для кластера 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:
- Убедитесь, что в конфигурации модуля
control-plane-managerвключен параметрapiserver.publishAPI. - Установите
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:
- Зарегистрируйте Dex как Service Provider (SP) у вашего провайдера идентификации со следующими параметрами:
- ACS URL (Assertion Consumer Service):
https://<DEX_DOMAIN>/callback - Entity ID:
https://<DEX_DOMAIN>/callback - Формат идентификатора имени:
persistentилиemailAddress
- ACS URL (Assertion Consumer Service):
-
Настройте сопоставление атрибутов в провайдере идентификации для отправки атрибутов
email,name(имя пользователя) иgroupsв SAML assertion. - Экспортируйте сертификат подписи провайдера идентификации и укажите его в поле
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. Claimexpобязателен. - 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): забывается браузер, который дольше всех не появлялся. С0Dex не помнит браузеры, и каждый вход — новое устройство.
У того, кто входит с украденным паролем, в браузере нет этой cookie, поэтому для него устройство новое. От украденной сессии это не защищает: возраст берётся у сессии или токена запроса, поэтому у скопированной cookie Dex или веб-интерфейса возраст устройства владельца.
Если пароль мог быть украден, действуйте с доверенного устройства в таком порядке:
- Запросите смену пароля.
- Сразу выйдите на этом устройстве и войдите снова: Dex попросит текущий и новый пароль. Браузер сохраняет свой возраст.
- Только после этого выйдите на остальных устройствах. Текущий браузер остаётся знакомым и доверенным, а со всех остальных устройств, в том числе с устройства злоумышленника, выполняется выход.
Выполняйте шаги 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.
Проверка статуса операции
Для проверки статуса операции выполните следующие действия:
-
Получите список всех операций:
d8 k get useroperations -
Получите полный статус операции:
d8 k get useroperation <имя> -o yaml -
Получите только статус завершения:
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 пользователя или имя группы. Подробнее — в описании гранулярной ролевой модели.