Интеграция с 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:

   Настройка 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 verified»:

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

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 ведет к деградации функциональности системы, так как теперь эта проверка ложится на пользователя Оркестратора.