Как правильно зарегистрировать приложение#

Аутентификация в терминологии OIDC/OAuth 2.0 является результатом взаимодействия трех сторон:

  • сервиса авторизации (Authorization Server) или поставщика ресурса (Resource Server), в качестве которых выступает Blitz Identity Provider;

  • системы-клиента (Client), в качестве которой выступает приложение, которое запрашивает доступ ресурсу (информации и данным пользователя);

  • владельца ресурса (Resource Owner), в качестве которого выступает пользователь, так как в ходе аутентификации он разрешает доступ к данным о себе.

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

  • идентификатор приложения (client_id);

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

  • разрешенные адреса возврата (списки redirect_uri и post_logout_redirect_uri);

  • перечень запрашиваемых разрешений (список scope);

  • информация о нестандартных режимах, необходимых приложению:

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

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

    • приложению нужно получать маркер доступа в формате JWT – по умолчанию маркер доступа предоставляется в формате opaque;

    • приложению нужно получать маркер доступа (access_token) с нестандартным сроком действия – стандартно маркер доступа действует 1 час;

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

  • режим входа (вход как физического лица или как представителя организации).

  • идентификатор мобильного приложения (software_id);

  • первичный маркер доступа (Initial Access Token);

  • метаданные приложения в форме JWS-токена (software_statement).

  • разрешенные адреса возврата (списки redirect_uri и post_logout_redirect_uri);

  • перечень запрашиваемых разрешений (список scope);

  • нестандартные режимы, необходимые приложению:

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

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

    • приложению нужно получать маркер доступа в формате JWT – по умолчанию маркер доступа предоставляется в формате opaque;

    • приложению нужно получать маркер доступа (access_token) с нестандартным сроком действия – стандартно маркер доступа действует 1 час;

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

  • режим входа (вход как физического лица или как представителя организации).

Примечание

При разработке мобильного приложения можно использовать как общие Initial Access Token и software_statement для своих iOS/Android-реализаций, так и запросить получение различных наборов Initial Access Token и software_statement для каждой ОС и, возможно, каждой редакции (телефон/планшет) и даже версии приложения. Для простоты дальнейшего изложения в тексте документа будет подразумеваться, что мобильное приложение использует один общий Initial Access Token и один общий software_statement.

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

  • пользователям мобильных приложений неудобно вводить при каждом входе логин и пароль на веб-странице аутентификации Blitz Identity Provider. Вместо этого им привычнее при повторных входах использовать ПИН-код приложения или Touch ID/Face ID;

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

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

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

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

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

Как определить адреса возврата

Запрос на проведение идентификации/аутентификации пользователя содержит ссылку возврата при авторизации (redirect_uri), куда должен быть возвращен пользователь после прохождения идентификации/аутентификации. Допустимые ссылки возврата должны соответствовать зарегистрированным в Blitz Identity Provider разрешенным префиксам.

Если в запросе на идентификацию/аутентификацию указана ссылка возврата, и она не соответствует ни одному из указанных префиксов, то в идентификации/аутентификации будет отказано.

