Настройка OAuth 2.0 и OpenID Connect 1.0#

Настройка приложения#

При подключении приложения по OAuth 2.0 или OpenID Connect 1.0 (OIDC) в блоке «Настройки взаимодействия с приложением» необходимо задать следующие настройки взаимодействия с приложением:

указать секретный ключ (или использовать сгенерированный по умолчанию ключ) подключаемого приложения (client_secret), который должен использоваться подключенным приложением при обращении к Blitz Identity Provider (если не указан, то аутентификация приложения-клиента должна производиться иначе, например, с использованием proxy TLS);
указать дополнительный секретный ключ (client_secret) подключаемого приложения. Рекомендуется для случаев, когда нужно обеспечить плавную смену client_secret для данного приложения;
указать предопределенную ссылку возврата (redirect_uri) – URL, на который по умолчанию будет переадресован пользователь после прохождения авторизации (redirect_uri);
указать допустимые префиксы ссылок возврата – префикс используется для проверки ссылок возврата (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 2.0»;
указать режим выдачи маркеров доступа по умолчанию. Blitz Identity Provider предусматривает два режима выдачи маркеров доступа (access_token):
- offline-режим – при запросе маркера доступа будет выдан также бессрочный маркер обновления (refresh_token), которые может быть использован для получения нового маркера доступа. Приложению рекомендуется использовать этот режим, если оно должно получать актуальные данные пользователя из Blitz Identity Provider за пределами времени действия пользовательской сессии. Например, если приложение делает почтовую рассылку и перед ее отправкой хочет получить актуальный адрес электронной почты из Blitz Identity Provider.
- online-режим – будет выдан только маркер доступа. Приложению рекомендуется использовать этот режим, если ему достаточно получать актуальные данные пользователя в момент входа (в течение активной сессии пользователя).

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

указать время жизни маркера обновления (в секундах). Если параметр не задан, то берется из общих настроек из раздела «OAuth 2.0»;
указать добавляемые в маркер идентификации (id_token) утверждения. Если приложение взаимодействует с Blitz Identity Provider по протоколу OIDC (OpenID Connect 1.0), то в качестве одного из разрешений (scope) необходимо также указать openid. Тогда в обмен на авторизационный код при вызове Token Endpoint будут выданы не только маркер доступа (access token) и маркер обновления (refresh token), но и идентификационный маркер (id_token). В маркер идентификации будет включен идентификатор пользователя sub, а также дополнительные атрибуты, перечисленные в этой настройке. Возможно добавление как атрибутов, сконфигурированных в разделе «Источники данных», так и дополнительных атрибутов (подробнее см. Добавление атрибутов в маркер идентификации);
выбрать формат маркера доступа – можно выбрать opaque или JWT. Если параметр не задан, то берется из общих настроек из раздела «OAuth 2.0».

:size=80% — Настройки взаимодействия с приложением по OAuth 2.0 и OIDC#

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

указать префиксы ссылок возврата при выходе. Необходимо перечислить префиксы допустимых URL страниц перенаправления пользователя после инициирования приложением логаута. Допустимо задать один или несколько префиксов ссылок возврата;
предопределенная ссылка возврата при выходе – ссылка, на которую будет перенаправлен пользователь после логаута из приложения, если в параметрах вызова логаута от приложения не был передан адрес возврата post_logout_redirect_uri;
отметить при необходимости опцию «Не показывать пользователю экран с подтверждением выхода из системы» – если эту настройку не отметить, то пользователю будет показан экран с запросом подтверждения выхода из приложения;
ссылка для очистки сессии пользователя в браузере (Front channel) – указанный адрес обработчика приложения будет вызван из фрейма браузера в случае инициирования логаута пользователя;
отметить при необходимости опцию «Добавлять идентификатор сессии и эмитента в ссылку очистки сессии в браузере (Front channel)» – в этом случае в браузерный обработчик логаута приложения будет передан идентификатор сессии (sid);
ссылка для очистки сессии пользователя в приложении (Back channel) – указанный адрес обработчика приложения будет вызван с сервера Blitz Identity Provider в случае инициирования логаута пользователя;
отметить при необходимости опцию «Добавлять идентификатор сессии и эмитента в ссылку очистки сессии в приложении (Back channel)» – в этом случае на адрес обработчика приложения, вызванный с сервера Blitz Identity Provider в случае инициирования логаута пользователя, будет передан logout_token, содержащий идентификатор сессии пользователя (sid).

При использовании приложением авторизации по спецификации Device Authorization Grant (например, для подключения IOT-устройств, смарт ТВ, чат ботов, приложений голосовых помощников) в блоке «Настройки взаимодействия с приложением» в параметре «Допустимые response type» добавить вариант device code, а в параметре «Допустимые ``grant type``» добавить вариант urn:ietf:params:oauth:grant-type:device_code. Также в блоке «Device Authorization Grant» необходимо задать следующие настройки:

формат пользовательского кода, для этого следует использовать регулярные выражения;
время жизни пользовательского кода;
ссылку на страницу ввода пользовательского кода;
отметить при необходимости опцию «Добавлять в URL пользовательский код». В этом случае Blitz Identity Provider при авторизации будет возвращать не только ссылку на станицу ввода пользовательского кода (например, https://test.ru/device), но еще и ссылку с кодом в качестве параметра (например, https://test.ru/device?uc=676-267-324).

Общие настройки OAuth 2.0#

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

В разделе «OAuth 2.0» консоли управления можно посмотреть различные URL обработчиков Blitz Identity Provider, связанных с OAuth 2.0 и OIDC:

«URL с метаданными Blitz Identity Provider» – по этой ссылке размещены динамически обновляемые настройки (метаданные) Blitz Identity Provider (спецификация). Разработчики приложений могут не прописывать все указанные ниже URL в конфигурации своего приложения, а использовать в настойках единую ссылку на эти метаданные;
«URL для авторизации» – адрес обработчика OAuth 2.0 Authorization Endpoint для запросов через браузер на получение кода авторизации;
«URL для получения и обновления маркера» – адрес обработчика OAuth 2.0 Token Endpoint для получения маркеров безопасности (access_token, id_token, refresh_token).

При необходимости можно:

изменить «Время жизни маркера доступа», используемое по умолчанию при выпуске маркеров для всех приложений;
указать «Формат маркера доступа», используемый по умолчанию при выпуске маркеров для всех приложений: строка (opaque) или JWT;
изменить «Время жизни маркера обновления», используемое по умолчанию при выпуске маркеров для всех приложений;
отметить опцию «Аутентификация систем-клиентов с использованием Proxy TLS». В этом случае должно быть настроено взаимодействие приложений с Blitz Identity Provider через прокси-сервер с установкой двустороннего TSL соединения. В поле «Common Name (CN)» сертификата системы должен быть указан домен системы подключаемого приложения.

В разделе «Device Authorization Grant» можно определить общие настройки для взаимодействия с приложениями по спецификации Device Authorization Grant. Здесь имеется возможность указать:

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

При необходимости для каждого приложения можно указать свои настройки, связанные со спецификацией Device Authorization Grant.

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

название разрешения;
описание разрешения (оно будет отображаться пользователю на странице согласия на предоставление доступа);
атрибуты пользователя, которые будут предоставлены по данному разрешению (атрибуты должны быть определены в меню «Источники данных»);
является ли разрешение системным – такие разрешения предоставляются приложениям только с использованием OAuth 2.0 Client Credentials Flow (не в контексте разрешения отдельного пользователя, а общие).

Для корректной работы аутентификации по OpenID Connect 1.0 нужно убедиться, что разрешение с названием openid определено в этом разделе консоли. Также можно прописать атрибуты, передаваемые по этому разрешению.

В этом случае указанные данные могут быть получены по маркеру доступа (access token), выданному на разрешение openid.

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

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

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

полученные при входе пользователя по электронной подписи. Это могут быть данные о сертификате ключа электронной подписи, данные о физическом / юридическом лице из сертификата;
полученные при входе через ЕСИА;
определенные в процедуре входа.

Для получения утверждений из сертификата ключа электронной подписи необходимо отредактировать конфигурационный файл blitz.conf, добавив в блок настроек blitz.prod.local.idp.login.methods.x509 добавить структуру следующего содержания:

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

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

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

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

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

"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"
  }
],

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

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

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

