Настройка интеграции с LDAP

Примечание

Выполняется пользователем с правами Администратор.

Система позволяет настроить интеграцию с большинством известных LDAP-совместимых серверов:

• Microsoft Active Directory.
• Apple Open Directory.
• Open LDAP.
• 389 Server.

Примечание

Система не поддерживает Microsoft Active Directory Trusts.

Примечание

LDAP-пользователи должны иметь адрес электронной почты, независимо от того, используется ли он для авторизации.

Основные настройки конфигурации

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

Настройка	Обязат.	Тип	Описание
label	Да	Строк.	Удобное для человека имя LDAP-сервера, которое отображается на странице авторизации. Например: Paris или Acme, Ltd
host	Да	Строк.	IP-адрес или доменное имя LDAP-сервера. Игнорируется, если определены хосты. Например: ldap.mydomain.com
port	Да	Целочисл.	Порт соединения с LDAP-сервером. Игнорируется, если определены хосты. Например: 389 или 636 (для SSL)
uid	Да	Строк.	Атрибут LDAP, сопоставляемый с именем пользователя, которое он использует для входа в систему. Это должен быть атрибут, а не значение, сопоставляемое с uid. Не влияет на имя пользователя Системы. Например: sAMAccountName или uid, или userPrincipalName
base	Да	Строк.	База, в которой осуществляется поиск пользователей. Например: ou=people,dc=appseccode,dc=example или DC=mydomain,DC=com
hosts	Нет	Массив строк и целочисленных значений	Массив пар хостов и портов для открытия соединений. Каждый настроенный сервер должен иметь такой набор данных. Это не означает, что необходимо конфигурировать несколько отдельных LDAP-серверов — используется только в целях повышения отказоустойчивости. Хосты перебираются в порядке их появления в конфигурации. Например: [['ldap1.mydomain.com', 636], ['ldap2.mydomain.com', 636]]
bind_dn	Нет	Строк.	Полное DN пользователя, с которым устанавливается связь. Например: america\momo или CN=AppSecCode,OU=Users,DC=domain,DC=com
password	Нет	Строк.	Пароль пользователя, с которым устанавливается связь
verify_certificates	Нет	Логич.	По умолчанию имеет значение true. Включает проверку сертификата SSL, если методом шифрования является start_tls или simple_tls. Если установлено значение false, проверка SSL-сертификата LDAP-сервера не производится
timeout	Нет	Целочисл.	Значение по умолчанию — 10. Таймаут LDAP-запросов (в секундах) — позволяет избежать блокировки запроса, если LDAP-сервер не отвечает на него
active_directory	Нет	Логич.	Параметр определяет, является ли LDAP-сервер сервером Active Directory. Для серверов, не являющихся серверами AD, он пропускает запросы, специфичные для AD. Если LDAP-сервер не является сервером AD, установите значение false
allow_username_or_email_login	Нет	Логич.	Значение по умолчанию — false. Если этот параметр включен, то Система игнорирует все, что следует за первым символом «@» в имени пользователя LDAP при авторизации. Если используется uid: 'userPrincipalName' в Active Directory, вы должны отключить этот параметр, поскольку имя userPrincipalName содержит символ «@»
block_auto_created_users	Нет	Логич.	Значение по умолчанию — false. Включите этот параметр, чтобы блокировать новых пользователей, пока они не будут разрешены администратором
user_filter	Нет	Строк.	Фильтр пользователей LDAP. Соответствует формату RFC 4515. Система не поддерживает пользовательский синтаксис фильтра omniauth-ldap. Примеры синтаксиса поля user_filter: – '(employeeType=developer)'; – '(&(objectclass=user)(|(samaccountname=momo)(samaccountname=toto)))'
lowercase_usernames	Нет	Логич.	Если эта опция включена, Система преобразует имена в нижний регистр
retry_empty_result_with_codes	Нет	Array	Массив кодов ответов на запросы LDAP, которые пытаются повторить операцию, если результат/содержимое пуст. Для Google Secure LDAP установите значение [80]

Приведем пример настройки LDAP с базовыми параметрами конфигурации.

1. Отредактируйте файл docker-compose.yml:

   version: "3.6"
   services:
       appseccode:
           image: 'appseccode/appseccode:latest'
           restart: always
           hostname: 'yoursite.ru'
           environment:
               GITLAB_OMNIBUS_CONFIG: |
                   gitlab_rails['ldap_enabled'] = true
                   gitlab_rails['ldap_servers'] = {
                       'main' => {
                           'label' => 'LDAP',
                           'host' =>  'ldap.mydomain.com',
                           'port' => 636,
                           'uid' => 'sAMAccountName',
                           'bind_dn' => 'CN=AppSecCode,OU=Users,DC=domain,DC=com',
                           'password' => '<bind_user_password>',
                           'encryption' => 'simple_tls',
                           'verify_certificates' => true,
                           'timeout' => 10,
                           'active_directory' => false,
                           'user_filter' => '(employeeType=developer)',
                           'base' => 'dc=example,dc=com',
                           'lowercase_usernames' => 'false',
                           'retry_empty_result_with_codes' => [80],
                           'allow_username_or_email_login' => false,
                           'block_auto_created_users' => false
                       }
                   }
   

