Обзор

Deckhouse Code выполняет вход пользователей через внешних провайдеров аутентификации (OmniAuth) и берёт членство в группах и права доступа из каталога LDAP. Поведение провайдеров, правила синхронизации и решения о предоставлении и отзыве доступа одинаковы для всех типов установки; различается место, где записываются параметры:

• пакет для ОС Linux — файл /etc/gitlab/gitlab.rb;
• Omnibus Docker — переменная GITLAB_OMNIBUS_CONFIG или файл /etc/gitlab/gitlab.rb на томе конфигурации;
• Helm-чарт — значения чарта;
• модуль Deckhouse Kubernetes Platform — ресурс CodeInstance.

Ключи и манифесты для каждого типа приведены на странице «Настройка».

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

Ограничения входа и аутентификация по паролю

Вход локальных учётных записей настраивается в разделе «Admin» → «Настройки» → «Основные» → «Ограничения входа». Флажок «Разрешить аутентификацию по паролю через веб-интерфейс» показывает, входит ли учётная запись с паролем в веб-интерфейс наряду с внешними провайдерами; в интерфейсе флажок доступен только для чтения.

Чтобы включить аутентификацию по паролю для веб-интерфейса, откройте Rails-консоль:

sudo gitlab-rails console

docker exec -it code gitlab-rails console

d8 k -n code exec -it deploy/code-toolbox -- gitlab-rails console -e production

d8 k -n d8-code exec -it -c toolbox deploy/toolbox -- gitlab-rails console -e production

Выполните в ней команду:

Gitlab::CurrentSettings.update!(password_authentication_enabled_for_web: true)

Аутентификация по паролю для Git через HTTPS и двухфакторная аутентификация для всего инстанса задаются в том же разделе административной панели и описаны на странице «Пользователи и доступ».

Конфигурация OmniAuth

Общие параметры OmniAuth действуют для всех провайдеров; OpenID Connect и SAML добавляют собственные параметры.

Поддерживаемые провайдеры

В параметре name записи провайдера указывается одно из следующих значений:

• openid_connect — OpenID Connect (описан ниже);
• saml — SAML (описан ниже);
• oauth2_generic — произвольный провайдер OAuth 2.0;
• jwt — аутентификация по JWT;
• github — GitHub;
• gitlab — GitLab.com;
• google_oauth2 — Google;
• azure_activedirectory_v2 — Microsoft Entra ID (Azure AD);
• atlassian_oauth2 — Atlassian;
• crowd — Atlassian Crowd;
• auth0 — Auth0;
• alicloud — AliCloud;
• salesforce — Salesforce;
• shibboleth — Shibboleth.

Вход через LDAP настраивается отдельно, в секции LDAP-серверов (подробнее — в разделе «Синхронизация с LDAP»).

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

Следующие параметры действуют для всех провайдеров:

• enabled — разрешает вход через внешних провайдеров. По умолчанию — true.
• providers — список провайдеров, через которых разрешён вход. По умолчанию — [].
• allow_single_sign_on — список провайдеров, для которых при первом входе автоматически создаётся учётная запись (например, ['openid_connect']). Также принимает значения true (все провайдеры) и false. Если автоматическое создание отключено, пользователь должен сначала получить учётную запись в Deckhouse Code, а затем связать её с провайдером. По умолчанию — false.
• block_auto_created_users — если true, автоматически созданные учётные записи блокируются до одобрения администратором. По умолчанию — true.
• auto_link_ldap_user — связывает учётную запись с учётной записью LDAP при первом входе (подробнее — в разделе «Связывание учётных записей OIDC с LDAP»). По умолчанию — false.
• auto_link_user — связывает вход через провайдера с существующей учётной записью Deckhouse Code по адресу электронной почты. Принимает список провайдеров или значения true и false. По умолчанию — false.
• auto_sign_in_with_provider — имя провайдера, на страницу входа которого пользователь перенаправляется автоматически, минуя страницу входа Deckhouse Code. По умолчанию — false.
• external_providers — список провайдеров, учётные записи которых создаются как внешние. По умолчанию — [].
• allow_bypass_two_factor — список провайдеров, вход через которых не требует двухфакторной аутентификации. Также принимает значения true и false. По умолчанию — false.
• sync_profile_from_provider — список провайдеров, из данных которых обновляется профиль пользователя при каждом входе. Также принимает значения true и false. По умолчанию — false.
• sync_profile_attributes — список атрибутов профиля, которые обновляются при синхронизации: name, email, location. Синхронизируемые атрибуты становятся доступными только для чтения. По умолчанию — ['email'].

