Подключение приложения по протоколу OIDC 1.0 / OAuth 2.0

Blitz Identity Provider в соответствии с принятой в OIDC 1.0 терминологией представляет собой OpenID-провайдером (OpenID Provider). Подключаемое к Blitz Identity Provider приложение в свою очередь называется клиентом (Client или Relying Party).

В общем виде настройка подключения по OIDC обычно включает следующие шаги:

  1. Регистрация приложения в Blitz Identity Provider.

  2. Конфигурирование протокола подключения приложения на стороне Blitz Identity Provider.

  3. Конфигурирование приложения – настройка параметров подключения к поставщику идентификации Blitz Identity Provider.

Регистрация приложения в Blitz Identity Provider

Для регистрации приложения необходимо перейти в раздел Приложения консоли и выбрать пункт «Добавить приложение»:

Перечень подключенных приложений

Это действие запустит мастер подключения. На первом этапе необходимо указать идентификатор подключаемого приложения – client_id, его название и домен, т.е. URL, по которому доступно данное приложение. Название приложения используется в дальнейшем в Blitz Identity Provider при отображении на странице входа в случае инициирования приложением запроса на идентификацию пользователя.

Для обозначения client_id недопустимо использовать двоеточия.


Домен приложения используется при необходимости перенаправления пользователя в приложение из веб-страниц Blitz Identity Provider. Перенаправление осуществляется на указанный домен или на переданный в процессе взаимодействия с Blitz Identity Provider специализированный redirect_url, но при этом выполняется сверка, что redirect_url соответствует заданному в настройке приложения домену.

В списке «Шаблон страниц» необходимо выбрать, на основе какого шаблона должна отображаться страница входа при попытке доступа пользователя в данное приложение. Шаблоны определяются в разделе Внешний вид консоли управления.

Первый шаг подключения приложения

Конфигурирование протокола подключения приложения на стороне Blitz Identity Provider

После добавления приложения необходимо перейти к редактированию специфических настроек OIDC, нажав на кнопку «Редактировать» (Редактировать). Далее выбрать протокол взаимодействия – OAuth 2.0 – и перейти к его конфигурированию, нажав по ссылке «Сконфигурировать».

Далее необходимо:

  • указать (или оставить сгенерированный системой) секретный ключ подключаемого приложения (client_secret), который должен использоваться подключенным приложением при обращении к Blitz Identity Provider;
  • предопределенная ссылка возврата (redirect_uri) – URL, на который по умолчанию будет переадресован пользователь после прохождения авторизации (опционально);
  • префиксы ссылок возврата – префикс используется для проверки ссылок возврата (redirect_uri). Если в запросе на аутентификацию указана ссылка возврата и она не соответствует ни одному из указанных префиксов, то в аутентификации будет отказано;
  • допустимые разрешения – разрешения (scope), которые имеет право запрашивать данное приложение;
  • разрешения по умолчанию – разрешения (scope), которые будут по умолчанию выданы приложению после аутентификации. Если не указаны, то в запросе на аутентификацию всегда должны быть явно прописаны требуемые разрешения.
Разрешения должны быть сконфигурированы в разделе OAuth консоли управления.


Настройки протокола OAuth 2.0 / OIDC для приложения

Окно предоставление доступа к данным

Кроме того, возможно добавление атрибутов в маркер идентификации (id_token), если взаимодействие осуществляется по протоколу OpenID Connect 1.0, а также изменение режима выдачи маркеров доступа по умолчанию. Blitz Identity Provider предусматривает два режима выдачи маркеров доступа (access_token):

  • offline-режим – при запросе маркера доступа будет выдан также бессрочный маркер обновления (refresh_token), которые может быть использован для получения нового маркера доступа. Приложению рекомендуется использовать этот режим, если оно должно получать актуальные данные пользователя из Blitz Identity Provider за пределами времени действия пользовательской сессии. Например, если приложение делает почтовую рассылку и перед ее отправкой хочет получить актуальный адрес электронной почты из Blitz Identity Provider.

  • online-режим – будет выдан только маркер доступа. Приложению рекомендуется использовать этот режим, если ему достаточно получать актуальные данные пользователя в момент входа (в течение активной сессии пользователя).

Режим выдачи маркеров доступа может быть явно указан в запросе на проведение аутентификации; если он не указан, то используется режим по умолчанию.

Если необходимо проведение аутентификации пользователя по протоколу OIDC (OpenID Connect 1.0), то в качестве одного из разрешений (scope) необходимо указать openid. В этом случае в обмен на авторизационный код при вызове Token Endpoint будут выданы не только маркер доступа и маркер обновления, но и идентификационный маркер (ID token).

