Аутентификация через OpenID Connect с Keycloak

Важно

Аутентификация через OpenID Connect (далее — OIDC) доступна только в серверной версии ТестОпс.

OIDC — это протокол аутентификации, основанный на OAuth 2.0. Если вы настроите OIDC-интеграцию с Keycloak для вашего инстанса ТестОпс, пользователи смогут использовать учетные записи Keycloak для входа в ТестОпс.

Примечание

Чтобы настроить аутентификацию через OIDC с Keycloak, вам необходимы:

права администратора инстанса Keycloak;
доступ к конфигурационным файлам ТестОпс.

Принцип работы аутентификации через OIDC с Keycloak

Пользователь открывает страницу входа в ТестОпс.
ТестОпс перенаправляет пользователя на страницу аутентификации Keycloak.
Пользователь вводит учетные данные на странице Keycloak.
После успешной аутентификации Keycloak возвращает токен доступа с информацией о пользователе.
ТестОпс аутентифицирует пользователя на основе данных из токена.

Настройка аутентификации через Keycloak

Чтобы настроить аутентификацию в ТестОпс через OIDC с Keycloak:

Создайте пространство в Keycloak (при необходимости).
Создайте OIDC-клиента для ТестОпс в Keycloak.
Получите OIDC-эндпоинты из настроек Keycloak.
Измените конфигурационные файлы ТестОпс.
Настройте маппинг ролей между Keycloak и ТестОпс (при необходимости).

1. Создайте пространство в Keycloak

Если вам нужно создать отдельное пространство (realm) в Keycloak для пользователей ТестОпс:

Перейдите в ваш инстанс Keycloak.
В сайдбаре слева перейдите в раздел Manage realms.
Нажмите Create realm.
В поле Realm name введите название нового пространства (например, testops-realm).
Нажмите Create.

2. Создайте OIDC-клиента для ТестОпс в Keycloak

В Keycloak переключитесь на пространство, которое предназначено для работы с ТестОпс (например, testops-realm).
В сайдбаре слева перейдите в раздел Clients.
Нажмите Create client.
Заполните поля:
- Client type — нажмите на выпадающий список и выберите OpenID Connect;
- Client ID — введите уникальный идентификатор OIDC-клиента (например, testops);
- Name — введите название OIDC-клиента (например, testops);
- Description — введите описание OIDC-клиента;
- Always display in UI — убедитесь, что переключатель выключен.
Нажмите Next.
Заполните поля:
- Client authentication — включите переключатель;
- Authentication flow — убедитесь, что напротив Standard flow стоит галочка.
Оставьте другие поля без изменений и нажмите Next.
В поле Valid redirect URIs введите URI перенаправления в зависимости от вашего типа развертывания ТестОпс:
- для Kubernetes — https://<домен_инстанса_ТестОпс>/login/oauth2/code/keycloak (например, https://testops.example.com/login/oauth2/code/keycloak);
- для Docker Compose или DEB/RPM-пакетов — https://<домен_инстанса_ТестОпс>/login/oauth2/code/openid (например, https://testops.example.com/login/oauth2/code/openid).
Оставьте другие поля без изменений и нажмите Save.
Перейдите на вкладку Credentials.
Напротив поля Client Secret нажмите иконку Copy to clipboard, чтобы скопировать секрет OIDC-клиента в буфер обмена.
Cохраните секрет в безопасном месте, он понадобится для настройки интеграции с Keycloak в конфигурационных файлах ТестОпс.

3. Получите OIDC-эндпоинты из настроек Keycloak

В Keycloak в сайдбаре слева перейдите в раздел Realm settings → вкладка General.
В поле Endpoints перейдите по ссылке OpenID Endpoint Configuration.
Откроется файл в формате JSON, который содержит все эндпоинты текущего пространства Keycloak.
Скопируйте и сохраните значения полей:
- authorization_endpoint,
- token_endpoint,
- jwks_uri,
- userinfo_endpoint.
Они понадобятся для настройки интеграции с Keycloak в конфигурационных файлах ТестОпс.