Пример данных, получаемых из ЕСИА

Обозначение атрибута, полученного из ЕСИА	Описание
oid	Уникальный идентификатор учетной записи ЕСИА
lastName	Фамилия
firstName	Имя
middleName	Отчество
birthDate	Дата рождения
gender	Пол
snils	СНИЛС
inn	ИНН
passport	Паспортные данные
birthPlace	Место рождения
email	Эл. почта
mobile	Моб. телефон

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

"claims" : [
              {
                  "name" : "esia_firstName",
                  "value" : "firstName"
              },
              {
                  "name" : "esia_lastName",
                  "value" : "lastName"
              },
              {
                  "name" : "esia_middleName",
                  "value" : "middleName"
              },
              {
                  "name" : "esia_birthDate",
                  "value" : "birthDate"
              }
              {
                  "name" : "esia_gender",
                  "value" : "gender"
              }
              {
                  "name" : "esia_snils",
                  "value" : "snils"
              }
              {
                  "name" : "esia_inn",
                  "value" : "inn"
              }
              {
                  "name" : "esia_passport",
                  "value" : "passport"
              }
              {
                  "name" : "esia_birthPlace",
                  "value" : "birthPlace"
              }
              {
                  "name" : "esia_email",
                  "value" : "email"
              }
              {
                  "name" : "esia_mobile",
                  "value" : "mobile"
              }
          ],