Общие настройки OAuth 2.0 / OIDC 1.0

Для задания общих настроек OAuth 2.0, а также для конфигурирования набора разрешений (scope) используется раздел OAuth 2.0 консоли управления.

Задание общих настроек OAuth 2.0 / OIDC

В разделе OAuth 2.0 консоли управления можно посмотреть URL, которые далее потребуются для выполнения запросов:

  • URL с метаданными Blitz Identity Provider – по этой ссылке размещены динамически обновляемые настройки (метаданные) Blitz Identity Provider (спецификация). Разработчики приложений могут не прописывать все указанные ниже URL в конфигурации своего приложения, а использовать в настойках единую ссылку на эти метаданные;

  • OAuth 2.0 Authorization Endpoint – для запроса идентификации и аутентификации и получения авторизационного кода;

  • OAuth 2.0 Token Endpoint – для первичного получения маркера доступа / маркера идентификации и для обновления маркера.

Для корректной работы взаимодействия с приложениями по протоколу OAuth 2.0 / OIDC необходимо определить разрешения (scope). Для этого в разделе OAuth нужно указать:

  • название разрешения;
  • описание разрешения (оно будет отображаться пользователю на странице согласия на предоставление доступа);
  • атрибуты пользователя, которые будут предоставлены по данному разрешению.

Для корректной работы аутентификации по OIDC 1.0 нужно убедиться, что разрешение с названием openid определено на этой вкладке. Также можно прописать атрибуты, передаваемые по этому разрешению. В этом случае указанные данные могут быть получены по маркеру доступа (access token), выданному на разрешение openid.

Добавление атрибутов в маркер идентификации

Приложения, подключенные по протоколу OpenID Connect 1.0, могут получать данные в маркере идентификации. Перечень атрибутов, которые будут переданы в маркере идентификации, должен быть задан в пункте «Добавляемые в маркер идентификации (id_token) утверждения» настроек протокола.

Помимо хранимых атрибутов, в маркер идентификации могут быть добавлены утверждения, полученные при входе пользователя по электронной подписи – это могут быть данные о сертификате ключа электронной подписи, данные о физическом / юридическом лице из сертификата. Чтобы соответствующие утверждения из сертификата были доступны, необходимо отредактировать конфигурационный файл /etc/blitz-config/blitz.conf, добавив в блок настроек methods/x509 добавить структуру следующего содержания:

"claims" : [
  {
      "name" : "attr_name",
      "value" : "cert_attr_name"
  }
],

В этой структуре attr_name – имя атрибута, которое будет использовано в маркере идентификации, а cert_attr_name – обозначение атрибута в сертификате (примеры доступных значении приведены в таблице ниже).

Пример данных, получаемых из сертификата ключа электронной подписи

Обозначение атрибута в сертификате Описание
SUBJECT.OGRN ОГРН организации
SUBJECT.INN ИНН организации
SUBJECT.E Служебный email должностного лица
SUBJECT.O Имя организации
SUBJECT.ST Регион организации
SUBJECT.L Населенный пункт организации
SUBJECT.STREET Улица, дом, номер офиса организации
SUBJECT.O Подразделение должностного лица
SUBJECT.T Должность представителя

Пример добавляемой в конфигурационный файл структуры:

"claims" : [
  {
      "name" : "org_OGRN",
      "value" : "SUBJECT.OGRN"
  },
  {
      "name" : "org_INN",
      "value" : "SUBJECT.INN"
  },
  {
      "name" : "org_email",
      "value" : "SUBJECT.E"
  },
  {
      "name" : "org_name",
      "value" : "SUBJECT.O"
  }
],

Конфигурирование приложения (клиента)

Конфигурирование приложения должно осуществляться в соответствии с документацией на данное приложение. Если приложение не поддерживает протокол OIDC, следует произвести его доработку согласно рекомендациям.

На стороне приложения конфигурирование подключения к OpenID-провайдеру включает в себя:

  • указание идентификатора OpenID-провайдера (client_id);

  • указание секрета OpenID-провайдера (client_sectret);

  • указание URL для проведения авторизации и аутентификации. Обычно он имеет вид <hostname>/blitz/oauth/ae;

  • указание URL для получения и обновления маркера. Обычно он имеет вид <hostname>/blitz/oauth/te.

В приведенных выше ссылках <hostname> – это адрес, на котором установлен Blitz Identity Provider, например https://idp.reaxoft.ru. В разделе OAuth консоли управления можно посмотреть URL, приведенные выше.