Подтверждение произвольных операций | КриптоПро DSS

Aутентификация и подтверждение операций | криптопро dss

Oauth 2.0

В протоколе OAuth 2.0 область использования маркера указывается в authorize
запросе в параметре scope, а подстановочные значения в параметре dss_scope_params.

Пример

Ws-trust

Для передачи области использования в запросе на выпуск маркера используется
расширение протокола WS-Trust AdditionalContext, описание которого содержится
в спецификации WS-Federation:

Завершение подтверждения операции

После подтверждения операции в мобильном приложении требуется завершить подтвреждение,
отправив запрос:

Запрос

Загрузка документа в сод

Бинарные данные для произвольной операции загружаются в СОД.
Для аутентификации использует access_token, полученный на
предыдущем шаге.

Запрос

Запоминание подтверждения

Существует возможность запомнить факт подтверждения операции после первого
успешного прохождения процедуры вторичной аутентификации. Для этого в свойствах
подтверждаемой области использования необходимо выставить свойство
RememberConsent в значение true с помощью команды:

Set-DssScope -ScopeName RememberConsentScope -RememberConsent true

здесь

• RememberConsentScope — название области использования, для которой меняется настройка.

После применения настройка факт первого успешного подтверждения будет
автоматически запомнен.

Области использования маркера

Результатом подтверждения любой операции в ЦИ является маркер безопасности
(токен). Для того чтобы указать, как будет применяться выпущенный маркер,
используют т.н. области использования маркера (scope). Область
использования маркера показывает для каких целей можно использовать выпущенный
маркер. Однако следует понимать, что контроль за областью использования ложится
на проверяющую сторону.

Ограничения областей использования

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

Для того чтобы задать способ список допустимых областей использования,
необходимо выполнить следующую PowerShell команду:

Set-DssClient -ClientId ScopeRestrictedClientId -AllowedScopes scope1,scope2

здесь

• ScopeRestrictedClientId — идентификатор OAuth-клиента, для которого
  настраивается ограничение;
• scope1,scope2 — идентификаторы областей использования, разрешённые для
  для данного OAuth-клиента.

Отмена операции

Для отмены существующей операции необходимо передавать идентификатор области
использования, идентификатор операции и значение «Cancel» для действия управления состоянием операции.

Пример

Пример

Отправка запроса на создание операции подтверждения

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

Запрос

Первичная аутентификация

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

Запрос

Передача бинарных данных

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

Для передачи бинарных данных необходимо расширить запрос на выпуск маркера
параметрами ConfirmationData и ConfirmationDataType.
В первом параметр передаётся содержимое бинарных данных транзакции в BASE64,
во втором тип бинарных данных. На основе типа данных ЦИ выполнит преобразование
в DTBS.

Пример

В состав DSS входит плагин для преобразования бинарных данных в DTBS. Этот
плагин осущевляет преобразование 1 к 1. На вход такому плагину в качестве
бинарных данных следует передавать массив байтов, представляющий XML в
кодировке UTF8:

Подтверждение операций в версии api 2.0

Версия API 2.0 позволяет подтверждать операции с несколькими бинарными данными,
предварительно загруженными в Сервис Обработки Документов КриптоПро DSS
(далее СОД).

Для этого в запрос на создание операции добавляется параметр
ConfirmationDataRefs, значение которого представляет собой массив
идентификаторов документов в СОД:

Полчение информации о подтверждённых действиях

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

Запрос

Примечание

Параметры ConfirmationDataRefs и ConfirmationData (вместе с
ConfirmationDataType) являются взаимоисключающими.

Разрешение на выполнение действий

С помощью одновременного применения ограничения на допустимые области
использования маркера и запоминания факта подтверждения можно организовать
сценарий взаимодействия с DSS, при котором у пользователя однократно будет
запрошено разрешение на выполнение какого-то действия для конкретного OAuth-
клиента. Далее этого сценарий будет рассмотрен подробнее.

Допустим, что существует некоторое веб-приложение DemoBank, вход в которое
осуществляется через КриптоПро DSS. Есть требование запрашивать перед первым
использованием приложения разрешение у пользователя на доступ к учётной записи
ЦИ КриптоПро DSS.

Для решения данной задачи администратор DSS создает новую область использования
dss-access с шаблоном «Доступ к учётной записи КриптоПро DSS». Для данной
области использования включается требование двухфакторной аутентификации при
подтверждении и возможность сохранения факта подтверждения:

Add-DssScope -ScopeName "dss-access" -RequireConfirmation true -RememberConsent true -DisplayName "Доступ к учётной записи КриптоПро DSS"

Далее для OAuth-клиента DemoBank включается требование подтверждения области
использования и список допустимых областей:

Set-DssClient -ClientId DemoBank -RequireConsent 1 -AllowedScopes "dss-access"

После применения настроек любой запрос на получения маркера доступа без
указания параметра scope или с указанием значения, отличного от
dss-access приведёт к ошибке invalid_scope. При этом запрос с указанием
dss-access приведёт к ошибке consent_required, означающей, что не было
получено разрешение пользователя на область использования dss-access для
OAuth-клиента DemoBank.

Для получения разрешения необходимо отправить следующий запрос на конечную
точку /confirmation:

Запрос

Строгое подтверждение

Для подтверждения произвольных операций через конечную точку
StrictConfirmation необходимо передавать идентификатор области
использования и параметры шаблона сообщения в запросе RequestConfirmation.

Пример

Управление областями использования маркера

Для управления областями использования маркера администратору предоставляются
следующие PowerShell команды:

• Add-DssScope — для добавления области использования маркера.
• Set-DssScope — для изменения параметров уже добавленной области использования.
• Remove-DssScope — для удаления области использования.

Форматы запросов

DSS предоставляет три возможности для передачи области использования маркера
в зависимости от применяемого протокола:

• Передача в запросе на маркер безопасности (Request Security Token) для WS-Trust.
• Передача в запросе на авторизацию OAuth 2.0.
• Передача в запросе на подтверждение операции.

Рассмотрим каждый из трёх способов в отдельности.

Шаблоны подтверждения

Каждой области использования маркера в DSS соответствует некоторый шаблон
сообщения, используемый для отображения информации о действии пользователю.
Шаблоны сообщений могут быть заданы для всех способов аутентификации
(в терминологии системы оповещений DSS различным способам аутентификации
соответствуют различные типы назначений — destination, а также
различные типы получателей сообщений — recipient).

На данный момент в DSS существуют следующие типы назначений:

• SMS — соответствует способу аутентификации Otp-via-Sms.
• Email — соответствует способу аутентификации Otp-via-Email.
• MobileAuth — соответствует способу аутентификации через мобильное приложение myDSS.
• MyDssAuth — соответствует способу аутентификации через DSS Client SDK.
• SimAuth — соответствует способу аутентификации с помощью апплета на SIM карте.
• Audit — данный тип назначения используется для записи сообщения в журнал аудита
• Challenge — данный тип используется для форматирования сообщения, отображаемого пользователю в интерфейсе.

Типы получателей