Настройка

Назначение каждого параметра описано на странице «Обзор». Здесь для каждого типа установки указано место, в котором записывается параметр, и форма его значения.

Где хранится конфигурация

Пакет для ОС Linux. Параметры задаются ключами файла /etc/gitlab/gitlab.rb.

Omnibus Docker. Контейнер читает те же ключи gitlab.rb. Они попадают в него из переменной окружения GITLAB_OMNIBUS_CONFIG, которая вычисляется при каждом запуске, и из файла /etc/gitlab/gitlab.rb на томе конфигурации, который читается после переменной. Ключ, записанный в файле, переопределяет тот же ключ в переменной. Переменная задаётся при создании контейнера:

docker run -d --name code \
  --shm-size 256m \
  -p 80:80 -p 443:443 -p 22:22 \
  -e GITLAB_OMNIBUS_CONFIG="external_url 'https://<HOSTNAME>'; gitlab_rails['omniauth_enabled'] = true; gitlab_rails['omniauth_allow_single_sign_on'] = ['openid_connect']; gitlab_rails['omniauth_auto_link_ldap_user'] = true" \
  -v /srv/code/config:/etc/gitlab \
  -v /srv/code/logs:/var/log/gitlab \
  -v /srv/code/data:/var/opt/gitlab \
  <REGISTRY>/<FLAVOR>:<VERSION>

Переменная фиксируется при создании контейнера, поэтому её изменение означает удаление контейнера и создание нового с теми же томами. Записи провайдеров и LDAP-серверов занимают несколько строк, а том конфигурации сохраняет их при замене контейнера. С томами из быстрого старта файл /etc/gitlab/gitlab.rb внутри контейнера — это /srv/code/config/gitlab.rb на хосте, и редактируется он на хосте:

sudo vi /srv/code/config/gitlab.rb

Helm-чарт. Параметры задаются значениями чарта в файле values.yaml релиза.

Модуль Deckhouse Kubernetes Platform. Параметры задаются в ресурсе CodeInstance, описанном на страницах «Настройка OmniAuth и LDAP» и Custom Resources в документации модуля.

Общие параметры OmniAuth

Параметры и их действие описаны в разделе «Общие параметры OmniAuth».

gitlab_rails['omniauth_enabled'] = true
gitlab_rails['omniauth_allow_single_sign_on'] = ['openid_connect']
gitlab_rails['omniauth_block_auto_created_users'] = true
gitlab_rails['omniauth_auto_link_ldap_user'] = true
gitlab_rails['omniauth_sync_profile_attributes'] = ['email']

global:
  appConfig:
    omniauth:
      enabled: true
      allowSingleSignOn: ['openid_connect']
      blockAutoCreatedUsers: true
      autoLinkLdapUser: true
      syncProfileAttributes: ['email']

enabled: true
allowSingleSignOn: ['openid_connect']
blockAutoCreatedUsers: true
autoLinkLdapUser: true
syncProfileAttributes: ['email']

Провайдер OpenID Connect

Параметры подключения провайдера и их действие описаны в разделе «OpenID Connect (OIDC)».

gitlab_rails['omniauth_providers'] = [
  {
    name: 'openid_connect',   # Не изменяйте это значение.
    label: 'Keycloak',        # Подпись кнопки входа.
    allowed_groups: ['gitlab'],
    admin_groups: ['admin'],
    auditor_groups: ['audit'],
    groups_attribute: 'gitlab_group',
    args: {
      name: 'openid_connect',
      scope: ['openid', 'profile', 'email'],
      response_type: 'code',
      issuer: 'https://keycloak.example.com/realms/example',
      discovery: true,
      client_auth_method: 'query',
      uid_field: 'preferred_username',
      send_scope_to_token_endpoint: false,
      pkce: true,
      client_options: {
        identifier: '<client_id>',
        secret: '<client_secret>',
        redirect_uri: 'https://code.example.com/users/auth/openid_connect/callback'
      }
    }
  }
]

d8 k -n code create secret generic code-omniauth-keycloak \
  --from-file=provider=keycloak.yaml

name: 'openid_connect'
label: 'Keycloak'
allowed_groups:
  - 'gitlab'
admin_groups:
  - 'admin'
