Общие сведения

Приложение позволяет использовать метод аутентификации OIDC со следующими ограничениями.

Полноценная учетная запись пользователя не может быть создана в приложении со стороны провайдера аутентификации. Если аутентифицирующийся пользователь не имеет учетной записи в приложении, учетная запись будет создана без ролей, принадлежности к группам и правил ограничений данных для датасетов.
Учетная запись пользователя не может быть удалена из приложения провайдером аутентификации.
При выходе из приложения сообщение о завершении сессии не отправляется провайдеру аутентификации, что в свою очередь не позволяет:
- завершить сессию и начать новую под другим пользователем – сессия завершится по истечении срока сессии, установленного в провайдере;
- использовать единый выход.
При завершении сессии в провайдере аутентификации приложение не получает сообщения о завершении сессии.

Настройка провайдера аутентификации на примере Keycloak

Для примера настроим провайдера аутентификации Keycloak для одного приложения Polymatica Dashboards TN (далее – приложение), чтобы использовать провайдера для аутентификации в приложении.

Для настройки нужно иметь доступ к консоли администратора Keycloak (далее – консоль администратора). При настройке будем обращаться к документации Keycloak, стандарту RFC6749 и документации OpenID Foundation, актуальным на момент написания.

1. Создаем новую область (realm). Область определяет границы взаимодействия приложений, пользователей этих приложений, их права, роли и т. п..

В консоли администратора, в левом верхнем углу страницы кликаем выпадающий список и кликаем в нём кнопку Create Realm.

Выпадающий список областей

Далее на открывшейся справа странице Create Realm вводим в поле Realm name название области и кликаем кнопку Create.

Страница Create Realm

2. Настроим область: установим название, отображаемое на странице аутентификации. А также скопируем значение для параметра POLYMATICA_CORE_OIDC_PROVIDER_ISSUER, который потребуется задать позже при настройке метода аутентификации в приложении.

В навигационной панели в левой части страницы кликаем вкладку Realm settings. На открывшейся справа странице, в поле HTML Display name вводим название для отображения на странице аутентификации – Polymatica. Кликаем кнопку Save.

Вкладка Realm settings. В заголовке вкладки отображается название области

Кликаем внизу страницы ссылку OpenID Endpoint Configuration, чтобы открыть метаданные провайдера, в открывшейся вкладке браузера находим ключ "issuer" (обычно самая верхняя после начала) и копируем значение, в нашем случае "https://dev-keycloak.polymatica.ru/auth/realms/Docs-realm".

Копируем значение ключа "issuer" для дальнейшего использования в параметре POLYMATICA_CORE_OIDC_PROVIDER_ISSUER

3. Добавим приложение в область.

В навигационной панели в левой части страницы кликаем вкладку Clients. На открывшейся справа странице кликаем кнопку Create client.

Кнопка Create Client на странице Clients

На открывшейся странице заполняем произвольным значением поле Client ID и кликаем внизу кнопку Next.

Заполнили поле Client ID понятным нам произвольным значением

На открывшейся странице переводим переключатель Client authentication в положение On и кликаем внизу кнопку Save. Параметр Client authentication определяет используемый тип клиента OpenID Connect.

Перевели переключатель Client authentication в положение On

4. Настроим добавленное приложение: укажем допустимые адреса переадресации для перехода после аутентификации.

На странице приложения Docs находим поле Valid redirect URIs. Так как мы используем тип клиента confidential, то адрес переадресации может быть любым: ставим символ «*», что означает – любое значение. Кликаем внизу кнопку Save.

Добавили допустимый адрес переадресации

5. Скопируем из добавленного приложения значение для параметра POLYMATICA_CORE_OIDC_PROVIDER_CLIENT_SECRET, который потребуется задать позже при настройке метода аутентификации в приложении.

Переходим на странице приложения Docs в секцию Credentials. Находим поле Client secret и в правой его части кликаем кнопку Copy to clipboard. Сохраняем скопированное значение в файл, чтобы не потерять (например, в блокнот).

Скопировали Client secret

6. Добавим учетную запись пользователя приложения. Если учетная запись не существует в приложении, она автоматически создается с ограничениями: заполняются только поля «Логин» и «E-mail», учетная запись не имеет ролей.

В навигационной панели в левой части страницы кликаем вкладку Users. На открывшейся справа странице Users кликаем кнопку Create new user.

Кликаем кнопку Create new user

На открывшейся странице Create user заполняем все поля формы, в том числе поля First name и Last name, что позволит, когда поддержка передаваемых полей будет доработана, не возвращаться к заполнению этих полей. После заполнения полей кликаем внизу кнопку Create.

Заполнили поля формы учетными данными пользователя

На открывшейся странице с логином пользователя в заголовке перейдем в секцию Credentials. и кликнем на ней кнопку Set password.

Секция Credentials страницы пользователя

В открывшемся окне Set password укажем в обоих полях временный пароль учетной записи для входа в приложение и кликнем кнопку Save.

Чтобы использовать установленный пароль в качестве постоянного, следует выключить параметр Temporary.

Окно установки пароля учетной записи

Подтвердим установку пароля – кликнем кнопку Save password.

Учетная запись пользователя готова. При первой аутентификации пользователю будет предложено сменить временный пароль, если параметр Temporary был оставлен включенным.

На этом шаге мы завершили настройку провайдера аутентификации Keycloak для одного приложения. Далее необходимо настроить метода аутентификации OIDC в приложении.

Настройка метода аутентификации OIDC в приложении

Чтобы включить в приложении метод аутентификации OIDC, выполните следующие действия.

Добавьте SSL-сертификат провайдера аутентификации.