OpenID Connect (OIDC)

Провайдеры перечисляются в параметре providers. Для провайдера OIDC доступны следующие параметры:

• name — тип провайдера. Для OIDC — всегда 'openid_connect'.
• label — подпись кнопки входа. По умолчанию — 'Openid Connect'.
• icon — адрес изображения, которое будет показано на кнопке входа.
• args — параметры подключения к провайдеру:
  • name — имя стратегии OmniAuth, совпадает со значением параметра name провайдера;
  • scope — список запрашиваемых областей доступа, например ['openid', 'profile', 'email'];
  • response_type — тип ответа OAuth 2.0. Для потока Authorization Code — 'code';
  • issuer — адрес OIDC-провайдера;
  • discovery — если true, настройки провайдера запрашиваются автоматически по адресу <issuer>/.well-known/openid-configuration;
  • client_auth_method — способ аутентификации клиента на token endpoint: 'basic' или 'query';
  • uid_field — поле из данных пользователя, которое используется как uid учётной записи (например, preferred_username). Если параметр не задан или поле отсутствует, используется поле sub;
  • send_scope_to_token_endpoint — передавать ли параметр scope в запросах к token endpoint. Задайте false, если провайдер не принимает этот параметр. По умолчанию — true;
  • pkce — включает Proof Key for Code Exchange (PKCE);
  • client_options:
    • identifier — идентификатор клиента, зарегистрированного у провайдера;
    • secret — секрет клиента;
    • redirect_uri — адрес установки Deckhouse Code с путём /users/auth/openid_connect/callback. Тот же адрес должен быть указан в настройках клиента на стороне провайдера.

Дополнительно Deckhouse Code поддерживает следующие параметры. Они указываются на верхнем уровне записи провайдера, рядом с параметром name:

• allowed_groups — список групп, пользователям которых разрешён вход. Пользователи вне этих групп будут заблокированы. По умолчанию — null (разрешены все группы).

• admin_groups — список групп, пользователи которых получают административные права. По умолчанию — null (права администратора не выдаются ни одной группе).

• auditor_groups — список групп, пользователи которых получают роль аудитора: доступ только на чтение ко всем группам и проектам, без доступа к административному разделу. По умолчанию — null (роль аудитора не выдаётся ни одной группе).

• groups_attribute — имя атрибута, из которого извлекаются группы пользователя. По умолчанию — 'groups'.

Примеры записи провайдера для каждого типа установки: «Провайдер OpenID Connect» и «Провайдер SAML».

SAML

Для провайдеров SAML доступны аналогичные параметры:

• allowed_groups — список групп с разрешённым входом. По умолчанию — null (разрешены все группы).

• admin_groups — группы с административными правами. По умолчанию — null (права администратора не выдаются ни одной группе).

• auditor_groups — группы, пользователи которых получают роль аудитора: доступ только на чтение ко всем группам и проектам. По умолчанию — null (роль аудитора не выдаётся ни одной группе).

• groups_attribute — имя атрибута, содержащего группы. По умолчанию — 'Groups'.

Синхронизация с LDAP

Deckhouse Code поддерживает синхронизацию пользователей, групп и прав доступа с LDAP-сервером. Синхронизация выполняется автоматически раз в час либо с периодичностью, заданной расписанием задачи ldap_sync_worker.

Примеры записи LDAP-сервера для каждого типа установки: «LDAP-серверы» и «Расписание синхронизации».

Ограничения на стороне LDAP-сервера

Во время синхронизации выполняются LDAP-запросы ко всем пользователям и группам, указанным в конфигурации. При необходимости используется постраничная загрузка (pagination). Если на стороне LDAP установлены ограничения на число возвращаемых объектов, это может привести к ошибкам синхронизации или удалению прав доступа у пользователей.

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

В секции LDAP можно описать несколько серверов. Ключ записи — имя сервера; из него формируется имя провайдера ldap<ключ> в нижнем регистре. Например, ключу main соответствует провайдер ldapmain. Это имя хранится в идентификаторе учётной записи и попадает в поле server записей о синхронизации в логах.

У каждого сервера собственные параметры подключения. Параметры синхронизации — секция group_sync со всем её содержимым, включая role_mapping, — учитываются только у сервера под ключом main; у остальных серверов эта секция игнорируется (раздел «Область синхронизации»).

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

