Интеграция с KeyCloak

В данном руководстве предполагается, что KeyCloak-сервер уже развернут и настроен.

Общие положения

Во флаговый энум типов авторизации (параметр Auth:Type конфигурационного файла WebApi) добавились значения KeyCloak1 = 8 (сокращенный флоу) и KeyCloak2 = 16 (полный флоу с PKCE). При наличии этого флага на форме авторизации отобразится кнопка «Войти с учетной записью KeyCloak». Использовать одновременно оба флага не рекомендуется.

1. Сначала потребуется создать Realm: для этого нужно войти в Administration Console на главной странице KeyCloak с правами администратора.

   Главная страница KeyCloak

   Форма авторизации в Administration Console

2. Нажимаем кнопку Create Realm и вводим параметры нового Realm:

   Кнопка Create Realm

   Форма создания Realm

3. После создания нового Realm система автоматически переключит на него:

   Новый Realm

   Этот параметр будет использоваться при настройке конфигурационного файла службы WebApi:

   Настройка Realm в конфигурационном файле службы WebApi

4. Далее создаем Client: переходим на форму Clients со списком клиентов и нажимаем кнопку Create Client:

   Форма Clients

5. В мастере создания Client на первом шаге задаем ClientID, Name и Description:

   Мастер создания Clients, шаг 1

   Параметр ClientID будет использоваться при настройке конфигурационного файла службы WebApi:

   Настройка ClientId в конфигурационном файле службы WebApi

6. В мастере создания Client на втором шаге включается Client authentication и Authorization, остальные по умолчанию:

   Мастер создания Clients, шаг 2 (включение Client authentication и Authorization)

7. На вкладке Credentials у созданного Client нужно скопировать значение параметра Client secret, зашифровать его утилитой шифрования паролей, и добавить в конфигурационный файл службы WebApi:

   Копирование Client secret

   Шифрование Client secret утилитой Primo.Orchestrator.PasswordEncryptor

   Настройка ClientSecret в конфигурационном файле службы WebApi

8. Для типа авторизации KeyCloak2 = 16 нужно в конфигурационном файле WebApi настроить (только IP и порт) RedirectUrl, и скопировать его в Valid redirect URIs для Client:

   ℹ️

   Не забудьте правильно указать порт, обычно 44392

   Настройка RedirectUrl в конфигурационном файле службы WebApi

   Valid redirect URIs для Client

9. Встроенной учетной записи, ассоциированной с Client – service-account-orch – надо добавить административные роли. Открыть вкладку «Users», выбрать пользователя service-account-orch, открыть вкладку «Role mapping» и установить фильтр Filter by clients и выбрать роли manage-users, manage-realm, realm-admin:

   Вкладка Users

   Вкладка Role mapping

   Выбор роли manage-realm

10. Далее нужно настроить роли пользователей, которые будут использованы для сопоставления с ролями Оркестратора. Переходим на вкладку Realm roles:

    Вкладка «Realm roles»

11. Добавляем роли с префиксом orch-, чтобы по том по нему производить поиск:

    Добавление роли

    Список ролей, отфильтрованный по префиксу orch-

12. Дальше создаем пользователей, которые будут авторизоваться в Оркестраторе. Переходим на вкладку Users:

    Вкладка Users

13. Создаем пользователя Оркестратора, сразу добавляем Email и включаем Email verified, добавляем First name и Last Name

    ℹ️

    Поля Email, First name и Last Name не обязательные, но без них далее не пройдет аутентификация

    Создание пользователя Оркестратора

14. Устанавливаем созданному пользователю пароль. Переходим на вкладку Credentials:

    Вкладка «Credentials»

    Назначаем пароль, сразу отмечаем его постоянным – отключаем Temporary:

    Назначение пароля пользователю

15. Ассоциируем пользователя с ранее созданными ролями для Оркестратора:

    Ассоциирование пользователя с ролями для Оркестратора

    Чтобы авторизация работала, необходимо чтобы эти роли средствами Оркестратора были связаны с ролями Оркестратора:

    Связь ролей KeyCloak с ролями Оркестратора

16. В конфигурационном файле службы WebApi прописываем URL-адрес порт KeyCloak-сервера:

    Настройка адреса KeyCloak-сервера в конфигурационном файле службы WebApi

    Если задан СonfigurationUrl, то AuthUrl, TokenUrl и LogoutUrl заполняются на основе ответа этого эндпоинта, и их можно оставить пустыми/удалить из конфигурационного файла службы WebApi.

Параметр KeycloakTokenRolesSource

Параметр KeycloakTokenRolesSource определяет источник, откуда в Keycloak-токене будут извлекаться роли:

KeycloakTokenRolesSource = 0 (Realm – KeyCloak[orch])

Пользователю назначаются роли из Realm:

Роли в Realm orch

Соответствующая настройка в конфигурационном файле:

Настройка в конфигурационном файле для KeycloakTokenRolesSource = 0

KeycloakTokenRolesSource = 1 (Client совпадает с KeyCloak[orch].ClientId)

Пользователю назначаются роли из Client:

Роли в Client orch

Соответствующая настройка в конфигурационном файле:

Настройка в конфигурационном файле для KeycloakTokenRolesSource = 1

KeycloakTokenRolesSource = 2 (Другой Client совпадает с KeyCloak[orch].RoleClientId)

Пользователю назначаются роли из другого Client:

Роли в Client orch2

Соответствующая настройка в конфигурационном файле:

Настройка в конфигурационном файле для KeycloakTokenRolesSource = 2

Пользователю могут одновременно быть назначены в Keycloak роли из всех трех источников ролей, но читаться из токена будут только роли для конкретного значения KeycloakTokenRolesSource:

Роли в Realm orch и Client orch и orch2

Обход запрета/отключения административных эндпоинтов

Эндпоинты RealmRolesUrl, ClientsUrl, ClientRolesUrl, UsersUrl, GroupsUrl являются административными:

1. RealmRolesUrl используется при KeycloakTokenRolesSource = 0 для настройки маппинга ролей Keycloak и ролей Оркестратора
2. ClientsUrl, ClientRolesUrl используются при KeycloakTokenRolesSource = 1 и при KeycloakTokenRolesSource = 2 для настройки маппинга ролей Keycloak и ролей Оркестратора
3. UsersUrl используется при DisableUserCheck = false для проверки наличия пользователя в Keycloak
4. GroupsUrl зарезервирован, в текущей версии Оркестратора не используется

В случае запрета/отключения административных эндпоинтов требуется установить параметры Roles и DisableUserCheck (по умолчанию выключены/закомментированы):

Параметры Roles и DisableUserCheck

Параметры Roles и DisableUserCheck применяются независимо от KeycloakTokenRolesSource:

• Roles – массив ролей из соответствующего KeycloakTokenRolesSource. Например, для KeycloakTokenRolesSource = 0 это должен быть массив ролей из Realm. Регистр имеет значение.
• DisableUserCheck = true – отключение проверки наличия пользователя в Keycloak. Отключение проверки наличия пользователя в Keycloak ведет к деградации функциональности системы, так как теперь эта проверка ложится на пользователя Оркестратора.