OIDC

Единый вход (SSO) пользователей в VK Registry обеспечивается путем подключения к OIDC-провайдеру.

После прохождения аутентификации пользователя в OIDC-провайдере VK Registry получает ID-токен пользователя, состоящий из набора пар «ключ-значение» (утверждений, claim) с атрибутами пользователя.

Используя утверждения из ID-токена, VK Registry создает учетные записи пользователей, актуализирует их и автоматически назначает им роли.

• Должен быть доступ к OIDC-провайдеру, поддерживающему спецификацию OpenID Connect. Например, Keycloak.
• Экземпляр VK Registry должен быть доступен по протоколу HTTPS с использованием действительного доверенного сертификата.

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

Чтобы настроить OIDC-провайдер:

1. Создайте клиент для интеграции с VK Registry. Он может называться application, client или relying party в зависимости от используемого провайдера.

   Задайте параметры клиента:

   • Client ID — идентификатор клиента.
   • Client Secret — секрет для защиты клиента.
   • Redirect URI или Callback URL — <URL-АДРЕС_REGISTRY>/service/rest/v2/security/oidc/callback.
   • Grant types — authorization code или implicit.
   • Scope — openid profile email groups.

2. Настройте OIDC-провайдер так, чтобы ID-токен включал данные пользователя, соответствующие profile из заданного Scope.

   Пример ID-токена:

    
   {  "sub": "i.ivanov@vk.team",  "email": "i.ivanov@vk.team",  "username": "i.ivanov",  "name": "Иван Иванов",  "given_name": "Иван",  "family_name": "Иванов",  "is_active": true,  "scope": "openid",  "exp": 1776115971,  "auth_time": 1776072588,  "jti": "d2b1cf2c-3b34-40cd-9654-0adfaab5ad16"}

3. Чтобы подготовиться к сопоставлению ролей в VK Registry, настройте OIDC-провайдер так, чтобы в ID-токене было утверждение со списком ролей пользователя.

   Пример такой настройки — в официальной документации Keycloak.

   Пример ID-токена с указанием списка ролей в утверждении groups:

    
   {  "sub": "i.ivanov@vk.team",  "email": "i.ivanov@vk.team",  "username": "i.ivanov",  "name": "Иван Иванов",  "given_name": "Иван",  "family_name": "Иванов",  "is_active": true,  "scope": "openid",  "groups": [    "unit21690",    "SysAccounts"  ],  "exp": 1776115971,  "auth_time": 1776072588,  "jti": "d2b1cf2c-3b34-40cd-9654-0adfaab5ad16"}

1. Авторизуйтесь в VK Registry с помощью учетной записи администратора.

2. Перейдите в раздел Безопасность → Настройки OIDC.

3. Задайте параметры сопоставления ролей:

   • Сопоставление ролей — опция, которая определяет, нужно ли VK Registry обрабатывать ID-токены пользователей для автоматического назначения ролей.
   • Группы пользователя — утверждение из ID-токена, которое содержит список ролей пользователя в OIDC-провайдере.

   Подробнее про механизм сопоставления ролей — в разделе Настройка сопоставления ролей.

4. Задайте параметры конфигурации клиента в OIDC-провайдере:

   • ID клиента — идентификатор клиента из настроек в OIDC-провайдере (Client ID).
   • Секрет клиента — секрет клиента из настроек в OIDC-провайдере (Client Secret).
   • URL издателя — URL-адрес OIDC-провайдера. Указан в конфигурации клиента в OIDC-провайдере (Issuer URL).

5. Задайте URL-адреса для работы с OIDC-провайдером:

   • Автоматически определять URL из метаданных издателя — опция, которая определяет, нужно ли автоматически заполнять параметры URL авторизации, URL токена, URL JWKS и URL выхода с помощью механизма OIDC Discovery.
   • (Опционально) URL авторизации — URL-адрес, по которому инициируется вход в систему. Указан в конфигурации клиента в OIDC-провайдере (Authorization Endpoint).
   • (Опционально) URL токена — URL-адрес для получения ID-токенов пользователей. Указан в конфигурации клиента в OIDC-провайдере (Token Endpoint).
   • (Опционально) URL JWKS — URL-адрес для получения публичных ключей, используемых при проверке подписи ID-токена OIDC-провайдером. Указан в конфигурации клиента в OIDC-провайдере (JWKS URL).