groups_attribute: 'gitlab_group'
args:
  name: 'openid_connect'
  scope:
    - 'openid'
    - 'profile'
    - 'email'
  response_type: 'code'
  issuer: 'https://keycloak.example.com/realms/example'
  discovery: true
  client_auth_method: 'query'
  uid_field: 'preferred_username'
  send_scope_to_token_endpoint: false
  pkce: true
  client_options:
    identifier: '<client_id>'
    secret: '<client_secret>'
    redirect_uri: 'https://code.example.com/users/auth/openid_connect/callback'

global:
  appConfig:
    omniauth:
      providers:
        - secret: code-omniauth-keycloak
          key: provider

providers:
  - name: 'openid_connect'   # Не изменяйте это значение.
    label: 'Keycloak'        # Подпись кнопки входа.
    allowedGroups:
      - 'gitlab'
    adminGroups:
      - 'admin'
    groupsAttribute: 'gitlab_group'
    args:
      name: 'openid_connect'
      scope:
        - 'openid'
        - 'profile'
        - 'email'
      response_type: 'code'
      issuer: 'https://keycloak.example.com/realms/example'
      discovery: true
      client_auth_method: 'query'
      uid_field: 'preferred_username'
      send_scope_to_token_endpoint: false
      pkce: true
      client_options:
        identifier: '<client_id>'
        secret: '<client_secret>'
        redirect_uri: 'https://code.example.com/users/auth/openid_connect/callback'

Провайдер SAML

Параметры провайдера SAML и их действие описаны в разделе «SAML».

gitlab_rails['omniauth_providers'] = [
  {
    name: 'saml',
    allowed_groups: ['gitlab'],
    admin_groups: ['admin'],
    groups_attribute: 'gitlab_group'
  }
]

providers:
  - name: 'saml'
    allowedGroups:
      - 'gitlab'
    adminGroups:
      - 'admin'
    groupsAttribute: 'gitlab_group'

LDAP-серверы

Ключ записи сервера является его именем. Назначение параметров подключения описано в разделе «Синхронизация с LDAP»; секция group_sync, которая создаёт группы и назначает роли, описана в разделах «Группы и права доступа» и «Секция role_mapping». Секция group_sync учитывается только у сервера под ключом main (раздел «Область синхронизации»).

gitlab_rails['ldap_enabled'] = true
gitlab_rails['ldap_servers'] = YAML.load <<-'EOS'
  main:
    label: 'Головной офис'
    host: ldap-main.example.com
    port: 3389
    uid: 'cn'
    bind_dn: 'uid=viewer,ou=People,dc=example,dc=com'
    password: 'viewer123'
    base: 'ou=People,dc=example,dc=com'
    # Не учитывать пользователей, заблокированных в каталоге (опционально).
    user_filter: '(!(nsAccountLock=TRUE))'
    # Пользователь найден в LDAP — вход разрешён сразу.
    block_auto_created_users: false
    sync_name: true
    group_sync:
      create_groups: true
      base: 'ou=Groups,dc=example,dc=com'
      filter: '(objectClass=groupOfNames)'
      prefix:
        attribute: 'businessCategory'
        default: 'default-program'
      top_level_group: 'LdapGroups'
      name_mask: '(?<=-)[A-z0-9]*$'
      owner: 'root'
      role_mapping:
        - by_name: '.*-project_manager-.*'
          gitlab_role: 'maintainer'
        - by_name: '.*-developer-.*'
          gitlab_role: 'developer'
        - by_name: '.*-participant-.*'
          gitlab_role: 'reporter'
  contractors:
    label: 'Подрядчики'
    host: ldap-contractors.example.com
    port: 3389
    uid: 'cn'
    bind_dn: 'uid=viewer,ou=People,dc=contractors,dc=example,dc=com'
    password: 'viewer123'
    base: 'ou=People,dc=contractors,dc=example,dc=com'
EOS

d8 k -n code create secret generic code-ldap-password \
  --from-literal=password='viewer123'