2. Сохраните файл и выполните переконфигурацию Системы:

   appseccode-ctl reconfigure
   

Настройка SSL

Параметры конфигурации SSL могут быть заданы в tls_options через пары имен/значений. Доступны следующие параметры конфигурации SSL:

Настройка	Описание	Обязат.	Пример
ca_file	Путь к файлу, содержащему СА-сертификат в формате PEM, например, при использовании внутреннего CA	Нет	'/etc/ca.pem'
ssl_version	Версия SSL для использования OpenSSL, если версия OpenSSL по умолчанию не подходит	Нет	'TLSv1_1'
ciphers	SSL-шифры для использования при взаимодействии с LDAP-серверами	Нет	'ALL:!EXPORT:!LOW:!aNULL:!eNULL:!SSLv2'
Cert	Сертификат клиента	Нет	'-----BEGIN CERTIFICATE----- <REDACTED> -----END CERTIFICATE -----'
Key	Приватный ключ клиента	Нет	'-----BEGIN PRIVATE KEY----- <REDACTED> -----END PRIVATE KEY -----'

Пример ниже иллюстрирует определение ca_file и ssl_version в tls_options:

1. Отредактируйте файл docker-compose.yml:

   version: "3.6"
   services:
       appseccode:
           image: 'appseccode/appseccode:latest'
           restart: always
           hostname: 'yoursite.ru'
           environment:
               GITLAB_OMNIBUS_CONFIG: |
                   gitlab_rails['ldap_enabled'] = true
                   gitlab_rails['ldap_servers'] = {
                       'main' => {
                           'label' => 'LDAP',
                           'host' =>  'ldap.mydomain.com',
                           'port' => 636,
                           'uid' => 'sAMAccountName',
                           'encryption' => 'simple_tls',
                           'base' => 'dc=example,dc=com',
                           'tls_options' => {
                               'ca_file' => '/path/to/ca_file.pem',
                               'ssl_version' => 'TLSv1_2'
                           }
                       }
                   }
   

2. Сохраните файл и перезапустите Систему:

   docker compose up -d
   

Параметры конфигурации атрибутов

Система использует приведенные ниже LDAP-атрибуты для создания аккаунта LDAP-пользователя. Могут использоваться следующие атрибуты:

• Имя атрибута, как строковая переменная, например: 'mail'.
• Массив имен атрибутов, которые перебираются по порядку. Например: ['mail', 'email'].

LDAP-атрибут пользователя, который используется для авторизации — uid.

Необходимо определить следующие атрибуты в хеше attributes.

Настройка	Описание	Обязат.	Пример
username	Используется в путях к собственным проектам пользователя (например, yoursite.ru/username/project) и при упоминании их в проблемах, запросах на слияние и комментариях (например, @username). Если атрибут, указанный для имени пользователя, содержит адрес электронной почты, то имя пользователя Системы является частью адреса электронной почты перед символом «@»	Нет	['uid', 'userid', 'sAMAccountName']
email	LDAP-атрибут для электронной почты пользователя	Нет	['mail', 'email', 'userPrincipalName']
name	LDAP-атрибут для отображаемого имени пользователя. Если name пуст, используется полное имя, взятое из атрибутов first_name и last_name	Нет	Атрибуты 'cn' или 'displayName' обычно содержат полные имена. В качестве альтернативы можно принудительно использовать first_name и last_name, указав отсутствующий атрибут, например, 'somethingNonExistent'
first_name	LDAP-атрибут для имени пользователя. Используется, когда атрибут для name не сконфигурирован	Нет	'givenName'
last_name	LDAP-атрибут для фамилии пользователя. Используется, когда атрибут для name не сконфигурирован	Нет	'sn'

Настройки синхронизации LDAP-конфигурации

Доступны следующие настройки синхронизации LDAP-конфигурации:

Настройка	Описание	Обязат.	Пример
group_base	База, используемая для поиска групп	Нет (обязат., когда сконфигурирован external_groups)	'ou=groups,dc=appseccode,dc=example'
admin_group	CN группы администраторов Системы	Нет	'administrators'
external_groups	Массив CN групп, содержащих пользователей, которые должны рассматриваться в качестве внешних	Нет	['interns', 'contractors']
sync_ssh_keys	LDAP-атрибут, содержащий публичный SSH-ключ пользователя	Нет	'sshPublicKey' или false, если не задан

Использование нескольких LDAP-серверов

Можно сконфигурировать систему для работы с несколькими LDAP-серверами. Чтобы добавить дополнительный LDAP-сервер:

1. Продублируйте main LDAP-конфигурацию.