6. (Опционально) Задайте параметры завершения сессии пользователей:

   • Завершать сессию при выходе — опция, которая определяет, нужно ли завершать сессию пользователей в OIDC-провайдере при выходе из VK Registry.
   • URL выхода — URL-адрес для отправки запроса на завершение сессии. Указан в конфигурации клиента в OIDC-провайдере (URL Back-channel logout).

7. Задайте в поле Алгоритм подписи токена алгоритм, который OIDC-провайдер использует для подписи ID-токена. Это нужно для защиты от подмены алгоритма подписи.

   Пример: RS256.

8. Задайте утверждения для определения атрибутов пользователей:

   • Идентификатор пользователя — утверждение из ID-токена, которое содержит идентификатор пользователя в OIDC-провайдере. Если заданное утверждение не удастся определить, будет использовано утверждение sub.
   • Имя — утверждение из ID-токена, которое содержит имя пользователя в OIDC-провайдере.
   • Фамилия — утверждение из ID-токена, которое содержит фамилию пользователя в OIDC-провайдере.
   • Email — утверждение из ID-токена, которое содержит почту пользователя в OIDC-провайдере.

9. Нажмите кнопку Сохранить.

10. Добавьте область безопасности OIDC с помощью API:

    1. Перейдите в раздел Система → API.
    2. Перейдите в раздел Области безопасности V2 → Получить упорядоченный список активных областей безопасности, чтобы найти запрос GET /v2/security/realms/active.
    3. Нажмите кнопки Test Request → Send, чтобы получить список областей безопасности.
    4. Скопируйте тело ответа.
    5. Перейдите в раздел Области безопасности V2 → Изменить порядок использования активных областей безопасности, чтобы найти запрос PUT /v2/security/realms/active.
    6. Нажмите кнопку Test Request.
    7. Укажите в теле запроса скопированный список областей безопасности и добавьте к нему "OidcRealm".
    8. Нажмите кнопку Send.

Проверка выполняется по значению, указанному в поле URL издателя.

Чтобы проверить доступность OIDC-провайдера:

1. Авторизуйтесь в VK Registry с помощью учетной записи администратора.
2. Перейдите в раздел Безопасность → Настройки OIDC.
3. Нажмите кнопку Проверить OIDC Discovery.

Механизм сопоставления ролей автоматически назначает пользователю роли VK Registry на основе утверждений из его ID-токена.

Особенности сопоставления ролей:

• Пользователь получает роль, если утверждение из его ID-токена совпадает с идентификатором роли в VK Registry.

  Пример: если в ID-токене пользователя есть утверждение "groups": ["unit21690","SysAccounts"],, в VK Registry ему будут назначены роли с идентификаторами unit21690 и SysAccounts.

• Сопоставление работает для всех ролей VK Registry, независимо от того, созданы они до или после включения этого механизма.

• Роли, назначенные через сопоставление, не отображаются в списке ролей пользователя в разделе Безопасность → Пользователи. Эти роли динамические, они действуют только в рамках пользовательской сессии.

• Роли, назначенные вручную в разделе Безопасность → Пользователи, отображаются и действуют постоянно, независимо от того, включено ли сопоставление ролей.

Чтобы настроить сопоставление ролей:

1. Создайте роль, указав в параметре ID идентификатор роли в OIDC-провайдере.

   Подробнее — в разделе Создание роли.

2. Повторите создание роли для всех нужных ролей из OIDC-провайдера.

3. Перейдите в раздел Безопасность → Настройки OIDC.

4. Убедитесь, что включена опция Сопоставление ролей и утверждение в поле Группы пользователя указано корректно.

1. Перейдите в VK Registry и выберите Войти через OIDC.
2. Авторизуйтесь с помощью SSO.
3. Убедитесь, что открылся интерфейс VK Registry.

Если нужно отключить автоматическое назначение ролей для пользователей OIDC:

1. Авторизуйтесь в VK Registry с помощью учетной записи администратора.
2. Перейдите в раздел Безопасность → Настройки OIDC.
3. Отключите Сопоставление ролей.

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

1. Авторизуйтесь в VK Registry с помощью учетной записи администратора.
2. Перейдите в раздел Безопасность → Настройки OIDC.
3. Нажмите кнопку Удалить.