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

Deckhouse Code поддерживает настройку OmniAuth согласно официальной документации GitLab. При этом реализованы дополнительные возможности, описанные ниже.

OpenID Connect (OIDC)

Для интеграции с провайдерами OIDC доступны следующие параметры:

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

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

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

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

Настройка выполняется в секции spec.appConfig.omniauth.:

providers:
  - name: 'openid_connect'
    allowed_groups:
      - 'gitlab'
    admin_groups:
      - 'admin'
    groups_attribute: 'gitlab_group'

SAML

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

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

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

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

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

Настройка выполняется в секции spec.appConfig.omniauth.:

providers:
  - name: 'saml'
    allowed_groups:
      - 'gitlab'
    admin_groups:
      - 'admin'
    groups_attribute: 'gitlab_group'

Если пользователь входит в admin_groups, но не указан в allowed_groups, доступ будет запрещён. В этом случае административные права также не будут назначены.

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

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

Вы можете настроить периодичность синхронизации через параметр cronJobs в секции spec.appConfig.:

cron_jobs:
  ldap_sync_worker:
    cron: "0 * * * *"

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

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

Пример конфигурации LDAP-провайдера

Конфигурация размещается в spec.appConfig.ldap.:

main:
  label: ldap
  host: 127.0.0.1
  port: 3389
  bind_dn: 'uid=viewer,ou=People,dc=example,dc=com'
  base: 'ou=People,dc=example,dc=com'
  uid: 'cn'
  password: 'viewer123'
  sync_name: true
  group_sync: {
    create_groups: true,
    base: 'ou=Groups,dc=example,dc=org',
    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' }
    ]
  }

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

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.
  • group_sync.owner — имя пользователя, который будет добавлен как владелец группы (по умолчанию — root).

Секция role_mapping

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

  • role_mapping.by_name — регулярное выражение; если имя группы совпадает, пользователю назначается соответствующая роль.
  • role_mapping.gitlab_role — название роли в Deckhouse Code (например: guest, reporter, developer, maintainer, owner).

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

LDAP Sync не поддерживает транзитивность для вложенных групп. Подробная информация в разделе «Вложенные группы и транзитивность».

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

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

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

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

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

sync_name — если true, имя пользователя будет обновлено по данным 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 sync worker UI

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

Ldap sync worker metrics

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

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

    Ldap sync history table

  2. Подключитесь к кластеру и определите имя пода Sidekiq командой: kubectl -n d8-code -l app.kubernetes.io/component=sidekiq get pod -o NAME

  3. Выполните сбор логов, подставив скопированный JID и имя пода (POD_NAME): kubectl -n d8-code logs POD_NAME | 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 Sync обрабатывает только прямые значения атрибутов членства группы и не выполняет рекурсивный обход вложенных групп.

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

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

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

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

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

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

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