Подключение приложения по протоколу 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

Регистрация приложений в Blitz Identity Provider необходима для того, чтобы приложения могли использовать предоставляемые Blitz Identity Provider сервисы:

  • запрашивать идентификацию и аутентификацию пользователей;

  • вызывать REST-сервисы Blitz Identity Provider (доступно только в Enterprise-редакции).

Управление приложениями осуществляется в разделе Приложения консоли управления.

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

Создание учетной записи нового приложения

Для подключения нового веб - приложения необходимо перейти в раздел Приложения консоли и выбрать пункт «Добавить приложение». Это действие запустит мастер подключения нового приложения, работа которого включает в себя следующие шаги:

Шаг 1. Базовые настройки. Требуется указать идентификатор подключаемого приложения (при подключении по протоколу SAML идентификатор соответствует entityID, при подключении по OAuth 2.0 – client_id, при задании идентификатора для OAuth 2.0 недопустимо использовать двоеточие), его название и домен, т.е. URL, по которому доступно данное приложение.

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

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

Базовые настройки приложения

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

В настройке «Префиксы ссылок возврата при выходе» нужно задать допустимые URL страниц перенаправления пользователя после инициирования приложением логаута. Настройку следует задавать только в случае, если вприложении реализована функция логаута. Допустимо задать один или несколько префиксов ссылок возврата.

Выбор шаблона страницы и настройка логаута

Шаг 3. Настройки протоколов подключения. Необходимо настроить один или несколько протоколов подключения приложения к Blitz Identity Provider.

Настройка протоколов подключения

Поддерживаются следующие протоколы подключения:

  • SAML – для подключения приложений по SAML 1.0, 1.1, 2.0 и WS-Federation для идентификации и аутентификации пользователей.;

  • OAuth 2.0 – для подключения приложений по OAuth 2.0, OpenID Connect 1.0 (OIDC) для идентификации и аутентификации пользователей. В рамках этого протокола возможно конфигурирование динамической регистрации клиентов;

  • Simple – для подключения веб-приложений для осуществления идентификации и аутентификации с помощью подстановки в приложение логина и пароля с proxy-сервера, если приложение не поддерживает возможности подключения по SAML/OIDC. Доступно только в Enterprise-редакции.;

  • REST – для подключения приложений, использующих REST-сервисы Blitz Identity Provider по регистрации/изменению учетных записей, управлению устройствами аутентификации пользователей. Доступно только в Enterprise-редакции.

Если организация планирует разработку или доработку собственных приложений для подключения их к Blitz Identity Provider, то разработчикам необходимо ознакомиться с документом «Руководство по интеграции». В том же документе описана и настройка приложений для использования REST-сервисов Blitz Identity Provider.

Если организация планирует подключить к Blitz Identity Provider приложения, имеющие штатную поддержку подключения по SAML 1.0, SAML 1.1, SAML 2.0, WS Federation или OIDC (OpenID Connect 1.0, OAuth 2.0), то можно обратиться в ООО «РЕАК СОФТ» за специализированной инструкцией по настройке этих приложений, либо воспользоваться описаниями в последующих подразделах, описывающих метод настройки на стороне Blitz Identity Provider подключения произвольного приложения с поддержкой SAML/OIDC.

Инструкции по применению протокола Simple для подключения к Blitz Identity Provider веб-приложений, в которых отсутствует поддержка SAML/OIDC, в данном руководстве не приводятся и могут быть высланы в виде отдельной инструкции под интеграцию конкретного приложения с Blitz Identity Provider. Для получения специализированной инструкции необходимо обратиться с запросом в ООО «РЕАК СОФТ».

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

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

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

  • указать (или оставить сгенерированный системой) секретный ключ подключаемого приложения (client_secret), который должен использоваться подключенным приложением при обращении к Blitz Identity Provider;

  • предопределенная ссылка возврата (redirect_uri) – URL, на который по умолчанию будет переадресован пользователь после прохождения авторизации (опционально);

  • префиксы ссылок возврата – префикс используется для проверки ссылок возврата (redirect_uri). Если в запросе на аутентификацию указана ссылка возврата и она не соответствует ни одному из указанных префиксов, то в аутентификации будет отказано;

  • допустимые разрешения – разрешения (scope), которые имеет право запрашивать данное приложение;

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

  • отметить при необходимости опцию «Обязательное использование Proof Key for Code Exchange (RFC 7636) для Authorization code grant type», если запросы на аутентификацию должны валидироваться согласно RFC 7636;

  • выбрать при необходимости метод аутентификации при обращении к сервису выдачи маркеров. Указанные методы аутентификации должны использоваться при обращении к сервису выдачи маркеров (token endpoint). При пустом значении доступны все методы;

  • выбрать при необходимости допустимые grant type. Параметр определяет список grant type, которые будут доступны приложению. При пустом списке доступны все grant type;

  • выбрать при необходимости допустимые response type. Параметр определяет список response type, которые будут доступны приложению при обращении к URL авторизации (authorization endpoint). При пустом списке доступны все response type.