В зависимости от типа подключаемого приложения рекомендуется использовать следующие префиксы ссылок возврата:

  • При подключении веб-приложений в качестве префиксов ссылок возврата использовать доменные имена приложений. Например, если после проведения аутентификации требуется вернуть пользователя на https://domain.com/callback, то в качестве префикса ссылки возврата следует указать https://domain.com/.

    Предупреждение

    При подключении к продуктивной среде Blitz Identity Provider веб‑приложение должно использовать в качестве redirect_uri и post_logout_redirect_uri только HTTPS-обработчики. Использование HTTP для взаимодействия с продуктивной средой Blitz Identity Provider запрещено.

  • При подключении мобильных приложений в качестве префиксов ссылок возврата рекомендуется указать сами ссылки возврата одного из типов: ссылки типа private‑use URI scheme» (например, com.example.app:/oauth2redirect/example‑provider) или ссылки типа Universal links (например, https://app.example.com/oauth2redirect/example-provider).

    Примечание

    Ссылки типа Universal links доступны начиная с iOS 9 и Android 6.0 и являются предпочтительными для использования. Ссылки private-use URI scheme рекомендуется использовать только в случае, если приложение должно работать на более ранних версиях iOS/Android.

Запрос на проведение логаута содержит ссылку возврата при логауте (post_logout_redirect_uri). Эта ссылка указывает, куда должен быть возвращен пользователь после успешно выполненного логаута. Допустимые ссылки возврата должны соответствовать зарегистрированным в Blitz Identity Provider разрешенным префиксам (префикс должен содержать доменное имя приложения и часть пути, минимум, https://domain.com/). Если в запросе на логаут указана ссылка возврата, и она не соответствует ни одному из указанных префиксов, то будет отображена ошибка.

Какие разрешения можно запросить

Разрешения (scope в терминологии OIDC/OAuth 2.0) определяют, какие данные и какие именно права на выполнение каких операций получит приложение по результатам аутентификации.

Перечень предусмотренных в Blitz Identity Provider разрешений представлен в таблице.

Доступные разрешения (scope)

Разрешение

Описание

Состав получаемых атрибутов

openid

Техническое разрешение, указывающее на то, что аутентификация проводится согласно спецификации OIDC

При запросе этого scope Blitz Identity Provider предоставляет приложению id_token. Из id_token приложение может получить нужные ему атрибуты пользователя.

profile

Основные данные профиля пользователя

Список данных:

  • sub– уникальный идентификатор

  • family_name – фамилия

  • given_name – имя

  • middle_name – отчество

  • email – служебный адрес электронной почты

  • phone_number – номер мобильного телефона

usr_grps

Получение списка групп пользователя

groups – список групп, в которые включен пользователь.

Каждая запись в списке включает следующие атрибуты организации:

  • id – идентификатор группы

  • name – имя группы

native

Разрешение на выполнение сквозного входа в веб-приложение из мобильного приложения

Актуально только для мобильных приложений.
Какие дополнительные атрибуты можно включить в id_token

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

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

Возможные дополнительные атрибуты пользователя в id_token

Атрибут

Описание

family_name

Фамилия

given_name

Имя

middle_name

Отчество

email

Адрес электронной почты

phone_number

Мобильный телефон

Следующие атрибуты заполняются только в том случае, если пользователь вошел в Blitz Identity Provider через ЕСИА в качестве сотрудника организации.

org_id

Идентификатор организации в Blitz Identity Provider

global_role

Выбранная роль при входе через ЕСИА:

  • P – физическое лицо

  • B – индивидуальный предприниматель

  • L – сотрудник юридического лица

  • A – сотрудник органа государственной власти

org_shortname

ОГРН организации (по сведениям из учетной записи ЕСИА)

org_fullname

ОГРН организации (по сведениям из учетной записи ЕСИА)

org_ogrn

ОГРН организации (по сведениям из учетной записи ЕСИА)

org_inn

ИНН организации (по сведениям из учетной записи ЕСИА). При аутентификации юридического лица с помощью электронной подписи ИНН организации передается в формате 00 + 10 цифр ИНН юридического лица, при аутентификации юридического лица с помощью учетной записи ЕСИА - в формате 10 цифр ИНН юридического лица.

Совет

Blitz Identity Provider также позволяет поместить элементы дизайна приложения на страницу входа Blitz Identity Provider. При желании создать для подключаемой системы персонифицированную страницу входа нужно адаптировать шаблон оформления страницы входа под дизайн подключаемой системы. Шаблон оформления страницы входа представляет собой zip-архив, внутри которого записаны HTML каркаса страницы входа и используемые на странице таблица стилей, изображения, JavaScript обработчики.

Подготовленный архив темы страницы входа нужно загрузить в Blitz Identity Provider.