Серверы задействуются по-разному в зависимости от сценария:

Область синхронизации

Синхронизация пользователей, групп и прав доступа охватывает только один сервер — тот, чьё имя провайдера равно ldapmain, то есть сервер под ключом main. Остальные серверы остаются источником входа, но не источником групп и прав. Ограничение действует одинаково и в задании синхронизации по расписанию, и при синхронизации, которая выполняется при входе пользователя.

Следствия:

• пользователь, заведённый только в неглавном каталоге, входит в Deckhouse Code, но групп и прав из LDAP не получает — их назначают вручную;
• у пользователя с двумя идентификаторами (одинаковый основной адрес электронной почты в обоих каталогах) группы и права всегда приходят из ldapmain, независимо от того, через какой сервер он вошёл;
• секция group_sync неглавных серверов не читается, поэтому ошибка в их параметре group_sync.filter не мешает запуску приложения. Ошибка в фильтре сервера main по-прежнему обнаруживается сразу при старте и не даёт приложению подняться.

Дойдя до неглавного сервера, синхронизация пропускает его и пишет об этом одну запись уровня INFO с именем пропущенного сервера в поле server:

Server is not synchronized: users, groups and permissions come from 'ldapmain' only

Идентификация пользователей при нескольких серверах

Пользователь ищется сначала по идентификатору учётной записи, затем по основному адресу электронной почты:

• если основной адрес в двух каталогах совпадает, при входе через второй сервер к существующей учётной записи добавляется второй LDAP-идентификатор; новая учётная запись не создаётся;
• если адреса разные, будут созданы две разные учётные записи.

Список идентификаторов учётной записи доступен в административном разделе на странице /admin/users/<username>/identities.

Решение о доступе при нескольких идентификаторах

Deckhouse Code периодически, не чаще одного раза в час, перепроверяет доступ пользователя LDAP: обращается в каталог и блокирует учётную запись, если запись в каталоге не найдена, либо разблокирует, если она нашлась снова. Если у учётной записи несколько LDAP-идентификаторов, каталог для проверки выбирается так:

• есть идентификатор ldapmain — решает только он, остальные каталоги не опрашиваются. Пользователь есть в ldapmain и не отключён там — доступ есть; его там нет или он отключён — доступа нет, что бы ни происходило в остальных каталогах;
• идентификатора ldapmain нет, то есть пользователь заведён только в неглавных каталогах, — он проверяется по своим идентификаторам, и доступ сохраняется, пока запись найдена хотя бы в одном из соответствующих каталогов.

«Запись найдена» означает, что она существует в каталоге и не отключена средствами Active Directory. Второе проверяется только для каталогов, сконфигурированных как AD.

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

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

Группы и права доступа

LDAP-группы сопоставляются с группами GitLab. При этом можно назначать роли пользователям на основе имени группы.

Обязательные параметры:

• group_sync.base — DN, с которого начинается поиск LDAP-групп.

Опциональные параметры:

• group_sync.create_groups — если true, группы будут создаваться в Deckhouse Code.
• group_sync.filter — LDAP-фильтр для поиска групп.
• group_sync.scope — область поиска групп (0 — Base, 1 — SingleLevel, 2 — WholeSubtree).
• group_sync.prefix — определяет, из какого атрибута брать имя родительской группы. Если атрибут отсутствует — используется значение по умолчанию.
• group_sync.top_level_group — имя группы верхнего уровня, в которую будут добавлены все синхронизированные группы.
• group_sync.name_mask — регулярное выражение для извлечения имени группы из атрибута CN (Common Name).
• group_sync.owner — имя пользователя, который будет добавлен как владелец группы (по умолчанию — root).

Секция role_mapping

Назначает права пользователям на основе имени группы (cn):

• role_mapping.by_name — регулярное выражение; если имя группы совпадает, пользователю назначается соответствующая роль.
• role_mapping.gitlab_role — имя роли, доступной на инстансе.

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

В настоящее время справочник содержит семь имён:

Имя роли записывается так, как указано в колонке gitlab_role: в нижнем регистре, слова разделяются подчёркиванием. Регистр и пробелы не нормализуются, поэтому, например, Security Manager считается нераспознанным именем.

Роль security_manager присутствует в справочнике, только если она включена на инстансе (переменная окружения GITLAB_SECURITY_MANAGER_ROLE, по умолчанию включена). Если роль отключена, её имя считается нераспознанным.