global:
  appConfig:
    ldap:
      servers:
        main:
          label: 'Головной офис'
          host: ldap-main.example.com
          port: 3389
          uid: 'cn'
          bind_dn: 'uid=viewer,ou=People,dc=example,dc=com'
          password:
            secret: code-ldap-password
            key: password
          base: 'ou=People,dc=example,dc=com'
          user_filter: '(!(nsAccountLock=TRUE))'
          block_auto_created_users: false
          sync_name: true
          group_sync:
            create_groups: true
            base: 'ou=Groups,dc=example,dc=com'
            filter: '(objectClass=groupOfNames)'
            top_level_group: 'LdapGroups'
            owner: 'root'
            role_mapping:
              - by_name: '.*-developer-.*'
                gitlab_role: 'developer'
        contractors:
          label: 'Подрядчики'
          host: ldap-contractors.example.com
          port: 3389
          uid: 'cn'
          bind_dn: 'uid=viewer,ou=People,dc=contractors,dc=example,dc=com'
          password:
            secret: code-ldap-password
            key: password
          base: 'ou=People,dc=contractors,dc=example,dc=com'

servers:
  main:
    label: ldap
    host: 127.0.0.1
    port: 3389
    bindDn: 'uid=viewer,ou=People,dc=example,dc=com'
    base: 'ou=People,dc=example,dc=com'
    uid: 'cn'
    password: 'viewer123'
    syncName: true
    groupSync:
      createGroups: true
      base: 'ou=Groups,dc=example,dc=com'
      filter: '(objectClass=groupOfNames)'
      prefix:
        attribute: 'businessCategory'
        default: 'default-program'
      topLevelGroup: 'LdapGroups'
      nameMask: '(?<=-)[A-z0-9]*$'
      owner: 'root'
      roleMapping:
        - byName: '.*-project_manager-.*'
          gitlabRole: 'Maintainer'
        - byName: '.*-developer-.*'
          gitlabRole: 'Developer'
        - byName: '.*-participant-.*'
          gitlabRole: 'Reporter'

Несколько LDAP-серверов

Несколько серверов описываются повторением записи сервера под другим ключом. У каждого сервера собственные параметры подключения; секция group_sync со всем её содержимым учитывается только у сервера под ключом main (раздел «Область синхронизации»). Идентификация пользователя и решение о доступе, когда один и тот же пользователь найден на нескольких серверах, описаны в разделе «Несколько LDAP-серверов».

servers:
  main:
    label: 'Головной офис'
    host: ldap-main.example.com
    base: 'ou=People,dc=example,dc=com'
    uid: 'cn'
    # Остальные параметры подключения.
    groupSync:
      base: 'ou=Groups,dc=example,dc=com'
      roleMapping:
        - byName: '.*-developer-.*'
          gitlabRole: 'Developer'
  contractors:
    label: 'Подрядчики'
    host: ldap-contractors.example.com
    base: 'ou=People,dc=contractors,dc=example,dc=com'
    uid: 'cn'
    # Остальные параметры подключения.

Связывание учётных записей OIDC с LDAP

Автоматическое связывание OIDC-учётной записи с учётной записью LDAP включается параметром auto_link_ldap_user. Как ищется учётная запись LDAP и что происходит при первом и последующих входах, описано в разделе «Связывание учётных записей OIDC с LDAP».

gitlab_rails['omniauth_auto_link_ldap_user'] = true

global:
  appConfig:
    omniauth:
      autoLinkLdapUser: true

autoLinkLdapUser: true

Вход пользователей, найденных в LDAP

Чтобы пользователи, найденные в LDAP, могли входить сразу, а остальные отправлялись на одобрение администратору, сочетайте параметры auto_link_ldap_user и block_auto_created_users секции OmniAuth с параметром block_auto_created_users LDAP-сервера main (раздел «Вход пользователей, найденных в LDAP»).

gitlab_rails['omniauth_auto_link_ldap_user'] = true
# Пользователь не найден в LDAP — учётная запись создаётся заблокированной,
# до одобрения администратором.
gitlab_rails['omniauth_block_auto_created_users'] = true
gitlab_rails['ldap_servers'] = YAML.load <<-'EOS'
  main:
    # Пользователь найден в LDAP — вход разрешён сразу.
    block_auto_created_users: false
    # Остальные параметры подключения.
EOS

global:
  appConfig:
    omniauth:
      autoLinkLdapUser: true
      # Пользователь не найден в LDAP — учётная запись создаётся заблокированной,
      # до одобрения администратором.
      blockAutoCreatedUsers: true
    ldap:
      servers:
        main:
          # Пользователь найден в LDAP — вход разрешён сразу.
          block_auto_created_users: false

