Подключение веб-приложения#

Совет

См. описание принципа взаимодействия веб-приложения с Blitz Identity Provider по OIDC.

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

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

  • идентификатор, присвоенный приложению в Blitz Identity Provider (client_id);

  • секрет приложения (client_secret);

  • зарегистрированные для приложения URL возврата при авторизации;

  • зарегистрированные для приложения URL возврата при логауте;

  • зарегистрированные для приложения разрешения (scope).

В целях взаимодействия с Blitz Identity Provider веб-приложение должно использовать следующие адреса:

  • URL для проведения авторизации и аутентификации:

    • https://login-test.company.com/blitz/oauth/ae (тестовая среда)

    • https://login.company.com/blitz/oauth/ae (продуктивная среда)

  • URL для получения и обновления маркера доступа:

    • https://login-test.company.com/blitz/oauth/te (тестовая среда)

    • https://login.company.com/blitz/oauth/te (продуктивная среда)

  • URL для получения данных пользователя:

    • https://login-test.company.com/blitz/oauth/me (тестовая среда)

    • https://login.company.com/blitz/oauth/me (продуктивная среда)

  • URL для получения данных о маркере доступа:

    • https://login-test.company.com/blitz/oauth/introspect (тестовая среда)

    • https://login.company.com/blitz/oauth/introspect (продуктивная среда)

  • URL для выполнения логаута:

    • https://login-test.company.com/blitz/oauth/logout (тестовая среда)

    • https://login.company.com/blitz/oauth/logout (продуктивная среда)

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

Совет

См. RFC 8414 OAuth 2.0 Authorization Server Metadata.

  • https://login-test.company.com/blitz/.well-known/openid-configuration (тестовая среда)

  • https://login.company.com/blitz/.well-known/openid-configuration (продуктивная среда)

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

Готовые библиотеки#

Для интеграции приложения с Blitz Identity Provider можно использовать одну из множества готовых OAuth 2.0 библиотек или реализовать взаимодействие самостоятельно.

Получение кода авторизации#

