OpenID Keycloak (OAuth2)

к сведению

Time поддерживает стандарт OpenID/OAuth2 для различных провайдеров авторизации.

Ниже приведены шаги для настройки OpenID авторизации с помощью Keycloak.

примечание

В качестве примера используется Keycloak, запущенный локально на порту 8080 и настроенный на работу с реалмом master.

Версия Keycloak — 23.0.4.

Требования

• Запущенный и настроенный вами Keycloak сервер. Документация по настройке Keycloak доступна на официальном сайте.
• Все пользователи имеют следующие атрибуты:
  • Адрес электронной почты — email
  • Имя учетной записи — username
  • Имя пользователя — firstName
  • Фамилия пользователя — lastName

Создание клиента

Теперь необходимо создать клиент в Keycloak.

1. Переходим в Clients справа и нажимаем кнопку Create client.

   

2. Следуем инструкциям конструктора.

   • Client ID — любой, его нужно будет указать в конфиге Time в параметре TIME_OPENIDSETTINGS_ID.
   • Client Type: OpenID Connect.
   • Нажимаем Next

   

3. На втором экране выбираем:

   • Client Authentication: On
   • Authorization: On
   • Authentication Flow:
     • Standard Flow
     • Direct access grants
     • Service accounts roles
   • Нажимаем Next

   

4. В Valid Redirect URIs пишем <ссылка на корень Time>/* (ссылка на корень Time — параметр TIME_SERVICESETTINGS_SITEURL)

   

5. Жмем Save и попадаем на страницу клиента

   

6. Во вкладке Credentials видим Client Secret. Копируем его в параметр Time TIME_OPENIDSETTINGS_SECRET

   

7. Переходим в Realm → Settings и на вкладке General видим Endpoints, рядом значение OpenID Endpoint Configuration.

   

8. Копируем ссылку, получается что-то похожее на http://localhost:8080/realms/master/.well-known/openid-configuration.

9. Убираем всё, начиная с /.well-known....

10. Получившуюся ссылку вставляем в параметр TIME_OPENIDSETTINGS_ISSUERURL.

Настройка Time

После проделанных по инструкции выше действий, конфигурация Time должна выглядеть примерно так:

Пример настроек OpenID для Keycloak

TIME_OPENIDSETTINGS_ENABLE: true
TIME_OPENIDSETTINGS_ID: "<Client Id из интерфейса>"
TIME_OPENIDSETTINGS_SECRET: "<Client Secret из интерфейса>"
TIME_OPENIDSETTINGS_SCOPE: "profile openid email"
TIME_OPENIDSETTINGS_ISSUERURL: "http://localhost:8080/realms/master"
TIME_OPENIDSETTINGS_BUTTONTEXT: "Keycloak"
TIME_OPENIDSETTINGS_BUTTONCOLOR: "#3CB8E3"

Дополнительные настройки

warning

Только для продвинутых пользователей. Не рекомендуется менять эти настройки, если вы не знаете, что делаете.

Time поддерживает дополнительные функции протокола авторизации OpenID. Ниже приведены настройки, которые можно указать в конфиге Time в разделе OpenIdSettings.

Пример доп. настроек OpenID для Keycloak

TIME_OPENIDSETTINGS_PROOFKEYCODEEXCHANGE: false
TIME_OPENIDSETTINGS_PROOFKEYCODECHALLENGE: ""
TIME_OPENIDSETTINGS_PROOFKEYCODECIPHER: "********************************"
TIME_OPENIDSETTINGS_SSOUSERMAPPING_ENABLE: false
TIME_OPENIDSETTINGS_SSOUSERMAPPING_USERNAMEATTRIBUTE: ""
TIME_OPENIDSETTINGS_SSOUSERMAPPING_EMAILATTRIBUTE: ""
TIME_OPENIDSETTINGS_SSOUSERMAPPING_AUTHDATAATTRIBUTE: ""
TIME_OPENIDSETTINGS_SSOUSERMAPPING_FIRSTNAMEATTRIBUTE: ""
TIME_OPENIDSETTINGS_SSOUSERMAPPING_LASTNAMEATTRIBUTE: ""

Proof Key Code Exchange (PKCE)

warning

Важно: если включен механизм PKCE, то он так же должен быть включен и на стороне сервера авторизации.

Proof Key Code Exchange (PKCE) — это дополнительная мера безопасности для OAuth2/OpenID авторизации, позволяющая дополнительно обезопасить процесс авторизации от атак перехвата кода авторизации.

Для включения PKCE необходимо настроить параметры Time:

• Установить параметр TIME_OPENIDSETTINGS_PROOFKEYCODEEXCHANGE: false
• В параметре TIME_OPENIDSETTINGS_PROOFKEYCODECHALLENGE должен быть указан метод SHA256 или plain
• В параметре TIME_OPENIDSETTINGS_PROOFKEYCODECIPHER должен быть указан секретный ключ, который будет использоваться для шифрования кода challenge. Длина ключа может быть 16, 24 или 32 байта

PKCE в Keycloak

Для включения PKCE в Keycloak необходимо:

• Зайти в настройки клиента в Keycloak
• Во вкладке Advanced найти настройку Proof Key for Code Exchange Code Challenge Method и выбрать значение S256 или plain (выбор любого метода включит PKCE механизм)

Свой маппинг полей пользователя на атрибуты OpenID

По умолчанию Time использует стандартные claim'ы OpenID для получения информации о пользователе. Но в некоторых случаях может потребоваться указывать свои поля для получения информации о пользователе.

Для этого необходимо, чтобы все поля, указанные в маппинге, присутствовали в claim'ах OpenID.

Стандартный маппинг полей:

• Username: preferred_username (если не указано, то nickname)
• Email: email
• AuthData: sub
• FirstName: given_name
• LastName: family_name
• В случае, если FirstName и LastName не указаны, то name делится по пробелу на две части и первая часть идет в FirstName, а вторая — в LastName

Для того, чтобы включить свой маппинг полей, необходимо:

• Установить параметр TIME_OPENIDSETTINGS_SSOUSERMAPPING_ENABLE: true
• Заполнить поля, для которых необходимо указать свой claim:
  • TIME_OPENIDSETTINGS_SSOUSERMAPPING_USERNAMEATTRIBUTE
  • TIME_OPENIDSETTINGS_SSOUSERMAPPING_EMAILATTRIBUTE
  • TIME_OPENIDSETTINGS_SSOUSERMAPPING_AUTHDATAATTRIBUTE
  • TIME_OPENIDSETTINGS_SSOUSERMAPPING_FIRSTNAMEATTRIBUTE
  • TIME_OPENIDSETTINGS_SSOUSERMAPPING_LASTNAMEATTRIBUTE

warning

Свой маппинг полей заменяет только те поля, для которых заполнены поля в параметрах TIME_OPENIDSETTINGS_SSOUSERMAPPING_*. Остальные поля будут заполнены стандартным маппингом.