Чтобы иметь возможность определять сессионные утверждения в процедуре входа, соответствующие утверждения также должны быть определены в конфигурационной файле. Для этого в раздел blitz.prod.local.idp.login конфигурационного файла необходимо добавить атрибут sessionClaims с перечнем утверждений, которые могут быть определены в процедуре.

Например, следующая запись позволяет определить атрибут custom_attr:

"sessionClaims" : [
   "custom_attr"
]

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

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

зарегистрировать приложение и настроить для него протокол подключения 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, определенным для приложения («Статический клиент»).

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

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

Настройка Simple#

Данный способ подключения приложения к Blitz Identity Provider можно применять при следующих условиях:

Приложение нельзя подключить к Blitz Identity Provider с использованием стандартных протоколов SAML или OIDC.
Приложение представляет собой веб-приложение, развернутое в собственной инфраструктуре (On-Premise). Доступ пользователей к приложениям можно организовать через реверсивный прокси-сервер.

Чтобы подключить приложение к Blitz Identity Provider по протоколу Simple, необходимо:

В настройках приложения в консоль управления выбрать протокол Simple и задать его настройки:
- SSL – настройка, указывающая, производится ли за прокси вызов подключаемого по Simple приложения по HTTP или по HTTPS. Рекомендуется в качестве прокси-сервера, защищающего приложение, использовать существующий веб-сервер приложения, и в таком случае соединение прокси-сервера с приложением будет осуществляться без TLS/SSL шифрования.
- Селектор формы – задается CSS-селектор, позволяющий определить положение формы входа на странице подключаемого приложения.
- Селектор поля с логином – задается CSS-селектор, позволяющий определить положение поля ввода логина на странице входа подключаемого приложения.
- URL выхода по умолчанию (опциональная настройка) – указывает, какой адрес должен вызвать Blitz Identity Provider при необходимости инициировать логаут в подключенном по Simple приложении в случае единого логаута в Blitz Identity Provider.
- URL для перехода после успешного выхода – указывает, какой адрес должен вызвать Blitz Identity Provider для перенаправления пользователя после успешного логаута, инициированного подключенным по Simple приложением.
- JavaScript (опциональная настройка) – встраиваемый в страницу входа подключаемого по Simple приложения JS-код, позволяющий обработать полученный от приложения ответ с результатами входа (проверить, что вход произведен успешно) и показать об этом ошибку в Blitz Identity Provider.
Пример значения:
```
var fm = document.querySelector('form[name=login]');

if (fm) {
    document.body.style.display = "none";
    var err = document.getElementById('lost-password');
    var errKey = err && err.innerHTML.indexOf('Неправильный пароль.') !== -1 ? 'incorrect_password' : 'unknown_error';
    var kvp = document.location.search.substr(1).split('&');
    kvp.push([encodeURI('error'),encodeURI(errKey)].join('='));
    window.location.search = kvp.join('&');
}

var aLogout = document.querySelector('#logout');
var href = aLogout ? aLogout.getAttribute("href") : null;
if (href) {
    var lp = encodeURIComponent(href);
    var slp = document.createElement('script');
    slp.setAttribute('src', 'https://idp.company.com/blitz/simple/slp?app=app_id&lp=' + lp);
    document.head.appendChild(slp);
}
```

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