Разрешения должны быть сконфигурированы в разделе OAuth консоли управления.


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

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

Возможно также изменение режима выдачи маркеров доступа по умолчанию.

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). В настойках приложения возможно добавление атрибутов в маркер идентификации (id_token), если взаимодействие осуществляется по протоколу OpenID Connect 1.0. Возможно добавление как атрибутов, сконфигурированных в разделе Источники данных, так и дополнительных атрибутов.

Общие настройки 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 нужно указать:

  • название разрешения;

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

  • является ли разрешение системным (данные разрешения получают интегрированные с Blitz Identity Provider приложения; используется в случае, если необходимо использовать маркеры доступа Blitz Identity Provider для регулирования доступа приложений к сервисам);

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

Для корректной работы аутентификации по 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"
  }
],

Чтобы утверждения из ЕСИА были доступны, необходимо отредактировать конфигурационный файл /etc/blitz-config/blitz.conf, добавив в блок настроек federation/points/esia структуру следующего содержания:


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

В этой структуре attr_name – имя атрибута, которое будет использовано в маркере идентификации, а esia_attr_name – обозначение атрибута при получении его из ЕСИА.

Пример данных, получаемых из ЕСИА при входе юридического лица

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


"claims" : [
              {
                  "name" : "org_OGRN",
                  "value" : "org.ogrn"
              },
              {
                  "name" : "org_INN",
                  "value" : "org.inn"
              },
              {
                  "name" : "org_name",
                  "value" : "org.name"
              },
              {
                  "name" : "org_chief",
                  "value" : "org.chief"
              }
          ],


Настройка динамической регистрации клиентов OAuth 2.0

Чтобы включить возможность динамической регистрации клиентов, необходимо выполнить следующие шаги: - зарегистрировать приложение и настроить для него протокол подключения OAuth 2.0 согласно документации;

  • в настройках OAuth 2.0 для данного приложения перейти на закладку «Динамические клиенты» .

Включение динамической регистрации клиентов

Указать базовые настройки динамической регистрации клиентов:

  • разрешить динамическую регистрацию клиентов;

  • указать допустимые к прямой передаче утверждения. Эти утверждения допускается указывать в запросе на регистрацию инстанса приложения. В случае их наличия в метаданных приложения (software_statement), приоритет будет отдан значению из метаданных. Рекомендуется разрешить передачу только типа устройства (device_type).

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

Сгенерировать метаданные приложения (software_statement). Эти метаданные передаются в качестве утверждения в запросе на регистрацию инстанса приложения. В качестве атрибутов метаданных можно указать:

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

  • префиксы ссылок возврата. Префикс используется для проверки ссылок возврата (redirect_uri). Если в запросе на аутентификацию указана ссылка возврата и она не соответствует ни одному из указанных префиксов, то в аутентификации будет отказано

  • допустимые разрешения – разрешения (scope), которые будут доступны приложению;

  • метод аутентификации при обращении к сервису выдачи маркеров. Указанный метод аутентификации должен использоваться инстансом приложения при обращении к сервису выдачи маркеров (token endpoint)

  • допустимые значения grant type. Список grant type, которые будут доступны инстансу приложения;

  • допустимые значения response type. Список response type, которые будут доступны инстансу приложения при обращении к URL авторизации (authorization endpoint)

Следует учесть, что указанные атрибуты метаданных должны соответствовать параметрам OAuth 2.0, определенным для приложения («Статический клиент»).

После подписания метаданных приложения их вместе с первичными маркерами следует передать разработчикам приложения, которое должно интегрироваться с Blitz Identity Provider.

Пример настроек динамической регистрации клиента представлен на рисунке ниже.

Настройки динамической регистрации клиентов

Настройка клиента REST-сервисов Blitz Identity Provider

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

  • нажать «Добавить приложение»;

  • указать идентификатор, название и домен системы;

  • нажать «Сохранить».

Далее перейти к настройкам приложения, в качестве протокола подключения указать REST и заполнить следующие данные:

  • пароль – будет использоваться при HTTP Basic-аутентификации, в качестве логина – идентификатор системы-клиента; если параметр не задан, то HTTP Basic-аутентификация не будет возможна для данной системы-клиента;

  • допустимые CN – перечень значений атрибута CN сертификата, используемого при TLS-аутентификации; если не заданы параметры, то TLS-аутентификация не будет возможна для данной системы-клиента.

Настройка приложения для работы с REST-сервисами

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

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