4. Измените конфигурационные файлы ТестОпс

Измените конфигурационные файлы ТестОпс в зависимости от вашего типа развертывания:

Измените параметры в файле values.yaml:

общие параметры:
- auth.primary — введите openid, чтобы установить OIDC в качестве основного метода аутентификации;
- auth.openid.defaultRole — введите глобальную роль ТестОпс по умолчанию, которая будет назначена новым пользователям из Keycloak. Рекомендуется указать ROLE_GUEST — глобальную роль «Гость», чтобы контролировать использование лицензионных мест.
  Примечание
  Если значение параметра auth.openid.defaultRole не указано, по умолчанию используется ROLE_GUEST.
подключение к Keycloak:
- auth.openid.enabled — введите true, чтобы включить OIDC-аутентификацию;
- auth.openid.clientName — введите название OIDC-клиента (значение поля Name из шага 2);
- auth.openid.clientId — введите уникальный идентификатор OIDC-клиента (значение поля Client ID из шага 2). Keycloak использует этот идентификатор для проверки запросов от ТестОпс;
- auth.openid.providerName — введите keycloak. Это значение отображается на кнопке входа в ТестОпс и используется в URI перенаправления;
- auth.openid.clientSecret — введите секрет OIDC-клиента, который вы сохранили на шаге 2. Keycloak использует этот секрет для аутентификации запросов от ТестОпс;
- auth.openid.redirectUri — введите https://<домен_инстанса_ТестОпс>/login/oauth2/code/keycloak. Keycloak перенаправляет пользователя на этот адрес после успешной аутентификации;
- auth.openid.scope — убедитесь, что указан список openid, email, profile. Он определяет, какие данные пользователя ТестОпс запрашивает у Keycloak;
- auth.openid.authorizationGrantType — убедитесь, что указано значение authorization_code;
- auth.openid.authorizationUri — введите значение поля authorization_endpoint, которое вы сохранили на шаге 3. ТестОпс перенаправляет пользователя на этот адрес для аутентификации;
- auth.openid.jwksSetUri — введите значение поля jwks_uri, которое вы сохранили на шаге 3. ТестОпс использует этот адрес для проверки подписи токенов;
- auth.openid.tokenUri — введите значение поля token_endpoint, которое вы сохранили на шаге 3. ТестОпс использует этот адрес для получения токена доступа;
- auth.openid.userinfoUri — введите значение поля userinfo_endpoint, которое вы сохранили на шаге 3. ТестОпс использует этот адрес для получения данных о пользователе;
- auth.openid.usernameAttribute — убедитесь, что указано значение preferred_username. Этот параметр из токена используется как имя пользователя в ТестОпс.

5. Настройте маппинг ролей между Keycloak и ТестОпс

При необходимости вы можете настроить маппинг ролей между Keycloak и ТестОпс, который укажет, какие глобальные роли ТестОпс должны получить группы пользователей из Keycloak.

Маппинг ролей позволяет контролировать использование мест в основной лицензии ТестОпс, предотвращать несанкционированный доступ к проектам ТестОпс и централизованно управлять правами пользователей из Keycloak.

5.1. Создайте роли и группы в Keycloak

Перейдите в ваш инстанс Keycloak.
В сайдбаре слева перейдите в раздел Realm roles.
Создайте две роли Keycloak для маппинга с глобальными ролями ТестОпс «Администратор» и «Пользователь». Чтобы создать каждую из этих ролей:
1. Нажмите Create role.
2. Заполните поля:
  - Role name — введите название роли (например, to_admins для глобальной роли «Администратор» и to_users для глобальной роли «Пользователь»);
  - Description — введите описание роли.