- Для приложения, установленного с использованием пакетов:

1. 1. Добавьте сертификат в директорию /usr/local/share/ca-certificates/ операционной системы окружения.
  2. Выполните команду:
    update-ca-certificates

- Для приложения, установленного с использованием Docker:

1. 1. Добавьте сертификат в скрипт:
    #!/bin/bash echo "inserting certificate" cat << EOF >> /usr/local/share/ca-certificates/сертификат.crt -----BEGIN CERTIFICATE----- тело_сертификата -----END CERTIFICATE----- EOF echo "updating CA" update-ca-certificates exit 0
    где сертификат – файл, в который следует записать сертификат;
    тело_сертификата – содержимое сертификата.
  2. Добавьте скрипт для выполнения в контейнер сервиса Manager (см. Выполнение скрипта в контейнере сервиса при запуске контейнера).
Укажите параметры метода аутентификации OIDC в конфигурации приложения (см. Настраиваемые параметры конфигурации приложения).
Требуется указать следующие параметры и их значения.
```
POLYMATICA_CORE_OIDC_AUTH_METHOD_ACTIVE=true
POLYMATICA_CORE_OIDC_PROVIDER_NAME=keycloak_OP
POLYMATICA_CORE_OIDC_PROVIDER_ISSUER=https://dev-keycloak.polymatica.ru/auth/realms/Docs-realm
POLYMATICA_CORE_OIDC_PROVIDER_REDIRECT_URL=https://stage-docs.platform.polymatica.ru/auth/oidc-callback
POLYMATICA_CORE_OIDC_PROVIDER_CLIENT_ID=stage-docs
POLYMATICA_CORE_OIDC_PROVIDER_CLIENT_SECRET=jmMEby8L9Jo0TNweolgSiLaXR4AEGNna
POLYMATICA_CORE_OIDC_PROVIDER_SCOPE=openid email profile
POLYMATICA_CORE_OIDC_PROVIDER_CLAIMS_PREFERRED_USERNAME_KEY=preferred_username
POLYMATICA_CORE_OIDC_PROVIDER_CLAIMS_EMAIL_KEY=email
POLYMATICA_CORE_OIDC_PROVIDER_CLAIMS_FIRST_NAME_KEY=given_name
POLYMATICA_CORE_OIDC_PROVIDER_CLAIMS_LAST_NAME_KEY=family_name
POLYMATICA_CORE_OIDC_PROVIDER_CLAIMS_MIDDLE_NAME_KEY=middle_name
```
где POLYMATICA_CORE_OIDC_PROVIDER_NAME – произвольно выбранное наименование провайдера аутентификации;
POLYMATICA_CORE_OIDC_PROVIDER_ISSUER – значение ключа issuer в метаданных провайдера;
POLYMATICA_CORE_OIDC_PROVIDER_REDIRECT_URL – адрес клиента для перенаправления после успешной аутентификации в провайдере, должен иметь вид https://хост/auth/oidc-callback;
POLYMATICA_CORE_OIDC_PROVIDER_SCOPE – запрашиваемые приложением доступы;
POLYMATICA_CORE_OIDC_PROVIDER_CLIENT_ID – Client ID, заданный при настройке провайдера;
POLYMATICA_CORE_OIDC_PROVIDER_CLIENT_SECRET – Client secret, полученный при настройке провайдера;
POLYMATICA_CORE_OIDC_PROVIDER_CLAIMS_PREFERRED_USERNAME_KEY – параметр, определяющий логин пользователя приложения, в который передаём значение ключа preferred_username из токена;
POLYMATICA_CORE_OIDC_PROVIDER_CLAIMS_EMAIL_KEY – параметр, определяющий e-mail пользователя приложения, в который передаём значение ключа email из токена;
POLYMATICA_CORE_OIDC_PROVIDER_CLAIMS_FIRST_NAME_KEY – параметр, определяющий имя пользователя приложения, в который передаём значение ключа given_name из токена;
POLYMATICA_CORE_OIDC_PROVIDER_CLAIMS_LAST_NAME_KEY – параметр, определяющий фамилию пользователя приложения, в который передаём значение ключа family_name из токена;
POLYMATICA_CORE_OIDC_PROVIDER_CLAIMS_MIDDLE_NAME_KEY– параметр, определяющий отчество пользователя приложения, в который передаём значение ключа middle_name из токена.
Перезапустите приложение.

- Для приложения, установленного с использованием пакетов выполните команду:
```
systemctl restart polymatica-platform-manager
```
- Для приложения, установленного с использованием Docker выполните команду:
```
cd /srv/platform && docker compose up -d --remove-orphans || docker-compose up -d --remove-orphans
```

При правильно выполненной настройке, на странице входа в приложение должна отображаться вкладка «Open ID»:

Вкладка «Open ID» справа от вкладки «Стандартный»

По клику вкладки выполняется переадресация на страницу аутентификации OIDC-провайдера.

Аутентификация OIDC по умолчанию

Перед использованием метода аутентификации OIDC по умолчанию убедитесь, что метод настроен.

Чтобы установить метод аутентификации OIDC выбранным по умолчанию, в конфигурации приложения укажите параметр со значением:

AUTH_DEFAULT_METHOD=openIDConnect

после чего перезапустите приложение.

При правильно выполненной настройке, страница входа в приложение должна открываться на вкладке «Open ID», после чего автоматически выполняется переадресация на страницу аутентификации OIDC-провайдера.

Быстрые ссылки

Дерево страниц

Общие сведения

Настройка провайдера аутентификации на примере Keycloak

Настройка метода аутентификации OIDC в приложении

Аутентификация OIDC по умолчанию