omniauth:
  autoLinkLdapUser: true
  # Пользователь не найден в LDAP — учётная запись создаётся заблокированной,
  # до одобрения администратором.
  blockAutoCreatedUsers: true
ldap:
  servers:
    main:
      # Пользователь найден в LDAP — вход разрешён сразу.
      blockAutoCreatedUsers: false

Расписание синхронизации

Расписание задачи синхронизации записывается в формате cron. Что задача делает при каждом запуске, описано в разделе «Синхронизация с LDAP»; запуск вручную описан в разделе «Ручной запуск синхронизации».

gitlab_rails['ldap_sync_worker_cron'] = "0 * * * *"

global:
  appConfig:
    cron_jobs:
      ldap_sync_worker:
        cron: "0 * * * *"

cronJobs:
  ldapSyncWorker:
    cron: "0 * * * *"

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

sudo gitlab-ctl reconfigure

docker exec code gitlab-ctl reconfigure

docker restart code

helm upgrade code deckhouse-code \
  -n code \
  -f values.yaml

Пример настройки: вход через OIDC и права из LDAP

Ниже приведена последовательность настройки, при которой пользователи входят через OIDC-провайдера (например, Keycloak), а группы, членства в них и роли приходят из LDAP.

Настройка включает в себя следующие шаги:

1. Настройка LDAP-провайдера.
2. Настройка OIDC-провайдера и включение связывания с LDAP.
3. Проверка связывания при первом входе.
4. Синхронизация прав.

Требования для настройки

Для настройки требуются:

• OIDC-провайдер.
• LDAP-каталог с теми же пользователями и с группами, имена которых позволяют определить роль.
• Сервисная учётная запись LDAP с правами на чтение каталога (параметры bind_dn и password).

Порядок поиска учётной записи описан в разделе «Как ищется учётная запись LDAP».

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

В записи сервера указываются каталог, база поиска и сервисная учётная запись, а её секция group_sync превращает имена групп в роли.

gitlab_rails['ldap_enabled'] = true
gitlab_rails['ldap_servers'] = YAML.load <<-'EOS'
  main:
    label: ldap
    host: ldap.example.com
    port: 3389
    bind_dn: 'uid=viewer,ou=People,dc=example,dc=com'
    password: 'viewer123'
    base: 'ou=People,dc=example,dc=com'
    uid: 'cn'
    sync_name: true
    # Не учитывать пользователей, заблокированных в каталоге (опционально).
    user_filter: '(!(nsAccountLock=TRUE))'
    # Пользователь найден в LDAP — вход разрешён сразу.
    block_auto_created_users: false
    group_sync:
      create_groups: true
      base: 'ou=Groups,dc=example,dc=com'
      filter: '(objectClass=groupOfNames)'
      top_level_group: 'LdapGroups'
      name_mask: '(?<=-)[A-z0-9]*$'
      owner: 'root'
      role_mapping:
        - by_name: '.*-maintainer-.*'
          gitlab_role: 'maintainer'
        - by_name: '.*-developer-.*'
          gitlab_role: 'developer'
        - by_name: '.*-participant-.*'
          gitlab_role: 'reporter'
EOS

global:
  appConfig:
    ldap:
      servers:
        main:
          label: ldap
          host: ldap.example.com
          port: 3389
          bind_dn: 'uid=viewer,ou=People,dc=example,dc=com'
          password:
            secret: code-ldap-password
            key: password
          base: 'ou=People,dc=example,dc=com'
          uid: 'cn'
          sync_name: true
          # Не учитывать пользователей, заблокированных в каталоге (опционально).
          user_filter: '(!(nsAccountLock=TRUE))'
          # Пользователь найден в LDAP — вход разрешён сразу.
          block_auto_created_users: false
          group_sync:
            create_groups: true
            base: 'ou=Groups,dc=example,dc=com'
            filter: '(objectClass=groupOfNames)'
            top_level_group: 'LdapGroups'
            name_mask: '(?<=-)[A-z0-9]*$'
            owner: 'root'
            role_mapping:
              - by_name: '.*-maintainer-.*'
                gitlab_role: 'maintainer'
              - by_name: '.*-developer-.*'
                gitlab_role: 'developer'
              - by_name: '.*-participant-.*'
                gitlab_role: 'reporter'