3. Нажмите Save.
В сайдбаре слева перейдите в раздел Groups.
Создайте две группы Keycloak для маппинга с глобальными ролями ТестОпс «Администратор» и «Пользователь». Чтобы создать каждую из этих групп:
1. Нажмите Create group.
2. Заполните поля:
  - Name — введите название группы (например, to_admins для глобальной роли «Администратор» и to_users для глобальной роли «Пользователь»);
  - Description — введите описание группы.
3. Нажмите Create.
В списке групп Keycloak откройте карточки групп, которые вы создали. В карточке каждой из этих групп:
1. Перейдите на вкладку Role mapping.
2. Нажмите Assign role → Realm roles.
3. Поставьте галочку напротив созданной роли, которую нужно назначить группе.
  Для примеров выше вам нужно:
  - назначить группе to_admins роль to_admins;
  - назначить группе to_users роль to_users.
Нажмите Assign.

5.2. Создайте client scope в Keycloak

Чтобы ТестОпс мог получать данные о группах пользователя из Keycloak, создайте набор конфигураций (client scope), содержащий маппер групп:

В Keycloak в сайдбаре слева перейдите в раздел Client scopes.
Нажмите Create client scope.
Заполните поля:
- Name — введите название набора конфигураций (например, openid);
- Description — введите описание набора конфигураций;
- Type — нажмите на выпадающий список и выберите Default;
- Protocol — нажмите на выпадающий список и выберите OpenID Connect;
- Include in token scope — включите переключатель.
Оставьте другие поля без изменений и нажмите Save.
Перейдите на вкладку Mappers.
Нажмите Add predefined mappers.
Поставьте галочку напротив groups.
Нажмите Add.

5.3. Назначьте client scope OIDC-клиенту в Keycloak

Назначьте созданный набор конфигураций OIDC-клиенту ТестОпс:

В Keycloak в сайдбаре слева перейдите в раздел Clients.
В списке клиентов откройте карточку OIDC-клиента, которого вы создали на шаге 2 (например, testops).
Перейдите на вкладку Client scopes.
Нажмите Add client scope.
Поставьте галочку напротив набора конфигураций, который вы создали на шаге 5.2 (например, openid).
Нажмите Add → Default.

5.4. Добавьте пользователей в группы в Keycloak

В Keycloak в сайдбаре слева перейдите в раздел Users.
В списке пользователей Keycloak откройте карточки пользователей, которым нужен доступ к ТестОпс. В карточке каждого из этих пользователей:
1. Перейдите на вкладку Groups.
2. Нажмите Join Group.
3. Поставьте галочку напротив созданной группы (например, to_admins или to_users), в которую нужно добавить пользователя.
Нажмите Join.

5.5. Настройте маппинг ролей в конфигурационных файлах ТестОпс

Измените параметры маппинга ролей в конфигурационных файлах ТестОпс в зависимости от вашего типа развертывания:

Измените параметры в файле values.yaml:

auth.openid.syncRoles — введите true, чтобы включить маппинг ролей между Keycloak и ТестОпс;
auth.openid.groupRoleAttribute — введите groups (название маппера групп в Keycloak из шага 5.2);
auth.openid.roleUserGroups — введите название группы Keycloak из шага 5.1, участники которой получат глобальную роль «Пользователь» в ТестОпс (например, to_users);
auth.openid.roleAdminGroups — введите название группы Keycloak из шага 5.1, участники которой получат глобальную роль «Администратор» в ТестОпс (например, to_admins).

Важно

Синхронизация ролей будет работать правильно только в случае, если параметр auth.openid.defaultRole из шага 4 имеет значение ROLE_GUEST.

Примеры настроенных конфигурационных файлов ТестОпс для OIDC с Keycloak

yaml