Для проведения идентификации и аутентификации пользователя приложение должно направить пользователя на URL для получения в Blitz Identity Provider кода авторизации, передав в качестве параметров:

  • client_id – идентификатор клиента;

  • response_type – тип ответа (принимает значение code, token, code token, code id_token, code id_token token, id_token token, id_token);

    Важно

    Значение параметра response_type указывает выбранный приложением способ взаимодействия с Blitz Identity Provider:

    • code – Authorization Code Flow;

    • code token, code id_token token, code id_token token – Hybrid Flow;

    • id_token token, id_token – OIDC Implicit Flow;

    • token – OAuth 2.0 Implicit Flow.

  • response_mode (необязательный параметр) – позволяет явно указать требуемый способ передачи кода авторизации. При обычном подключении приложения к Blitz Identity Provider данный параметр передаваться не должен, так как рекомендуется использовать стандартные способы передачи кода авторизации (query – для Authorization Code Flow и fragment – для Implicit/Hybrid Flow).

    Возможные значения параметра response_mode:

    • query – значение кода авторизации (code) возвращается на redirect_uri приложения в форме query-параметра. Стандартный режим для Authorization Code Flow.

    • fragment – значение кода авторизации (code) возвращается на redirect_uri приложения в форме fragment-параметра (#). Стандартный режим для Implicit Flow.

    • form_post – в этом режиме параметры ответа на авторизацию кодируются как значения HTML-формы, которые автоматически отправляются в User Agent и передаются клиенту через метод HTTP POST, при этом результирующие параметры кодируются в теле с помощью формата application/x-www-form-urlencoded.

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

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

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

  • access_type (необязательный параметр) – требуется ли приложению получать refresh_token, необходимый для получения сведений о пользователе в дальнейшем, когда пользователь будет оффлайн. Принимает значение online или offline, refresh_token предоставляется при access_type=offline. Если значение не задано, то поведение определяется настройкой, заданной для указанного приложения в Blitz Identity Provider;

  • prompt (необязательный параметр) – указывает Blitz Identity Provider требуемый режим входа. Возможные значения параметра prompt:

    • none – запрет на аутентификацию.

      Если при выполнении запроса у Blitz Identity Provider возникнет потребность отобразить пользователю экран запроса идентификации/аутентификации, то Blitz Identity Provider не будет этого делать, а вернет системе на ее redirect_uri ошибку login_required. Вызов с параметром prompt=none нужно делать в случае, если приложение хочет проверить наличие у пользователя сессии Blitz Identity Provider, но не хочет, чтобы при выполнении такой проверки пользователю отобразился экран входа Blitz Identity Provider.

    • select_account – запрос смены текущего пользователя.

      Blitz Identity Provider отобразит пользователю экран выбора аккаунта, чтобы пользователь мог войти под другой учетной записью.

    • login – запрет на SSO.

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

      Если при повторной идентификации/аутентификации пользователь выполнит вход под другой учетной записью, то Blitz Identity Provider вернет системе на ее redirect_uri ошибку login_required. Вызов с параметром prompt=login нужно делать в случае, если приложение хочет явно запросить у пользователя идентификацию/аутентификацию, например, при доступе к требующей повышенной защиты функции приложения.

    Примечание

    Для prompt=login для приложения можно при необходимости включить иной сценарий обработки ситуации, что пользователь вошел под другой учетной записью, чем был ранее залогинен в сессии. А именно, можно включить, чтобы при вызове prompt=login осуществлялся принудительный логаут текущей сессии и создание сессии под новой учетной записью. Такое поведение не является рекомендуемым, но может быть включено для приложения по отдельному запросу.

  • nonce (необязательный параметр) – строка, используемая для привязки сессии приложения с маркером идентификации. При стандартном подключении приложения к Blitz Identity Provider с использованием Authorization Code Flow параметр nonce использовать нет необходимости.

    При подключении по Implicit Flow или Hybrid Flow данный параметр должен передаваться. Значение nonce должно быть случайной текстовой строкой.

  • display (необязательный параметр) – параметр в значении script передается только в случае запуска процесса входа через HTTP API.

  • bip_action_hint (необязательный параметр) – указывает Blitz Identity Provider, что страница входа должна открыться в одном из специальных режимов:

    • open_reg – открыть в режиме регистрации пользователя; при использовании этого режима можно дополнительно указать параметр login_hint со значением email пользователя, и тогда поле «Адрес электронной почты» будет перезаполнено указанным значением email;

    • open_recovery – открыть в режиме восстановления пароля; при использовании этого режима можно дополнительно указать параметр login_hint со значением email пользователя, и тогда поле «Логин» будет перезаполнено указанным значением email;

    • used_externalIdps:esia:esia_1 – открыть в режиме входа через ЕСИА;

    • used_externalIdps:esiadp:esiadp_1 – вход с использованием учетной записи ЕСИА (через получение согласия на доступ к цифровому профилю);

    • used_externalIdps:sbrf:sbrf_1 – открыть в режиме входа через Сбер ID;

    • used_externalIdps:sbb:sbb_1 – открыть в режиме входа через СберБизнес ID;

    • used_externalIdps:tcs:tcs_1 – открыть в режиме входа через Тинькофф ID;

    • used_externalIdps:vtb:vtb_1 – открыть в режиме входа через ВТБ ID;

    • used_externalIdps:alfa:alfa_1 – открыть в режиме входа через Альфа ID;

    • used_externalIdps:mos:mos_1 – открыть в режиме входа через Mos ID (СУДИР);

    • used_externalIdps:apple:apple_1 – открыть в режиме входа через Apple ID;

    • used_externalIdps:facebook:facebook_1 – открыть в режиме входа через Facebook [1];

    • used_externalIdps:google:google_1 – открыть в режиме входа через Google;

    • used_externalIdps:mail:mail_1 – открыть в режиме входа через Mail ID;

    • used_externalIdps:vkid:vkid_1 – открыть в режиме входа через VK ID;

    • used_externalIdps:ok:ok_1 – открыть в режиме входа через Одноклассники;

    • used_externalIdps:vk:vk_1 – открыть в режиме входа через VK;

    • used_externalIdps:yandex:: yandex_1 – открыть в режиме входа через Яндекс;

    • used_password – открыть в режиме входа по паролю (поведение по умолчанию);

    • used_webAuthn – открыть в режиме входа с использованием FIDO2 ключа (Passkey);

    • used_x509 – открыть в режиме входа по электронной подписи;

    • used_qrCode – открыть в режиме входа по QR-коду;

    • used_spnego – открыть в режиме входа по сеансу операционной системы;

    • used_sms – открыть в режиме входа по коду в SMS;

    • used_outside_methodname – открыть в режиме входа через внешний метод аутентификации с именем methodname.

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

    Идентификатор должен соответствовать одной из запомненных на устройстве учетных записей или страница входа будет открыта в режиме входа нового пользователя;

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

    Если нужно заполнить логин в случае, когда уже есть запомненный пользователь, то нужно использовать параметр login_hint в комбинации с параметром bip_user_hint;

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

  • code_challenge_method (необязательный параметр) – передается значение “S256”, если подключенное приложение поддерживает спецификацию PKCE для дополнительной защиты взаимодействия с Blitz Identity Provider.

    Совет

    См. RFC 7636 Proof Key for Code Exchange by OAuth Public Clients.

    Для подключения веб‑приложений применение PKCE не является обязательным.

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

  • code_challenge (необязательный параметр) – при использовании PKCE в этот параметр передается значение, вычисленное от code_verifier по следующей формуле:

    Совет

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

    code_challenge=BASE64URL-ENCODE(SHA256(ASCII(code_verifier)))

    Примечание

    Запрещается открывать страницу входа во фрейме. Пользователь должен видеть URL страницы входа, а также иметь возможность убедиться в наличии HTTPS-соединения веб-порталом login.company.com.

Пример запроса на получение кода авторизации (запрошена идентификация/аутентификация и маркер доступа с разрешениями openid и profile):

https://login.company.com/blitz/oauth/ae?client_id=ais&response_type=code&scope=openid+profile&access_type=offline&state=342a2c0c-d9ef-4cd6-b328-b67d9baf6a7f&redirect_uri=https%3A%2F%2Fapp.company.com%2Fre

Пример ответа со значением кода авторизации (code) и параметром state:

https://app.company.com/re?code=f954…nS0&state=342a2c0c-d9ef-4cd6-b328-b67d9baf6a7f

Возможные ошибки при вызове /oauth/ae соответствуют RFC 6749 и описаны здесь.

Пример запроса на получение кода авторизации, при котором Blitz Identity Provider не должен открыть страницу входа в случае, если пользователь еще не проходил идентификацию/аутентификацию в текущем веб-браузере:

https://login.company.com/blitz/oauth/ae?client_id=ais&response_type=code&scope=openid+profile&access_type=offline&state=342a2c0c-d9ef-4cd6-b328-b67d9baf6a7f&prompt=none&redirect_uri=https%3A%2F%2Fapp.company.com%2Fre

Пример ответа с ошибкой, если для получения кода авторизации пользователь должен явно пройти идентификацию/аутентификацию на странице входа Blitz Identity Provider, а запрос был выполнен с параметром prompt=none:

https://app.company.com/re?error=login_required&error_description=The+Authorization+Server+requires+End-User+authentication…&state=342a2c0c-d9ef-4cd6-b328-b67d9baf6a7f

Пример запроса на получение кода авторизации, при котором Blitz Identity Provider должен осуществить вход в режиме входа через ЕСИА:

https://login.company.com/blitz/oauth/ae?client_id=ais&response_type=code&scope=openid+profile&access_type=offline&state=342a2c0c-d9ef-4cd6-b328-b67d9baf6a7f&bip_action_hint=used_externalIdps:esia:esia_1&redirect_uri=https%3A%2F%2Fapp.company.com%2Fre

Пример запроса на получение маркера доступа и маркера идентификации с использованием OIDC Implicit Flow:

https://login.company.com/blitz/oauth/ae?client_id=ais&response_type=id_token%20token&scope=openid+profile&state=342a2c0c-d9ef-4cd6-b328-b67d9baf6a7f&nonce=n-0S6_WzA2Mj&redirect_uri=https%3A%2F%2Fapp.company.com%2Fre

Пример ответа от Blitz Identity Provider с маркерами доступа и идентификации, полученными с использованием OIDC Implicit Flow:

https://app.company.com/re#access_token=SlAV32hkKG&token_type=Bearer&id_token=eyJ0…NiJ9.eyJ1c…I6IjIifX0.DeWt4Qu…ZXso&expires_in=3600&state=342a2c0c-d9ef-4cd6-b328-b67d9baf6a7f

Пример запроса на получение кода авторизации и маркера идентификации с использованием OIDC Hybrid Flow:

https://login.company.com/blitz/oauth/ae?client_id=ais&response_type=code%20id_token&scope=openid+profile&state=342a2c0c-d9ef-4cd6-b328-b67d9baf6a7f&nonce=n-0S6_WzA2Mj&redirect_uri=https%3A%2F%2Fapp.company.com%2Fre

Пример ответа от Blitz Identity Provider с маркерами доступа и идентификации, полученными с использованием OIDC Hybrid Flow:

https://app.company.com/re#code=f954…FxS0&id_token=eyJ0…NiJ9.eyJ1c…I6IjIifX0.DeWt4Qu…ZXso&state=342a2c0c-d9ef-4cd6-b328-b67d9baf6a7f

Получение маркеров#

В целях проведения результата идентификации/аутентификации пользователя и получения его данных Blitz Identity Provider выпускает приложению различные маркеры.

Используемые в Blitz Identity Provider маркеры

Название

Обозначение

Предназначение и срок действия

Маркер доступа

access_token

Получение доступа к защищенному ресурсу, например, к данным пользователя.

Маркер действителен 3600 секунд.

Маркер обновления

refresh_token

Обновление маркера доступа. Маркер refresh_token предоставляется, только если для приложения при регистрации была указана необходимость получения refresh_token, или если в запросе на получение кода авторизации был указан параметр access_type=offline.

Маркер действителен до момента использования, но не дольше 365 дней.

Маркер идентификации

id_token

Получение идентификационной информации, например, идентификатора пользователя.

Маркер действителен 3 часа.

Обмен кода авторизации на маркеры

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

Внимание

Сервис получения маркеров должен обязательно вызываться с серверов подключенного к Blitz Identity Provider приложения. Вызов сервиса из выполняемого на стороне веб-браузера программного кода (например, из JavaScript кода веб-страницы) ЗАПРЕЩАЕТСЯ. Полученный маркер доступа (access_token) должен обрабатываться серверной частью приложения и не должен передаваться через браузер пользователя.

Метод

POST https://login.company.com/blitz/oauth/te

Заголовки

Authorization со значением Basic {secret}, где secret – это client_id:client_secret (например, app:topsecret) в формате Base64.

Тело запроса

  • code – значение кода авторизации, который был ранее получен;

  • grant_type – принимает значение authorization_code, если код авторизации обменивается на маркер доступа;

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

  • code_verifier (только если используется PKCE) – значение проверочного кода, использованного при расчете code_challenge при получении кода авторизации.

Возвращает

  • В случае успеха - маркер доступа, маркер обновления и маркер идентификации.

    Совет

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

  • Если код авторизации был уже использован, не совпал redirect_uri с ранее использованным в вызове к /oauth/ae, или истек срок действия кода, либо переданный code_verifier не соответствует code_challenge, то в качестве ответа будет возвращена ошибка. Возможные ошибки при вызове /oauth/te соответствуют RFC 6749 и описаны здесь.

Примеры

POST /blitz/oauth/te HTTP/1.1
Authorization: Basic cG9ydGFsLmlhc2l1LmxvY2FsOnBvcnRhbC5pYXNpdS5sb2NhbA==
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code=FLZHS…GU&redirect_uri=https%3A%2F%2Fapp.company.com%2Fre

{
    "id_token": "eyJhbGciOiJSUzI1NiJ9.eyJub…n0=.Ckt…sQ",
    "access_token": "dO-xym…BE",
    "expires_in": 3600,
    "refresh_token": "1lEWX…Iw",
    "token_type": "Bearer"
}

{
    "error": "invalid_grant",
    "error_description": "The provided authorization grant … is invalid, expired, revoked…"
}

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

Метод

POST https://login.company.com/blitz/oauth/te

Заголовки

Authorization со значением Basic {secret}, где secret – это client_id:client_secret (например, app:topsecret) в формате Base64.

Тело запроса

  • refresh_token – маркер обновления;

  • grant_type – принимает значение refresh_token, если маркер обновления обменивается на маркер доступа.

Пример запроса#
POST /blitz/oauth/te HTTP/1.1
Authorization: Basic cG9ydGFsLmlhc2l1LmxvY2FsOnBvcnRhbC5pYXNpdS5sb2NhbA==
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&refresh_token=jj2DA…bQ

Обмен маркера доступа

Приложение может обменять access_token с одним набором разрешений (scopes) и утверждений (claims) на access_token с другим набором разрешений и утверждений с использованием OAuth 2.0 Token Exchange. Это может быть полезно перед передачей access_token от получившего его приложения другому приложению, чтобы приложение получило сокращенный набор разрешений и сведений о пользователе.

Внимание

Для использования обмена маркера доступа приложению должно быть предоставлено специальное разрешение на использование OAuth 2.0 Token Exchange (разрешен grant_type – urn:ietf:params:oauth:grant-type:token-exchange). Также должны быть заданы настройки правил обмена маркеров доступа.

Метод

POST https://login.company.com/blitz/oauth/te

Заголовки

Authorization со значением Basic {secret}, где secret – это client_id:client_secret (например, app:topsecret) в формате Base64.

Тело запроса

Внимание

Должен быть указан один из параметров resource или audience.

  • grant_type – принимает значение urn:ietf:params:oauth:grant-type:token-exchange.

  • resource – принимает имя ресурса, для передачи которому запрашивается обмен маркера доступа.

  • audience – принимает имена приложений, для передачи которым запрашивается маркер доступа.

  • subject_token_type – передается требуемый тип получаемого маркера. В текущей версии Blitz Identity Provider поддерживается только тип urn:ietf:params:oauth:token-type:access_token.

  • subject_token – передается значение заменяемого маркера доступа (access_token).

  • Необязательный параметр scope – указывает перечень запрашиваемых scope в новом маркере. Если данный параметр не указан, то в новый маркер будут включены все scope, разрешенные правилом обмена.

  • Необязательный параметр token_format – указывает требуемый формат для выпускаемого маркера доступа. Возможные значения: jwt или opaque. Если данный параметр не указан, то новый маркер доступа будет выпущен в том же формате, что и маркер доступа, переданный в subject_token.

Примеры

Стандартный запрос#
POST /blitz/oauth/te HTTP/1.1
Authorization: Basic cG9…A==
Content-Type: application/x-www-form-urlencoded

grant_type=urn:ietf:params:oauth:grant-type:token-exchange&resource=…&subject_token_type=urn:ietf:params:oauth:token-type:access_token&subject_token=eyJ…vA
Запрос с передачей audience, token_format и scope#
POST /blitz/oauth/te HTTP/1.1
Authorization: Basic cG9…A==
Content-Type: application/x-www-form-urlencoded

grant_type=urn:ietf:params:oauth:grant-type:token-exchange&token_format=opawue&audience=system1 system2&scope=openid profile&subject_token_type=urn:ietf:params:oauth:token-type:access_token&subject_token=uuy…OE

{
    "access_token": "eyJr...-g",
    "expires_in": 3600,
    "scope": "openid new_scope",
    "token_type": "Bearer",
    "issued_token_type": "urn:ietf:params:oauth:token_type:access_token"
}
Не найдено правил, разрешающих запрошенный обмен маркера доступа#
{
    "error": "invalid_target",
    "error_description": "Access denied for resource or audience"
}
Маркер доступа просрочен#
{
    "error": "bad_access_token",
    "error_description": "Access token 'CmJ…Dk' not found"
}

Использование OAuth 2.0 Resource Owner Password Credentials

Если приложению предоставлено специальное разрешение на использование OAuth 2.0 Resource Owner Password Credentials (ROPC) (разрешен grant_type – password), то приложение может запросить получение маркера доступа следующим образом.

Метод

POST https://login.company.com/blitz/oauth/te

Заголовки

Authorization со значением Basic {secret}, где secret – это client_id:client_secret (например, app:topsecret) в формате Base64.

Тело запроса

  • grant_type – принимает значение password;

  • username – содержит логин пользователя;

  • password – содержит пароль пользователя;

  • scope – содержит список запрашиваемых разрешений.

Возвращает

  • В случае успеха - маркер доступа.

  • В случае неудачи - ошибку. Возможные значения для error_description при проблеме с учетной записью:

    • Invalid user credentials – неправильный логин или пароль;

    • User locked – учетная запись заблокирована;

    • User locked by inactivity – учетная запись заблокирована по причине длительной неактивности;

    • Password method locked – для учетной записи включен запрет на использование парольной аутентификации;

    • Password method not configured – метод парольной аутентификации не сконфигурирован;

    • Password expired – срок действия пароль истек;

    • Need password change – требуется обязательная смена пароля при входе.

POST /blitz/oauth/te HTTP/1.1
Authorization: Basic cG9…A==
Content-Type: application/x-www-form-urlencoded

grant_type=password&username=testuser&password=testpwd1&scope=profile

{
    "access_token": "dO-xym…BE",
    "expires_in": 3600,
    "scope": "profile",
    "token_type": "Bearer"
}

{
    "error": "invalid_grant",
    "error_description": "Invalid user credentials"
}

Маркер идентификации#

Для получения данных об идентификации и аутентификации приложение может самостоятельно анализировать содержание маркера идентификации (id_token).

Совет

Вместо анализа id_token рекомендуется использовать запрос на актуализацию данных пользователя по маркеру доступа.

Структура маркера

Маркер идентификации состоит из трех частей:

  • заголовок (header), в котором содержится общая информация о типе маркера, в том числе об использованных в ходе его формирования криптографических операциях;

  • набор утверждений (payload / claim set) с содержательными сведениями о маркере;

  • подпись (signature), которая удостоверяет, что маркер выдан Blitz Identity Provider и не был изменен при передаче.

Части маркера разделены точкой, он имеет вид:

HEADER.PAYLOAD.SIGNATURE

Маркер передается в виде строки в формате Base64url.

Заголовок маркера

  • alg – описание алгоритма шифрования (параметр alg); в настоящее время в Blitz Identity Provider поддерживается алгоритм электронной подписи RSA SHA-256, рекомендуемый спецификацией (соответствует значению RS256);

  • kid – идентификатор ключа, использованного для подписи маркера.

Набор утверждений

Атрибуты:

  • exp – время прекращения действия, указывается в секундах с 1 января 1970 г. 00:00:00 GMT;

  • iat – время выдачи, указывается в секундах с 1 января 1970 г. 00:00:00 GMT;

  • sub – идентификатор субъекта, в качестве значения указывается значение идентификатора пользователя;

  • ua_id – идентификатор устройства пользователя;

  • aud – адресат маркера, указывается client_id приложения, направившего запрос на аутентификацию;

  • iss – организация, выпустившая маркер, указывается URL issuer, по умолчанию https://login.company.com/blitz;

  • nonce – строка безопасности, указывается значение nonce, которое было передано приложением к Blitz Identity Provider в исходном запросе к /oauth/ae. Используется только при Implicit или Hybrid Flow. При получении приложением маркера с использованием Implicit или Hybrid Flow приложение должно сопоставить nonce из состава маркера идентификации с nonce из своего запроса;

  • at_hash – половина хэша маркера доступа, передается только при использовании Implicit или Hybrid Flow. Представляет собой закодированную в Base64 левую половину значения функции SHA‑256 от access_token. Приложение, получившее маркер доступа с использованием Implicit или Hybrid Flow должно извлечь из маркера идентификации значение at_hash и сравнить с маркером доступа.

  • c_hash – половина хэша кода авторизации, передается только в случае использования Hybrid Flow. Представляет собой закодированную в Base64 левую половину (128 бит) значения функции SHA‑256 от кода авторизации (code); Приложение, получившее код авторизации с использованием Hybrid Flow, должно извлечь из маркера идентификации значение c_hash и сравнить с кодом авторизации.

  • amr – пройденные методы аутентификации, указывается список пройденных пользователем методов аутентификаций. Список может включать следующие идентификаторы методов:

    • password – вход с использованием пароля;

    • cls:<метод> (например, cls:password) – автоматический вход с запомненного устройства (в названии идентификатора после двоеточия указан метод аутентификации, первично пройденной пользователем, в результате чего произошло запоминание пользователя на данном устройстве);

    • css – автоматический вход по результатам регистрации пользователя, восстановления пароля или перехода в веб-приложение из мобильного приложения, использующего вызов с использованием scope=native;

    • sms – подтверждение входа с помощью кода в SMS-сообщении (второй фактор аутентификации);

    • email – подтверждение входа с помощью кода в сообщении электронной почты (второй фактор аутентификации);

    • push – подтверждение входа с помощью кода в push-уведомлении в мобильное приложение (второй фактор аутентификации);

    • hotp – подтверждение входа с помощью кода, сгенерированного HOTP‑генератором кодов подтверждения (второй фактор аутентификации);

    • totp – подтверждение входа с помощью кода, сгенерированного программным TOTP-генератором кодов подтверждения (второй фактор аутентификации);

    • tls – вход в режиме автоматической аутентификации с использованием TLS Proxy;

    • spnego – вход с использованием сеанса операционной системы;

    • userApp – вход в мобильное приложение привязанной к устройству учетной записью пользователя (Touch ID/Face ID/ПИН-код);

    • webAuthn – вход с использованием FIDO2 ключа (Passkey) или подтверждение входа с помощью U2F-ключа;

    • x509 – вход с использованием электронной подписи;

    • qrCode – вход по QR-коду;

    • externalIdps:esia:esia_1 – вход с использованием учетной записи ЕСИА;

    • externalIdps:esiadp:esiadp_1 – вход с использованием учетной записи ЕСИА (через получение согласия на доступ к цифровому профилю);

    • externalIdps:sbrf:sbrf_1 – вход с использованием учетной записи Сбер ID;

    • externalIdps:sbb:sbb_1 – вход с использованием учетной записи СберБизнес ID;

    • externalIdps:tcs:tcs_1 – вход с использованием учетной записи Тинькофф ID;

    • externalIdps:vtb:vtb_1 – вход с использованием учетной записи ВТБ ID;

    • externalIdps:alfa:alfa_1 – вход с использованием учетной записи Альфа ID;

    • externalIdps:mos:mos_1 – вход с использованием учетной записи Mos ID (СУДИР);

    • externalIdps:apple:apple_1 – вход с использованием учетной записи Apple ID;

    • externalIdps:facebook:facebook_1 – вход с использованием учетной записи в социальной сети Facebook [1];

    • externalIdps:google:google_1 – вход с использованием учетной записи Google;

    • externalIdps:mail:mail_1 – вход с использованием учетной записи Mail ID;

    • externalIdps:vkid:vkid_1 – вход с использованием учетной записи VK ID;

    • externalIdps:ok:ok_1 – вход с использованием учетной записи в социальной сети Одноклассники;

    • externalIdps:vk:vk_1 – вход с использованием учетной записи в социальной сети VK;

    • externalIdps:yandex:yandex_1 – вход с использованием учетной записи Яндекс;

    • outside_methodname – признак, что в процессе входа пользователь использовал внешний метод аутентификации с именем methodname.

  • sid – идентификатор сессии пользователя;

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

Пример набора утверждений#
{
    "exp": 1445004777,
    "iat": 1444994212,
    "ua_id": "f8a235ff-cb85-4c4b-b55d-544f9358a8d7",
    "sub": "3d10f626-ea77-481d-a50bd4a4d432d86b",
    "amr": [
        "externalIdps:esia:esia_1"
    ],
    "aud": [
        "ais"
    ],
    "iss": "https://login.company.com/blitz",
    "sid": "5a600d12-4b14-447e-ba21-2dc40344a44a"
}
Подпись маркера

Осуществляется по алгоритму, который указывается в параметре alg маркера. Подпись вычисляется от двух предыдущих частей маркера (HEADER.PAYLOAD). Сертификат открытого ключа Blitz Identity Provider, необходимый для проверки подписи, можно загрузить по следующим ссылкам (находится в атрибуте x5c, идентификатор ключа находится в атрибуте kid):

  • https://login-test.company.com/blitz/.well-known/jwks (тестовая среда)

  • https://login.company.com/blitz/.well-known/jwks (продуктивная среда)

Работа с маркером идентификации

  1. После получения маркера идентификации приложению рекомендуется произвести валидацию маркера идентификации, которая включает в себя следующие проверки:

    1. Получение идентификатора Blitz Identity Provider (sub), содержащегося в маркере идентификации, и получение иных необходимых приложению дополнительных атрибутов пользователя.

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

    3. Проверка подписи маркера идентификации (с использованием указанного в маркере алгоритма).

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

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

  2. Для анализа содержания маркера идентификации, а также для упрощения разработки модулей по его проверке можно воспользоваться доступными онлайн-декодерами и библиотеками.

    Совет

    См. ресурсы http://jwt.io/ и http://kjur.github.io/jsjws/mobile/tool_jwt.html#verifier.

Проверка маркера доступа через сервис интроспекции#

Данные о маркере доступа (access_token) необходимо проверять в следующих случаях:

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

  • к приложению предъявляются повышенные требования к безопасности, и приложение хочет через проверку маркера убедиться, что маркер не аннулирован досрочно. Аннулирование маркера доступам (access_token) или маркера идентификации (id_token) может произойти в целях безопасности в случае, если произошли сброс/изменение пароля учетной записи пользователя или если учетная запись пользователя была заблокирована;

  • приложение является поставщиком ресурсов и предоставляет доступ к этим ресурсам по предъявлению маркера доступа, выданного Blitz Identity Provider приложению, запрашивающему ресурс.

Метод

POST https://login.company.com/blitz/oauth/introspect

Совет

См. RFC 7662 OAuth 2.0 Token Introspection.

Сервис интроспекции может быть вызван любой системой, зарегистрированной в Blitz Identity Provider, для проверки любого маркера доступа (система может проверить маркер, выданный другой системе). Проверять можно не только маркер доступа, но и маркер обновления.

Заголовки

  • Authorization со значением Basic {secret}, где secret – это client_id:client_secret (например, app:topsecret) в формате Base64;

  • Content-Type со значением application/x-www-form-urlencoded.

Тело запроса

  • token – маркер доступа, данные о котором требуется просмотреть.

  • Необязательный параметр token_type_hint – тип маркера доступа (например, access_token), предназначен для ускорения поиска.

Возвращает

Данные о маркере доступа:

  • active – признак действительности маркера доступа, принимает значения true или false. Маркер действителен, если он выдан сервисом авторизации Blitz Identity Provider, не был отозван и срок его действия не истек;

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

  • client_id – идентификатор системы-клиента, которая получила данный маркер доступа;

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

  • jti – идентификатор маркера доступа (в виде строки);

  • token_type – тип предъявленного маркера доступа;

  • iat – время выдачи маркера (в Unix Epoch);

  • exp – время окончания действия маркера (в Unix Epoch).

Примеры

POST /blitz/oauth/introspect HTTP/1.1
Authorization: Basic cG9ydGFsLmlhc2l1LmxvY2FsOnBvcnRhbC5pYXNpdS5sb2NhbA==
Content-Type: application/x-www-form-urlencoded

token=MkvRf…No
Действующий access_token#
{
   "sub": "3d10f626-ea77-481d-a50bd4a4d432d86b",
   "scope": "openid profile",
   "jti": "10jdlNohfHzuv3xoFurvWSPheEJEC7KHdHr-dcaVyYYvV3h0l2sh",
   "token_type": "Bearer",
   "client_id": "ais",
   "active": true,
   "iat": 1699938503,
   "exp": 1699942103
}
Действующий id_token#
{
    "exp": 1699939472,
    "iat": 1699935872,
    "jti": "fU2FTCzm9G5I4YC6VDFnfjFY5QeIULwHlYo_BH6OuCQ",
    "token_type": "id_token",
    "active": true,
    "client_id": "ais",
    "sub": "3d10f626-ea77-481d-a50bd4a4d432d86b"
}
Действующий refresh_token#
{
    "sub": "3d10f626-ea77-481d-a50bd4a4d432d86b",
    "scope": "openid profile",
    "jti": "10jdlNohfHzuv3xoFurvWSPheEJEC7KHdHr-dcaVyYYvV3h0l2sh",
    "token_type": "refresh_token",
    "client_id": "ais",
    "active": true,
    "iat": 1699938503,
    "exp": 1699942103
}
Недействительный маркер доступа#
{
    "active": false
}

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

При регистрации приложения в Blitz Identity Provider можно указать, что приложение должно получать маркер доступа (access_token) в формате JWT. В этом случае приложение получает возможность самостоятельно проверить маркер доступа, выполнив его разбор.

Структура первично полученного маркера доступа будет аналогична структуре этого маркера идентификации. Во вторичных маркерах доступа, полученных в результате обмена маркера обновления (refresh_token), не будет содержаться сессионная информация (будут отсутствовать amr и дополнительные атрибуты пользователя).

Маркеры доступа в формате JWT следует использовать, только в случае если у приложения на это есть особые причины. В остальных случаях рекомендуется использовать обычные маркеры доступа в формате opaque.

Логаут#

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

Если этого не сделать, то может возникнуть ситуация, что пользователь в приложении нажал кнопку Выход, после чего сразу попробовал нажать кнопку Вход, и вместо ожидаемого запроса идентификации и аутентификации сработал Single Sign-On, и пользователь сразу автоматически оказался авторизованным.

Для инициирования логаута в Blitz Identity Provider приложение после закрытия своей локальной сессии должно направить пользователя в Blitz Identity Provider на URL для выполнения логаута, передав в качестве параметров:

Примечание

Вызов логаута выполняется в соответствии со спецификацией OpenID Connect RP-Initiated Logout 1.0.

  • Необязательный параметр id_token_hint - Blitz Identity Provider проверяет, что id_token из значения параметра выпущен им. Допустимые адреса возврата при логауте и дизайн страницы выхода используются в соответствии с настроенным приложением с client_id из поля aud из id_token.

  • Необязательный параметр client_id – допустимые адреса возврата при логауте и дизайн страницы выхода используются в соответствии с указанным client_id.

  • Необязательный параметр post_logout_redirect_uri – адрес возврата в приложение после логаута. Если параметр не задан, то перенаправление в приложение после логаута не осуществляется. Если задан, то проверяется, что значение соответствует хотя бы одному разрешенному префиксу возврата для приложения, соответствующего переданному в id_token_hint приложению (поле aud из id_token) или переданному client_id. При передаче параметра post_logout_redirect_uri обязательно также передать параметр id_token_hint или client_id.

  • state - набор случайных символов, имеющий вид 128-битного идентификатора запроса. Это же значение будет возвращено в ответе при перенаправлении пользователя на post_logout_redirect_uri.

Пример запроса логаута:

https://login.company.com/blitz/oauth/logout?id_token_hint=eyJhbGciOiJSUzI1NiJ9.eyJub…n0=.Ckt…sQ&post_logout_redirect_uri=https://app.company.com/redirect_uri&state=342a2c0c-d9ef-4cd6-b328-b67d9baf6a7f

Если Blitz Identity Provider успешно завершит логаут, то он перенаправит пользователя по переданному URL обратно в приложение.

Альтернативный пример запроса логаута:

https://login.company.com/blitz/oauth/logout?client_id=test-app&post_logout_redirect_uri=https://app.company.com/redirect_uri&state=342a2c0c-d9ef-4cd6-b328-b67d9baf6a7f

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

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

Для уведомления через веб-браузер в настройках приложения в Blitz Identity Provider регистрируется обработчик «Ссылка для очистки сессии пользователя в браузере (Front channel)». Если обработчик зарегистрирован и в процессе сессии пользователь входил в приложение, то при вызове пользователем логаута Blitz Identity Provider через браузер на странице выхода пользователя через фрейм <iframe src= "ссылка"> вызовет через HTTP GET указанный в настройке обработчик приложения. В случае если была отмечена настройка «Добавлять идентификатор сессии и эмитента в ссылку очистки сессии в браузере (Front channel)», то дополнительно будут переданы следующие параметры в запросе:

  • iss – идентификатор поставщика идентификации;

  • sid – идентификатор сессии пользователя.

Пример вызова ссылки для очистки сессии пользователя в браузере (Front channel):

https://app.company.com/front_channel_logout?iss=https://login.company.com/blitz&sid=4ac78c75-b99d-44dc-9304-d2599c829440

В ответ на вызов приложение должно завершить локальную сессию и вернуть ответ HTTP 200 OK. Также в ответ должны быть включены заголовки:

Cache-Control: no-cache, no-store
Pragma: no-cache

Примечание

При реализации на стороне приложения обработчика приема уведомления через веб-браузер следует учитывать особенности современных браузеров, которые противодействуют передаче cookies при вызове обработчиков в фрейме на URL-домены, отличные от URL-домена родительской страницы:

– чтобы cookie стороннего сайта могла быть переданы из фрейма, у cookie должен быть установлен флаг SameSite=None и флаг Secure, в момент установки или перезаписи cookie не должен передаваться заголовок X-Frame-Options, а сам обработчик должен быть доступен по HTTPS;

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

Для уведомления через сервер в настройках приложения в Blitz Identity Provider регистрируется обработчик «Ссылка для очистки сессии пользователя в приложении (Back channel)». Если обработчик зарегистрирован и в процессе сессии пользователь входил в приложение, то при вызове пользователем логаута сервер Blitz Identity Provider вызовет сервер приложения через HTTP POST на указанный в настройке обработчик приложения. В вызов будет передан маркер логаута logout_token, представляющий собой JWT-токен, в теле которого содержатся следующие параметры:

  • iss – идентификатор поставщика идентификации;

  • aud – идентификаторы оповещаемых приложений;

  • iat – время выпуска маркера обновления;

  • jti – идентификатор маркера логаута;

  • events – константное значение http://schemas.openid.net/event/backchannel-logout согласно спецификации OpenID Connect Back-Channel Logout 1.0;

  • sid – идентификатор сессии пользователя;

  • sub – идентификатор пользователя.

В маркере обновления присутствует либо sub (если не включена настройка «Добавлять идентификатор сессии и эмитента в ссылку очистки сессии в приложении (Back channel)», либо sid (если настройка «Добавлять идентификатор сессии и эмитента в ссылку очистки сессии в приложении (Back channel)» включена).

Пример вызова сервиса очистки сессии пользователя в приложении (Back channel):

POST /back_channel_logout HTTP/1.1
Host: app.company.com
Content-Type: application/x-www-form-urlencoded

logout_token=eyJ…J9.eyJ…J9.RV8…Nw

Пример разобранного тела маркера логаута при выключенной настройке «Добавлять идентификатор сессии и эмитента в ссылку очистки сессии в приложении (Back channel)»:

{
    "iss": "https://login.company.com/blitz",
    "aud": [
        "ais"
    ],
    "iat": 1646979918,
    "jti": "ee75ccd8-ad30-4175-9a61-3ae06c1a6730",
    "events": {
        "http://schemas.openid.net/event/backchannel-logout": {}
    },
    "sub": "3d10f626-ea77-481d-a50bd4a4d432d86b"
}

Пример разобранного тела маркера логаута при включенной настройке «Добавлять идентификатор сессии и эмитента в ссылку очистки сессии в приложении (Back channel)»:

{
    "iss": "https://login.company.com/blitz",
    "aud": [
        "ais"
    ],
    "iat": 1646979918,
    "jti": "ee75ccd8-ad30-4175-9a61-3ae06c1a6730",
    "events": {
        "http://schemas.openid.net/event/backchannel-logout": {}
    },
    "sid": "4ac78c75-b99d-44dc-9304-d2599c829440"
}

В ответ на вызов приложение должно:

  1. Проверить подпись маркера логаута по аналогии с тем, как выполняется проверка подписи маркера идентификации.

  2. Проверить, что:

  • iss соответствует идентификатору развернутой системы issuer;

  • aud включает идентификатор вызванного приложения;

  • маркер обновления выпущен (iat) не ранее 2 минут назад;

  • sid или sub соответствуют действующим сессиям пользователя.

  1. Если какие-то проверки маркера логаута неуспешны, то вернуть код HTTP 400 Bad Request.

  2. Если все проверки успешны, то завершить локальную сессию пользователя и вернуть HTTP 200 OK в случае успеха или HTTP 501 Not Implemented в случае, если сессию завершить не удалось.

    Рекомендуется включить в ответ заголовки:

Cache-Control: no-cache, no-store
Pragma: no-cache