2. Отредактируйте каждую скопированную конфигурацию для использования дополнительных серверов.

   • Для каждого дополнительного сервера, выберите другой ID-провайдера, например main, secondary или tertiary. Используйте цифры и буквы в нижнем регистре. Система использует ID провайдера, чтобы связать каждого пользователя с определенным LDAP-сервером.
   • Для каждой записи используйте уникальное значение метки label. Эти значения используются для названия вкладок на странице авторизации.

Ниже приведена минимальная конфигурация трех LDAP-серверов:

1. Отредактируйте файл docker-compose.yml:

   version: "3.6"
   services:
       appseccode:
           image: 'appseccode/appseccode:latest'
           restart: always
           hostname: 'yoursite.ru'
           environment:
               GITLAB_OMNIBUS_CONFIG: |
                   gitlab_rails['ldap_enabled'] = true
                   gitlab_rails['ldap_servers'] = {
                       'main' => {
                           'label' => 'AD1',
                           'host' =>  'ad.mydomain.com',
                           'port' => 636,
                           'uid' => 'sAMAccountName',
                           'encryption' => 'simple_tls',
                           'base' => 'dc=example,dc=com',
                       },
   
                       'secondary' => {
                           'label' => 'AD2',
                           'host' =>  'ad-secondary.mydomain.com',
                           'port' => 636,
                           'uid' => 'sAMAccountName',
                           'encryption' => 'simple_tls',
                           'base' => 'dc=example,dc=com',
                       },
   
                       'tertiary' => {
                           'label' => 'AD3',
                           'host' =>  'ad-tertiary.mydomain.com',
                           'port' => 636,
                           'uid' => 'sAMAccountName',
                           'encryption' => 'simple_tls',
                           'base' => 'dc=example,dc=com',
                       }
                   }
   

2. Сохраните файл из перезапустите Систему:

   docker compose up -d
   

В результате применения приведенных в это примере настроек на странице входа в систему появятся следующие вкладки:

• AD1.
• AD2.
• AD3.

Включение перевода имен LDAP-пользователей в нижний регистр

Некоторые LDAP-серверы, в зависимости от их конфигурации, могут возвращать имена пользователей в верхнем регистре, что может приводить к некоторым проблемам, например, создание ссылок или пространств имен с использованием букв в верхнем регистре.

Система автоматически переводит имя пользователя, предоставленное LDAP-сервером в нижний регистр, если выбрана опция lowercase_usernames. По умолчанию для этой опции выбрано значение false.

1. Отредактируйте файл docker-compose.yml:

   version: "3.6"
   services:
       appseccode:
           image: 'appseccode/appseccode:latest'
           restart: always
           hostname: 'yoursite.ru'
           environment:
               GITLAB_OMNIBUS_CONFIG: |
                   gitlab_rails['ldap_servers'] = {
                       'main' => {
                           'lowercase_usernames' => true
                       }
                   }
   

2. Сохраните файл и перезапустите Систему:

   docker compose up -d
   

Использование шифрования учетных данных

Вместо хранения учетных данных для интеграции с LDAP в открытом виде, можно использовать зашифрованный файл.

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

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

Поддерживаются следующие элементы конфигурации для зашифрованного файла:

• bind_dn;
• password.

1. Если изначально конфигурация LDAP в файле docker-compose.yml выглядит следующим образом:

   version: "3.6"
   services:
       appseccode:
           image: 'appseccode/appseccode:latest'
           restart: always
           hostname: 'yoursite.ru'
           environment:
               GITLAB_OMNIBUS_CONFIG: |
                   gitlab_rails['ldap_servers'] = {
                       'main' => {
                           'bind_dn' => 'admin',
                           'password' => '123'
                       }
                   }
   

2. Перейдите в контейнер и отредактируйте секреты шифрования:

   docker exec -t <container_name> bash
   gitlab-rake gitlab:ldap:secret:edit EDITOR=vim
   

3. Введите защифрованное содержимое секретов LDAP:

   main:
       bind_dn: admin
       password: '123'
   

4. Отредактируйте docker-compose.yml и удалите настройки для bind_dn и password.

5. Сохраните файл и перезапустите Систему:

   docker compose up -d
   

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

Удаление пользователей с LDAP-сервера незамедлительно блокирует его авторизацию в Системе.

Однако пользователи смогут продолжать использовать Систему через SSH, до следующей проверки кэша LDAP.

Чтобы удалить аккаунт незамедлительно, можно заблокировать пользователя вручную.

Обновление адресов электронной почты

Адреса электронной почты на LDAP-сервере считаются источником истины при авторизации.

Обновление адресов электронной почты пользователей должно производиться на LDAP-сервере, который управляет пользователем. Адрес электронной почты для Системы обновляется либо:

• При следующем входе пользователя в систему.
• При выполнении следующей синхронизации пользователя.

Обновленный (предыдущий) адрес электронной почты пользователя становится вторичным для сохранения истории коммитов этого пользователя.