Если под имя LDAP-группы подошло несколько правил, назначается численно наибольший уровень доступа. Например, если группа подошла и под правило с ролью security_manager (уровень 25), и под правило с ролью developer (уровень 30), её участники получат роль Developer.

Проверка имён ролей

Имена ролей проверяются один раз, в начале назначения ролей пользователям по их LDAP-группам (далее — назначение членств), включая правила, под которые при текущей синхронизации не подошла ни одна LDAP-группа. Это позволяет обнаруживать и скрытые опечатки, которые проявились бы только при появлении подходящей группы.

Проверка не прерывает назначение членств:

• LDAP-группы, все подошедшие правила которых распознаны, обрабатываются полностью и получают членства;
• нераспознанное правило не участвует в вычислении уровня доступа;
• если под LDAP-группу подошли только нераспознанные правила, уровень доступа для неё не определяется, и группа целиком пропускается при текущей синхронизации: её текущие участники не пересчитываются и не удаляются.

При этом синхронизация завершается ошибкой — уже после того, как группы, пользователи и корректные членства записаны. Следствия:

• синхронизация учитывается как аварийно завершённая на странице метрик задачи синхронизации, а отметка об успешной синхронизации не обновляется (раздел «Ручной запуск синхронизации»);

• в логи попадает запись уровня ERROR, в которой перечислены и нераспознанные имена, и полный список допустимых:

  Unknown gitlab_role in group_sync.role_mapping: 'security_manger'. Available roles: guest, planner, reporter, security_manager, developer, maintainer, owner
  

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

Определение членов группы

Deckhouse Code поддерживает следующие атрибуты для определения членов группы (все значения — массив DN):

• member;
• uniquemember;
• memberof;
• memberuid;
• submember.

Синхронизация пользователей

Во время синхронизации обновляются имена и email-адреса пользователей, а также статус блокировки.

Опциональные параметры:

• sync_name — если true, имя пользователя будет обновлено по данным LDAP.

Блокировка пользователей по данным LDAP

Если пользователь удалён из LDAP, очередная плановая синхронизация заблокирует его учётную запись. Если пользователя вернули в LDAP, следующая синхронизация разблокирует учётную запись автоматически.

Блокировка выполняется всегда и не требует дополнительных настроек: источником истины для статуса учётной записи остаётся LDAP. Вход заблокированного пользователя через OIDC-провайдера завершится отказом, даже если в самом провайдере пользователь активен.

Если в вашем каталоге пользователей не удаляют, а блокируют через атрибут, исключите заблокированных пользователей из выдачи LDAP с помощью параметра user_filter сервера. Укажите один фильтр, соответствующий вашему каталогу:

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

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

Как ищется учётная запись LDAP

При первом входе через OIDC Deckhouse Code ищет пользователя в LDAP. Для поиска используются два значения из данных OIDC-провайдера:

• uid — значение поля, указанного в параметре uid_field провайдера (например, preferred_username);
• email — адрес электронной почты пользователя.

Настроенные LDAP-серверы опрашиваются по очереди. На каждом сервере выполняется до четырёх попыток поиска, до первого совпадения:

Если пользователь найден, к его учётной записи добавляется LDAP-идентификатор с найденным DN. Если ни одна попытка не дала результата, учётная запись создаётся без привязки к LDAP.

Таким образом, связывание сработает, только если uid или email из OIDC-провайдера совпадает со значением соответствующего атрибута в LDAP.

Первый и последующие входы

При первом успешном входе учётная запись связывается с LDAP. При последующих входах:

• LDAP не опрашивается — используется ранее установленная связь;
• доступ и административные права переоцениваются по группам из данных OIDC-провайдера (параметры allowed_groups и admin_groups). Если пользователя убрали из разрешённой группы, учётная запись будет заблокирована;
• членства в группах и проектах, а также роли в них при входе через OIDC не меняются — их обновляет фоновая синхронизация с LDAP по расписанию.

Поэтому сразу после первого входа пользователь может войти, но членств в группах и проектах у него ещё нет: они появятся после ближайшей синхронизации. Чтобы не ждать её, запустите синхронизацию вручную (подробнее — в разделе «Ручной запуск синхронизации»).

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

Чтобы пользователи, найденные в LDAP, могли входить сразу, а остальные отправлялись на одобрение администратору, сочетайте два параметра:

