Интеграция с внешними провайдерами аутентификации

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

DKP поддерживает подключение следующих внешних провайдеров и протоколов аутентификации:

• LDAP (например, Active Directory);
• OIDC (например, Okta, Keycloak, Gluu, Blitz Identity Provider);
• GitHub;
• GitLab;
• Atlassian Crowd;
• Bitbucket Cloud.

Общая схема интеграции

1. Создайте OAuth-приложение у провайдера аутентификации:
   • укажите Redirect URI вида https://dex.<publicDomainTemplate>/callback;
   • получите clientID и clientSecret.

   Важно. При указании Redirect URI подставьте значение publicDomainTemplate без %s. Например, если указано publicDomainTemplate: '%s.sandbox1.deckhouse-docs.flant.com', то фактический URI будет https://dex.sandbox20.deckhouse-docs.flant.com/callback.

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

   d8 k -n d8-user-authn get ingress dex -o jsonpath="{.spec.rules[*].host}"
   

2. Создайте ресурс DexProvider с учётом специфики выбранного провайдера.

3. Включите модуль user-authn (если он выключен).

   Сделать это можно как через веб-интерфейс администратора, так и через CLI. Далее приведен пример работы через CLI (требуется kubectl настроенный на работу с кластером).

   Проверьте статус модуля:

   d8 k get module user-authn
   

   Пример вывода:

   NAME         STAGE   SOURCE     PHASE       ENABLED   READY
   user-authn           Embedded   Available   True      True
   

   Включите модуль через CLI:

   d8 platform module enable user-authn
   

4. Настройте модуль user-authn.

   • Откройте настройки модуля user-authn (создайте ресурс ModuleConfig user-authn, если его нет):

     d8 k edit mc user-authn
     

   • Укажите необходимые параметры модуля в секции spec.settings. Подробнее о настройках модуля user-authn можно узнать в разделе справки модуля.

     Пример конфигурации user-authn:

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

Интеграция по OIDC (OpenID Connect)

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

Полученные в ходе выполнения инструкции clientID и clientSecret укажите в ресурсе DexProvider.

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

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

Keycloak

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

1. Создайте в разделе Client scopes scope с именем groups, и назначьте ему предопределенный маппинг Group Membership («Client scopes» → «Client scope details» → «Mappers» → «Configure a new mapper»). В поле «Name» и «Token Claim Name» впишите groups, в параметре «Full group path» задайте off.
2. В созданном ранее клиенте добавьте данный scope во вкладке Client scopes («Clients → «Client details» → «Client Scopes» → «Add client scope»).
3. В полях «Valid redirect URIs», «Valid post logout redirect URIs» и «Web origins» конфигурации клиента укажите https://dex.<publicDomainTemplate>/*, где publicDomainTemplate – это указанный шаблон DNS-имен кластера в модуле global.

Пример настройки провайдера для интеграции с 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.

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

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

  scopes:
   - openid
   - profile
   - email_dkp
   - groups
  

Blitz Identity Provider

Пример настройки провайдера для интеграции с 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
    insecureSkipEmailVerified: true # Установить true, если нет необходимости в проверке email пользователя.
    insecureSkipVerify: false
    issuer: https://yourdomain.idblitz.ru/blitz
    promptType: consent 
    scopes:
    - profile
    - openid
    userIDKey: sub
    userNameKey: email
  type: OIDC

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
    insecureSkipEmailVerified: true
    getUserInfo: true

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

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

Интеграция по LDAP

Для настройки аутентификации создайте в LDAP учетную запись с правами только на чтение (service account). Эта учетная запись будет использоваться для выполнения поисковых запросов в каталоге LDAP.

В ресурсе DexProvider укажите следующие параметры:​

• bindDN: Полный DN (Distinguished Name) созданного service account. Например: cn=readonly,dc=example,dc=org.
• bindPW: Пароль для указанного bindDN.

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

apiVersion: deckhouse.io/v1
kind: DexProvider
metadata:
  name: active-directory
spec:
  type: LDAP
  displayName: Active Directory
  ldap:
    host: ad.example.com:636
    insecureSkipVerify: true

    bindDN: cn=Administrator,cn=users,dc=example,dc=com
    bindPW: admin0!

    usernamePrompt: Email Address

    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

Интеграция с GitHub

В организации GitHub необходимо создать новое приложение.

Для этого выполните следующие шаги:

1. Перейдите в «Settings» → «Developer settings» → «OAuth App» → «New OAuth App», и в качестве «Authorization callback URL» укажите адрес https://dex.<publicDomainTemplate>/callback.
2. Полученные Client ID и Client Secret укажите в ресурсе DexProvider.

Если организация GitHub находится под управлением клиента:

1. Перейдите в «Settings» → «Applications» → «Authorized OAuth Apps» → <имя созданного OAuth-приложения> и нажмите «Send Request» для подтверждения.
2. Попросите клиента подтвердить запрос, который придет к нему на email.

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

apiVersion: deckhouse.io/v1
kind: DexProvider
metadata:
  name: github
spec:
  type: Github
  displayName: My Company GitHub
  github:
    clientID: plainstring
    clientSecret: plainstring

Интеграция с GitLab

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

Для этого выполните следующие шаги:

1. Self-hosted-версия GitLab: перейдите в «Admin Area» → «Applications» → «New application» и в качестве «Redirect URI (Callback url)» укажите адрес https://dex.<publicDomainTemplate>/callback, а также выберите «scopes»: read_user, openid.
2. GitLab Cloud (gitlab.com): под главной учетной записью проекта перейдите в «User Settings» → «Applications» → «Add new application» и в качестве «Redirect URI (Callback url)» укажите адрес https://dex.<publicDomainTemplate>/callback, а также выберите «scopes»: read_user, openid.
3. Полученные Application ID и секрет укажите в ресурсе DexProvider.

Пример настройки провайдера для интеграции с 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

Интеграция с Atlassian Crowd

В соответствующем проекте Atlassian Crowd необходимо создать новое Generic-приложение.

Для этого выполните следующие шаги:

1. Перейдите в «Applications» → «Add application».
2. Полученные «Application Name» и «Password» укажите в ресурсе DexProvider.
3. При указании групп в ресурсе DexProvider убедитесь, что их названия приведены к нижнему регистру (lowercase). Это необходимо для корректного сопоставления групп между Crowd и Deckhouse.

Пример настройки провайдера для интеграции с 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
    enableBasicAuth: true
    groups:
    - administrators
    - users

Интеграция с Bitbucket Cloud

Для настройки аутентификации необходимо в меню команды Bitbucket создать нового OAuth пользователя (consumer).

Для этого выполните следующие шаги:

1. Перейдите в «Personal settings» → «Access management» → «OAuth consumers» → «Add consumer» и в качестве «Callback URL» укажите адрес https://dex.<publicDomainTemplate>/callback.
2. Разрешите доступ: «Account: Read» → позволяет получать основную информацию о пользователе (например, email, имя пользователя), «Workspace membership → Read»: позволяет получать информацию о членстве пользователя в рабочих пространствах.
3. Полученные Key и секрет укажите в ресурсе DexProvider.

Пример настройки провайдера для интеграции с 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