servers:
  main:
    label: ldap
    host: ldap.example.com
    port: 3389
    bindDn: 'uid=viewer,ou=People,dc=example,dc=com'
    password: 'viewer123'
    base: 'ou=People,dc=example,dc=com'
    uid: 'cn'
    syncName: true
    # Не учитывать пользователей, заблокированных в каталоге (опционально).
    userFilter: '(!(nsAccountLock=TRUE))'
    # Пользователь найден в LDAP — вход разрешён сразу.
    blockAutoCreatedUsers: false
    groupSync:
      createGroups: true
      base: 'ou=Groups,dc=example,dc=com'
      filter: '(objectClass=groupOfNames)'
      topLevelGroup: 'LdapGroups'
      nameMask: '(?<=-)[A-z0-9]*$'
      owner: 'root'
      roleMapping:
        - byName: '.*-maintainer-.*'
          gitlabRole: 'Maintainer'
        - byName: '.*-developer-.*'
          gitlabRole: 'Developer'
        - byName: '.*-participant-.*'
          gitlabRole: 'Reporter'

Настройка OIDC-провайдера и включение связывания с LDAP

Значение uid_field используется при поиске пользователя в LDAP. Оно должно совпадать со значением атрибута, указанного в параметре uid LDAP-сервера, или с адресом электронной почты — подробнее в разделе «Как ищется учётная запись LDAP».

Остальные параметры провайдера описаны в разделе «OpenID Connect (OIDC)».

gitlab_rails['omniauth_enabled'] = true
gitlab_rails['omniauth_auto_link_ldap_user'] = true
gitlab_rails['omniauth_providers'] = [
  {
    name: 'openid_connect',   # Не изменяйте это значение.
    label: 'Keycloak',        # Подпись кнопки входа.
    groups_attribute: 'gitlab_group',
    args: {
      name: 'openid_connect',
      scope: ['openid', 'profile', 'email'],
      response_type: 'code',
      issuer: 'https://keycloak.example.com/realms/example',
      discovery: true,
      client_auth_method: 'query',
      uid_field: 'preferred_username',
      send_scope_to_token_endpoint: false,
      pkce: true,
      client_options: {
        identifier: '<client_id>',
        secret: '<client_secret>',
        redirect_uri: 'https://code.example.com/users/auth/openid_connect/callback'
      }
    }
  }
]

global:
  appConfig:
    omniauth:
      enabled: true
      autoLinkLdapUser: true
      providers:
        - secret: code-omniauth-keycloak
          key: provider

autoLinkLdapUser: true
providers:
  - name: 'openid_connect'   # Не изменяйте это значение.
    label: 'Keycloak'        # Подпись кнопки входа.
    groupsAttribute: 'gitlab_group'
    args:
      name: 'openid_connect'
      scope:
        - 'openid'
        - 'profile'
        - 'email'
      response_type: 'code'
      issuer: 'https://keycloak.example.com/realms/example'
      discovery: true
      client_auth_method: 'query'
      uid_field: 'preferred_username'
      send_scope_to_token_endpoint: false
      pkce: true
      client_options:
        identifier: '<client_id>'
        secret: '<client_secret>'
        redirect_uri: 'https://code.example.com/users/auth/openid_connect/callback'

Проверка связывания при первом входе

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

1. Войдите под тестовым пользователем через OIDC-провайдера.
2. Откройте страницу пользователя в административном разделе (/admin/users/<username>/identities). У связанной учётной записи должно быть два идентификатора: openid_connect и ldapmain (имя LDAP-идентификатора складывается из префикса ldap и имени LDAP-сервера, в примере — main).

Если LDAP-идентификатора нет, проверьте следующее:

• значения uid или email в OIDC-провайдере и в LDAP совпадают;
• пользователь попадает в область поиска base и не отсекается фильтром user_filter;
• параметр auto_link_ldap_user включён.

Синхронизация прав

Сразу после первого входа у пользователя есть учётная запись, но нет членства в группах и проектах. Дождитесь ближайшей синхронизации или запустите её вручную (раздел «Ручной запуск синхронизации»), после чего проверьте, что:

• группы созданы внутри группы, указанной в group_sync.top_level_group;
• пользователь добавлен в них с ролью, соответствующей role_mapping.