• block_auto_created_users на уровне OmniAuth со значением true — пользователь, не найденный в LDAP, получает учётную запись, заблокированную до одобрения администратором;
• block_auto_created_users у LDAP-сервера main со значением false — пользователь, найденный в LDAP, входит сразу.

Особенности связывания

• Если пользователя блокируют переименованием cn в каталоге, при первом входе он всё равно может быть найден по email и связан с учётной записью LDAP. Для блокировки используйте удаление пользователя из каталога или параметр user_filter (подробнее — в разделе «Блокировка пользователей по данным LDAP»).
• Если пользователь не был связан с LDAP и его заблокировала задача Ldap::BlockNonLdapUsersWorker, автоматическая разблокировка не сработает. Такого пользователя нужно разблокировать вручную и связать с учётной записью LDAP.

Устранение проблем с синхронизацией

Если предыдущее задание синхронизации завершилось некорректно, Redis может сохранить блокировку на его выполнение (по умолчанию параметр concurrency = 1). Это помешает запуску нового задания.

Чтобы снять блокировку:

1. Подключитесь к Redis, используя базы, указанные в config/redis.shared_state.yml и config/redis.queues.yml.

2. Удалите ключ sidekiq:concurrency_limit:throttled_jobs:{ldap/sync_worker} следующими командами:

   keys *ldap*
   del "sidekiq:concurrency_limit:throttled_jobs:{ldap/sync_worker}"
   

Ручной запуск синхронизации

Чтобы синхронизировать группы сразу после их изменения на стороне LDAP, выполните следующие шаги:

1. Зайдите на страницу worker’а синхронизации LDAP /admin/sidekiq/cron/namespaces/default/jobs/ldap_sync_worker.

2. В верхнем правом углу нажмите кнопку «Запустить» и подтвердите в диалоговом окне.

   

Чтобы посмотреть, как завершилась запущенная синхронизация, откройте страницу метрик задачи синхронизации LDAP: /admin/sidekiq/metrics?substr=SyncWorker&period=8h. На графике отображается статистика вызовов, в таблице ниже — количество успешно и аварийно завершённых вызовов синхронизации LDAP.

Чтобы посмотреть полные логи процесса синхронизации:

1. На странице worker’а /admin/sidekiq/cron/namespaces/default/jobs/ldap_sync_worker найдите таблицу событий запусков «История». Первая строка соответствует последнему запуску. Скопируйте значение в колонке JID (Job ID) — оно понадобится для поиска по логам.

   

2. Соберите записи логов Sidekiq для этого запуска, подставив скопированный JID:

   • Пакет для ОС Linux
   • Omnibus Docker
   • Helm-чарт
   • Модуль Deckhouse Kubernetes Platform

   sudo grep '<JID>' /var/log/gitlab/sidekiq/current

   docker exec code grep '<JID>' /var/log/gitlab/sidekiq/current

   d8 k -n code logs -l app.kubernetes.io/component=sidekiq | jq 'select(.jid=="<JID>")'

   d8 k -n d8-code -l app.kubernetes.io/component=sidekiq get pod -o NAME
   d8 k -n d8-code logs <POD_NAME> -c sidekiq | jq 'select(.jid=="<JID>")'

Особенности работы LDAP Sync

Алгоритм синхронизации

LDAP Sync использует плоский алгоритм синхронизации:

1. Получение групп. Выполняется LDAP-запрос, который получает все группы по параметрам base, filter и scope.
2. Извлечение участников. Для каждой найденной группы читаются атрибуты членства: member, uniquemember, memberof, memberuid, submember.
3. Сопоставление пользователей. Каждый DN из атрибутов членства сопоставляется со значением Identity.extern_uid в базе данных.
4. Игнорирование неизвестных DN. Если DN не соответствует известному пользователю, он пропускается. Например, это может быть DN вложенной группы.

Циклические зависимости между группами

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

Рекурсивный обход вложенности не выполняется, поэтому циклы не влияют на результат синхронизации.

Вложенные группы и транзитивность

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

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

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

Если требуется учитывать вложенные группы, это нужно реализовать на стороне LDAP-сервера. Например, можно заполнять атрибут submember полным списком транзитивных участников.

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

Создание локальной учётной записи при включённой синхронизации с LDAP

Локальные учётные записи можно создавать и использовать даже при включённой синхронизации с LDAP.

Такие пользователи входят через веб-интерфейс, пока включена аутентификация по паролю для веб-интерфейса (раздел «Ограничения входа и аутентификация по паролю»).