Задать настройки проксирования запросов к приложению на веб-сервере.

Пример конфига для веб-сервера nginx:

map "" $idp_host {
        default <hostname сервера Blitz>:9000;
}

map "$http_Blitz_Idp" $idp_post_login {
        default "0";
        "prepare-login" "1";
}

map "$arg_passive" $activLogout {
        default "1";
        "true" "0";
}

upstream oc-web {
    server <hostname сервера приложения>:<порт приложения>;
}

server {
    listen 80;
    server_name <доменное имя приложения>;
    # enforce https
    return 301 https://$server_name$request_uri;
}

server {
    listen         443 ssl;
    server_name    <доменное имя приложения>;

    resolver               172.27.0.20 172.25.0.50 valid=300s;
    #resolver               8.8.8.8 valid=300s;

    #ssl_certificate        /etc/nginx/cert/<путь к сертификату в случае подключения по SSL>.pem;
    #ssl_certificate_key    /etc/nginx/cert/<путь к контейнеру в случае подключения по SSL>.pem;

    #ssl_certificate /etc/letsencrypt/live/app.company.com/fullchain.pem; # managed by Certbot
    #ssl_certificate_key /etc/letsencrypt/live/app.company.com/privkey.pem; # managed by Certbot

    access_log              /var/log/nginx/oc-acs.log full;
    error_log               /var/log/nginx/oc-err.log error;

    ### force timeouts if one of backend is died ##
    proxy_next_upstream error timeout invalid_header http_500 http_502 http_503 http_504;

    ### Set headers ####
    proxy_set_header        Accept-Encoding   "";
    proxy_set_header        Host            $host;
    proxy_set_header        X-Real-IP       $remote_addr;
    proxy_set_header        X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header        X-Forwarded-Proto $scheme;
    add_header              Front-End-Https   on;
    proxy_redirect          off;

    proxy_set_header        Cookie "$http_cookie;domain2auth=$host";
    proxy_hide_header       Content-Security-Policy;

    add_header Content-Security-Policy "default-src 'self' https://$idp_host; script-src 'self' https://$idp_host 'unsafe-eval'; img-src 'self' data: https://$idp_host; style-src 'self' 'unsafe-inline'; font-src 'self' data:; frame-src 'self'; connect-src 'self'";

    location ~ <path страницы входа в приложение>$ {
            #if ($http_referer ~* "/blitz/simple") {
            #    set $idp_post_login "1";
            #}
            if ($http_referer ~* "<доменное имя Blitz>") {
                set $idp_post_login "1";
            }
            if ($idp_post_login = "1" ) {
                proxy_pass http://oc-web$request_uri;
            }
            if ($idp_post_login = "0" ) {
                proxy_pass http://$idp_host/blitz/simple/prepare$request_uri;
                break;
            }
    }
    location ~ /logout$ {
        if ($activLogout = "1") {
            return 302 https://<доменное имя Blitz>/blitz/simple/active_logout?app=$host;
        }
        proxy_pass http://oc-web$request_uri;
    }
    location / {
        proxy_pass http://oc-web;
    }
}

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

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

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

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

Если для приложения не заданы настройки протокола подключения REST, то приложение не сможет использовать REST API сервера Blitz Identity Provider, защищаемые с использованием HTTP Basic авторизации.