Модули безопасности#

Модуль безопасности (Security Provider) — это именованный объект каталога, хранящий конфигурацию внешней системы аутентификации. Каталог поддерживает подключение нескольких модулей безопасности различных типов. После создания модуля его можно назначить пользователям каталога: при входе в систему их пароль будет проверяться во внешней системе.

Текущая версия поддерживает следующие типы модулей безопасности:

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

  • ldap — аутентификация через внешний LDAP-сервер. См. Модуль безопасности LDAP.

  • oidc — аутентификация через внешний сервер авторизации по протоколу OAuth 2.0 с опциональной поддержкой OpenID Connect. См. Модуль безопасности OIDC.

Назначение модуля безопасности пользователю#

За выбор способа аутентификации пользователя отвечает параметр identified-with. Он хранит имя модуля безопасности, которому будет делегирована проверка пароля при входе в систему.

По умолчанию все новые пользователи создаются с identified-with, ссылающимся на встроенный модуль local, и аутентифицируются по паролю каталога.

Изменить модуль безопасности пользователя можно двумя способами:

  • Через веб-интерфейс: на экране редактирования пользователя в поле Способ аутентификации выберите нужный модуль безопасности из выпадающего списка.

  • Через CLI с помощью параметра --new-identified-with команды principal update:

    # Перевести пользователя на аутентификацию через LDAP-провайдер
catalog principal update --principal-name alice --new-identified-with ldap1

# Вернуть пользователя на локальную аутентификацию
catalog principal update --principal-name alice --new-identified-with local

Управление через интерфейс пользователя#

Модули безопасности отображаются и редактируются в разделе Модули безопасности пользовательского интерфейса. Здесь можно создать новый модуль, выбрав его тип и заполнив параметры конфигурации, изменить существующий, а также проверить корректность конфигурации модуля (например, доступность сервера аутентификации).

Управление через CLI#

Для управления модулями безопасности из командной строки используйте группу команд security-provider:

Модуль безопасности LDAP#

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

Описание workflow настройки и привязки пользователей приведено в разделе Аутентификация через LDAP.

Режимы поиска пользователя#

Модуль безопасности поддерживает два взаимоисключающих режима определения LDAP Distinguished Name (DN) пользователя.

Режим шаблона DN (user-dn-pattern) Используется, когда имя пользователя в каталоге можно напрямую преобразовать в DN по фиксированному шаблону. Шаблон задаётся через параметр user-dn-pattern и должен содержать заполнитель ${USER}, который при аутентификации заменяется именем пользователя каталога. Можно задать несколько шаблонов, разделив их двоеточием; модуль безопасности последовательно перебирает их до первого совпадения.

Пример: cn=${USER},ou=users,dc=example,dc=com

Режим поиска (user-search-base + user-search-filter) Используется, когда DN пользователя нельзя вычислить по простому шаблону. Модуль безопасности сначала выполняет поиск от имени сервисной учётной записи (bind-user-dn / bind-password), находит DN пользователя, а затем проверяет пароль, выполняя bind от имени найденного пользователя.

Пример фильтра: (&(objectClass=inetOrgPerson)(uid=${USER}))

Примечание

В обоих режимах параметры bind-user-dn и bind-password обязательны, поскольку модуль безопасности использует сервисную учётную запись для проверки существования пользователя в LDAP.

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

Параметр

Обязательный

По умолчанию

Описание

url

Да

—

URL-адрес LDAP-сервера в формате ldap[s]://host[:port]. Пример: ldaps://ldap.example.com:636

bind-user-dn

Да

—

Distinguished Name сервисной учётной записи для подключения к LDAP. Пример: cn=admin,dc=example,dc=com

bind-password

Да

—

Пароль сервисной учётной записи

user-dn-pattern

Да (режим шаблона DN)

—

Шаблон DN пользователя, должен содержать ${USER}. Несколько шаблонов разделяются двоеточием. Пример: cn=${USER},ou=users,dc=example,dc=com

user-search-base

Да (режим поиска)

—

Базовый DN для поиска пользователя. Пример: ou=users,dc=example,dc=com