auth:
  primary: openid
  defaultRole: ROLE_GUEST
  openid:
    enabled: true
    clientName: testops
    clientId: testops
    clientSecret: Swi6lI8IpwSilx0WkmOx
    providerName: keycloak
    redirectUri: https://testops.example.com/login/oauth2/code/keycloak
    scope: openid, email, profile
    authorizationGrantType: authorization_code
    authorizationUri: https://keycloak.example.com/realms/testops-realm/protocol/openid-connect/auth
    jwksSetUri: https://keycloak.example.com/realms/testops-realm/protocol/openid-connect/certs
    tokenUri: https://keycloak.example.com/realms/testops-realm/protocol/openid-connect/token
    usernameAttribute: preferred_username
    defaultRole: ROLE_GUEST
    syncRoles: true
    groupRoleAttribute: groups
    roleUserGroups: to_users
    roleAdminGroups: to_admins

Использование OIDC вместе с локальной аутентификацией ТестОпс

Если OIDC указан как основной способ аутентификации в ТестОпс, при необходимости вы также можете использовать локальную аутентификацию:

Страница https://<домен_инстанса_ТестОпс>/login использует метод аутентификации, указанный в конфигурационных файлах ТестОпс в параметре primary или ALLURE_LOGIN_PRIMARY. Для данной инструкции это OIDC.
Страница https://<домен_инстанса_ТестОпс>/login/system использует локальную аутентификацию ТестОпс.

Чтобы войти в ТестОпс, например, с глобальной ролью «Администратор», перейдите на https://<домен_инстанса_ТестОпс>/login/system и используйте учетные данные локального пользователя.

Устранение неполадок

Если синхронизация ролей между Keycloak и ТестОпс не работает, проверьте содержимое токена доступа, получаемого от Keycloak:

Выполните API-вызов к инстансу Keycloak, например, с помощью curl:

shell

USERNAME=<имя_пользователя_в_Keycloak>
PASSWORD=<пароль_пользователя_в_Keycloak>
CLIENT_ID=<уникальный_идентификатор_OIDC-клиента_из_шага_2>
CLIENT_SECRET=<секрет_OIDC-клиента_из_шага_2>

RESPONSE=$(curl -X POST 'https://<домен_инстанса_Keycloak>/realms/<название_пространства>/protocol/openid-connect/token' \
    --data-urlencode "client_id=${CLIENT_ID}" \
    --data-urlencode "client_secret=${CLIENT_SECRET}" \
    --data-urlencode 'grant_type=password' \
    --data-urlencode 'scope=openid' \
    --data-urlencode "username=${USERNAME}" \
    --data-urlencode "password=${PASSWORD}")

ACCESS_TOKEN=$(echo $RESPONSE | jq .access_token)
echo "$ACCESS_TOKEN"

Декодируйте полученный токен доступа, например, с помощью jwt.io.
Отформатируйте полученные JSON-данные и убедитесь, что параметр groups содержит нужные группы, например:
json
```
{
  "scope": "openid profile email groups",
  "groups": [
    "to_admins"
  ],
  "preferred_username": "ivanivanov"
}
```

Аутентификация через OpenID Connect с Keycloak ​

Принцип работы аутентификации через OIDC с Keycloak ​

Настройка аутентификации через Keycloak ​

1. Создайте пространство в Keycloak ​

2. Создайте OIDC-клиента для ТестОпс в Keycloak ​

3. Получите OIDC-эндпоинты из настроек Keycloak ​

4. Измените конфигурационные файлы ТестОпс ​

5. Настройте маппинг ролей между Keycloak и ТестОпс ​

5.1. Создайте роли и группы в Keycloak ​

5.2. Создайте client scope в Keycloak ​

5.3. Назначьте client scope OIDC-клиенту в Keycloak ​

5.4. Добавьте пользователей в группы в Keycloak ​

5.5. Настройте маппинг ролей в конфигурационных файлах ТестОпс ​

Примеры настроенных конфигурационных файлов ТестОпс для OIDC с Keycloak ​

Использование OIDC вместе с локальной аутентификацией ТестОпс ​

Устранение неполадок ​