user-search-filter

Да (режим поиска)

—

Фильтр LDAP для поиска пользователя, должен содержать ${USER}. Пример: (&(objectClass=inetOrgPerson)(uid=${USER}))

allow-insecure

Нет

false

Разрешает подключение к LDAP-серверу без использования TLS (только для ldap://). Не рекомендуется в production

ssl-truststore-path

Нет

—

Путь к truststore в формате PEM или JKS относительно resource-dir каталога. Используется для проверки сертификата LDAP-сервера

ssl-truststore-password

Нет

—

Пароль для truststore

ssl-keystore-path

Нет

—

Путь к keystore в формате PEM или JKS относительно resource-dir каталога. Используется при взаимной TLS-аутентификации

ssl-keystore-password

Нет

—

Пароль для keystore

ignore-referrals

Нет

false

Игнорировать LDAP-перенаправления на другие серверы. Установите в true, если поиск должен выполняться только на одном LDAP-сервере

connect-timeout

Нет

отсутствует

Таймаут установления соединения с LDAP-сервером, в миллисекундах

read-timeout

Нет

отсутствует

Таймаут чтения данных из LDAP-сервера, в миллисекундах

cache-ttl

Нет

300000 (5 минут)

Время жизни кэша результатов аутентификации, в миллисекундах. Значение 0 отключает кэш

cache-max-size

Нет

1000

Максимальное количество записей в кэше. Значение 0 отключает кэш

Примечание

Параметры user-dn-pattern и user-search-base/user-search-filter являются взаимоисключающими: необходимо задать либо шаблон DN, либо параметры поиска, но не оба одновременно.

Модуль безопасности OIDC#

Модуль безопасности OIDC позволяет аутентифицировать пользователей каталога через внешний сервер авторизации по протоколу OAuth 2.0 с опциональной поддержкой OpenID Connect.

Модуль безопасности реализует Authorization Code Flow: при входе в каталог пользователь перенаправляется на страницу входа сервера авторизации, проходит аутентификацию, после чего сервер авторизации перенаправляет пользователя обратно в каталог с кодом авторизации. Каталог обменивает код на access token и создаёт сессию.

Описание workflow настройки и привязки пользователей приведено в разделе Аутентификация через OIDC.

Конфигурация сервера авторизации#

Для работы модуля безопасности необходимо создать клиентское приложение (client) на сервере авторизации и зарегистрировать следующие URI:

Callback URI (Redirect URI)

Адрес, на который сервер авторизации перенаправляет пользователя после успешной аутентификации:

https://<адрес_каталога>/external-oauth/callback

Данный адрес необходимо добавить в список допустимых redirect URI клиентского приложения (Valid Redirect URIs, Sign-in Redirect URIs, Callback URL — в зависимости от сервера авторизации).

Post Logout Redirect URI

Адрес, на который сервер авторизации перенаправляет пользователя после выхода из системы:

https://<адрес_каталога>/cedrus-catalog-ui/login

Данный адрес необходимо добавить в список допустимых post-logout redirect URI клиентского приложения (Valid Post Logout Redirect URIs, Sign-out Redirect URIs — в зависимости от сервера авторизации).

Примечание

Каталог требует использования HTTPS для callback URI. Убедитесь, что каталог доступен по HTTPS, или используйте reverse proxy с TLS-терминацией.

Режимы OAuth 2.0 и OpenID Connect#

Модуль безопасности поддерживает два режима работы:

Режим OAuth 2.0

Используется по умолчанию. Каталог запрашивает только access token у сервера авторизации. Для включения этого режима не добавляйте openid в параметр request-scopes.

Режим OpenID Connect

Для включения режима OpenID Connect добавьте openid в параметр request-scopes. В этом режиме каталог дополнительно получает и валидирует ID token, что обеспечивает более строгую проверку подлинности пользователя.

Управление сессией#

Длительность сессии каталога определяется следующим образом:

  • Если сервер авторизации выдаёт refresh token: сессия длится не более значения session-timeout и не более времени жизни refresh token. При активности пользователя после истечения access token каталог автоматически обновляет токены.

  • Если refresh token отсутствует: сессия завершается по истечении access token или значения session-timeout — в зависимости от того, что наступит раньше.

При выходе пользователя из каталога, если параметр logout-from-auth-server установлен в true (по умолчанию), каталог инициирует RP-Initiated Logout на сервере авторизации.

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

Параметр

Обязательный

По умолчанию

Описание

issuer-url

Да

—

Базовый URL сервера авторизации. Примеры: Keycloak: https://<host>/realms/<realm>, Okta: https://<domain>/oauth2/<serverId>. Сервер авторизации должен поддерживать OpenID Connect Discovery и предоставлять конфигурацию по адресу {issuer-url}/.well-known/openid-configuration

client-id

Да

—

Client ID, используемый каталогом при аутентификации на сервере авторизации

client-secret

Да

—

Секрет клиента, используемый каталогом при аутентификации на сервере авторизации

principal-claim

Да

—

Claim access token, используемый как имя principal в каталоге (например, sub, email или preferred_username). Значение этого claim должно совпадать с именем пользователя в каталоге

request-scopes

Нет

—

Список scope, разделённых запятыми, запрашиваемых во время authorization code flow. Добавьте openid, чтобы использовать OpenID Connect flow и получать ID token

verify-audiences

Нет

—

Список допустимых значений claim aud в access token, разделённых запятыми (как правило, совпадает с Client ID). Если не указан, проверка audience отключена

verify-scopes

Нет

—

Список scope, разделённых запятыми, которые должны присутствовать в claim scope access token. Если не указан, проверка scope отключена

pkce-method

Нет

—

Метод PKCE для authorization code flow, защищающий от перехвата кода авторизации. Поддерживаемое значение: S256. Если не указан, PKCE отключён. При включении убедитесь, что поддержка PKCE также включена в настройках клиентского приложения на сервере авторизации

logout-from-auth-server

Нет

true

Выполнять RP-Initiated Logout на сервере авторизации при выходе пользователя из каталога

max-clock-skew

Нет

60

Максимально допустимое расхождение времени в секундах между каталогом и сервером авторизации при проверке временных claims JWT

auth-flow-timeout

Нет

300

Максимальное время в секундах, в течение которого пользователь должен завершить authorization code flow

session-timeout

Нет

900

Длительность сессии каталога в секундах. См. раздел «Управление сессией» выше

create-users

Нет

false

Автоматически создавать пользователей каталога при успешной аутентификации с помощью access token сервера авторизации. См. раздел автоматическое создание пользователей

roles-claim-paths

Нет

—

Список путей к claims access token, содержащих имена ролей, разделённых запятыми. Пример: realm_access.roles,resource_access.<client_id>.roles. См. раздел извлечение ролей из токена

use-local-role-grants

Нет

true

Учитывать роли, выданные пользователю через API каталога, в дополнение к ролям, извлечённым из access token. См. раздел извлечение ролей из токена

ssl-truststore-path

Нет

—

Путь к truststore в формате PEM или JKS относительно resource-dir каталога. Используется для проверки сертификата сервера авторизации

ssl-truststore-password

Нет

—

Пароль для truststore

ssl-keystore-path

Нет

—

Путь к keystore в формате PEM или JKS относительно resource-dir каталога. Используется при взаимной TLS-аутентификации с сервером авторизации

ssl-keystore-password

Нет

—

Пароль для keystore

Извлечение ролей из access token#

Модуль безопасности OIDC может извлекать имена ролей из claims access token, выданного сервером авторизации. Извлечённые роли используются как эффективные роли пользователя при работе с каталогом.

Для включения данной возможности задайте с помощью параметра roles-claim-paths список путей к claims, содержащих имена ролей. Каждый путь — это последовательность имен claim, разделённых точками. Значением claim может быть строка или массив строк; значения других типов игнорируются.

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

roles-claim-paths=realm_access.roles,resource_access.cedrusdata-catalog.roles

Извлечённые из токена имена ролей сопоставляются с ролями каталога следующим образом:

  • Имя роли, которое не является корректным именем роли каталога, игнорируется.

  • Роль, отсутствующая в каталоге, игнорируется.

  • Для каждой найденной роли учитываются все роли, выданные ей рекурсивно.

  • Публичная роль учитывается всегда.

Параметр use-local-role-grants определяет, как извлечённые из токена роли сочетаются с ролями, выданными пользователю через API каталога (веб-интерфейс, CLI):

  • true (по умолчанию) — локально выданные роли объединяются с ролями из токена.

  • false — локально выданные роли игнорируются; эффективными являются только роли, извлечённые из токена, а также публичная роль. Если access token не содержит ни одной роли каталога, пользователю доступна только публичная роль.

Примечание

Роли, извлечённые из токена, не сохраняются в каталоге и не отображаются в веб-интерфейсе и CLI как выданные пользователю. Они вычисляются заново при каждой аутентификации на основе содержимого access token.

Автоматическое создание пользователей#

По умолчанию перед аутентификацией через OIDC для каждого пользователя необходимо вручную создать учётную запись в каталоге (см. Аутентификация через OIDC).

Если параметр create-users установлен в true, каталог автоматически создаёт учётную запись пользователю, который успешно прошёл аутентификацию с помощью access token сервера авторизации, но ещё не существует в каталоге. Автоматически созданный пользователь:

  • аутентифицируется через соответствующий модуль безопасности OIDC (параметр identified-with);

  • не имеет пароля для локальной аутентификации;

  • получает эффективные роли согласно разделу извлечение ролей из токена (если настроен параметр roles-claim-paths).

Пользователь, от имени которого создаются учётные записи, задаётся с помощью параметра sync-users-as модуля безопасности. Данный параметр влияет на проверку прав доступа: операция создания пользователя выполняется от имени указанного пользователя. Если параметр sync-users-as не задан, учётные записи создаются от имени владельца модуля безопасности.

Примечание

Автоматическое создание пользователей выполняется только при аутентификации с помощью access token сервера авторизации (в том числе при работе с каталогом из CedrusData через token propagation и при входе в веб-интерфейс каталога).

Передача OAuth-токенов из CedrusData (Token Propagation)#

При работе с CedrusData Catalog из CedrusData через нативный протокол (коннектор Iceberg с типом cedrusdata_catalog) можно включить передачу OAuth2 access token, полученного пользователем CedrusData при аутентификации, в каталог.

В этом режиме CedrusData не использует сконфигурированный токен доступа каталога, а передаёт OAuth2 access token, полученный пользователем при аутентификации в CedrusData. Каталог валидирует этот токен с помощью модуля безопасности OIDC и определяет principal из указанного claim.

Для включения данного режима добавьте в конфигурацию Iceberg каталога CedrusData:

iceberg.catalog.type=cedrusdata_catalog
iceberg.cedrusdata-catalog.oauth-token-propagation-enabled=true

Для работы token propagation необходимо:

  1. В CedrusData настроена аутентификация пользователей через OAuth2, и пользователи получают access token от того же сервера авторизации, что указан в модуле безопасности OIDC каталога.

  2. В каталоге создан модуль безопасности OIDC, и параметр principal-claim указывает на claim, значение которого совпадает с именем пользователя в каталоге.

  3. Для каждого пользователя создана учётная запись в каталоге с привязкой к модулю безопасности OIDC (параметр identified-with указывает на соответствующий модуль безопасности). Вместо ручного создания учётных записей можно включить автоматическое создание пользователей с помощью параметра create-users модуля безопасности (см. Автоматическое создание пользователей).

Примечание

Передаваемый access token имеет ограниченное время жизни, определяемое настройками сервера авторизации. Операции с каталогом, такие как чтение метаданных таблиц и фиксация (commit) изменений, выполняются в начале и в конце запроса; сам процесс обработки данных не требует обращений к каталогу. Для большинства запросов времени жизни access token достаточно. Однако если фаза планирования или фиксации результатов длительного запроса (например, INSERT в таблицу с большим объёмом данных) превысит время жизни access token, операция завершится с ошибкой аутентификации. В этом случае рекомендуется увеличить время жизни access token на сервере авторизации.