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

Данный раздел содержит руководство разработчика по подтверждению операций на Сервисе Подписи. В разделе приведен общий подход при подтверждении операций.

В подтверждении операций задействованы следующие сервисы DSS:

Конечная точка	Сервис	Описание
https://<host>/<StsAppName>/oauth	Сервис Аутентификации.	Аутентификация пользователей для возможности обращений к Сервису Подписи
https://<host>/<SignServerAppName>/rest/api	Сервис Подписи	Создание транзакций и получение результатов, подтвержденной операции
https://<host>/<StsAppName>/confirmation	Сервис Подтверждения Операций	Подтверждение транзакций

Подтверждены вторым фактором аутентификации могут быть операции требующие доступа к закрытому ключу. Список подтверждаемых операций - Коды операций

Последовательность шагов:

• Аутентификация пользователя
• Получение политики Сервиса Подписи (опционально)
• Создание транзакции на Сервисе Подписи
• Подтверждение транзакции на Сервисе Подтверждения Операций
• Получение результата операции на Сервисе Подписи

Получение Политики Сервиса Подписи

Для получения Политики Сервиса Подписи необходимо обратиться на конечную точку /policy.

Из Политики Сервиса Подписи можно получить:

• Список операций, требующих подтверждения
• Параметры создания запроса на сертификат

Список операций доступных пользователю содержится в структуре ActionPolicy. Элементами списка являются объекты вида:

Поле	Тип	Описание
DisplayName	string	Отображаемое имя операции
Uri	string	Идентификатор операции
Action	string	Имя операции
MfaRequired	bool	Требование подтверждения операции

Список имён операций приведён в разделе Коды операций

Примечание

Любую операцию на Сервисе Подписи можно выполнить с подтверждением вторым фактором аутентификации, даже если для данной операции не выставлено требование подтверждения.

Пример ActionPolicy

"ActionPolicy": [{
            "DisplayName": "Выпуск маркера (вход в ЦИ)",
            "Uri": "http://dss.cryptopro.ru/identity/claims/action/issue",
            "Action": "Issue",
            "MfaRequired": false
        }, {
            "DisplayName": "Подпись документа",
            "Uri": "http://dss.cryptopro.ru/identity/claims/action/signdocument",
            "Action": "SignDocument",
            "MfaRequired": false
        }, {
            "DisplayName": "Подпись пакета документов",
            "Uri": "http://dss.cryptopro.ru/identity/claims/action/signdocuments",
            "Action": "SignDocuments",
            "MfaRequired": false
        }, {
            "DisplayName": "Расшифрование документа",
            "Uri": "http://dss.cryptopro.ru/identity/claims/action/decryptdocument",
            "Action": "DecryptDocument",
            "MfaRequired": false
        }, {
            "DisplayName": "Создание запроса на сертификат",
            "Uri": "http://dss.cryptopro.ru/identity/claims/action/createrequest",
            "Action": "CreateRequest",
            "MfaRequired": false
        }, {
            "DisplayName": "Смена пин-кода закрытого ключа",
            "Uri": "http://dss.cryptopro.ru/identity/claims/action/changepin",
            "Action": "ChangePin",
            "MfaRequired": false
        }, {
            "DisplayName": "Обновление сертификата",
            "Uri": "http://dss.cryptopro.ru/identity/claims/action/renewcertificate",
            "Action": "RenewCertificate",
            "MfaRequired": false
        }, {
            "DisplayName": "Отзыв сертификата",
            "Uri": "http://dss.cryptopro.ru/identity/claims/action/revokecertificate",
            "Action": "RevokeCertificate",
            "MfaRequired": false
        }, {
            "DisplayName": "Приостановление действия сертификата",
            "Uri": "http://dss.cryptopro.ru/identity/claims/action/holdcertificate",
            "Action": "HoldCertificate",
            "MfaRequired": false
        }, {
            "DisplayName": "Возобновление действия сертификата",
            "Uri": "http://dss.cryptopro.ru/identity/claims/action/unholdcertificate",
            "Action": "UnholdCertificate",
            "MfaRequired": false
        }, {
            "DisplayName": "Удаление сертификата",
            "Uri": "http://dss.cryptopro.ru/identity/claims/action/deletecertificate",
            "Action": "DeleteCertificate",
            "MfaRequired": false
        }, {
            "DisplayName": "Доступ к закрытому ключу",
            "Uri": "http://dss.cryptopro.ru/identity/claims/action/privatekeyaccess",
            "Action": "PrivateKeyAccess",
            "MfaRequired": false
        }
    ]

Создание транзакции

Для создания транзакции необходимо обратиться на конечную точку /transactions.

Список параметров необходимый при создании транзакций приведён в разделе Параметры транзакций.

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

Подтверждение транзакции

Для начала подтверждения транзакции необходимо отправить запрос на конечную точку /confirmation.

Для подтверждения транзакции, созданной на Сервисе Подписи, пользователь отправляет запрос содержащий:

• CallbackUri - адрес для оповещения о завершении транзакции (опционально).
• TransactionTokenId – идентификатор транзакции, созданной на Cервисе Подписи.
• Resource – идентификатор Сервиса Подписи.

В заголовке Authorization HTTP-запроса клиент должен указать токен полученный на первом шаге: Authorization: Bearer <access_token>.

Примеры запроса

POST https://host/STS/confirmation HTTP/1.1
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJHM ... 5aPB98A3NAVduJbtz5Wti-H8CeXycwB6A
Content-Type: application/json; charset=utf-8
Host: host
Content-Length: 246
Expect: 100-continue

{
    "Resource":"urn:cryptopro:dss:signserver:signserver",
    "TransactionTokenId":"d5ebd393-e093-4aa8-bdcf-f5e497dc6b4d",
    "CallbackUri":"http://clienthost/callback/"
}

При получении запроса Сервис Подтверждения Операций начнёт процедуру подтверждения операции. Например, пользователю будте отправлено SMS с одноразовым паролем или придёт Push-уведомление на мобильное устройство.

Пример ответа

Ответ Сервиса Подтверждения Операций содержит:

Поле	Описание
Challenge	Запрос на выполнение аутентификационного испытания
AccessToken	Маркер доступа. Заполняется при IsFinal - true
ExpiresIn	Время жизни AcessToken в секундах. Заполняется при IsFinal - true
IsFinal	Является ли данный ответ последним в процессе подтверждения.
IsError	Содержит ли данный ответ ошибку обработки запроса. Заполняется при IsFinal - false
Error	Ошибка обработки запроса. Заполняется при IsFinal - false
ErrorDescription	Подробное описание ошибки обработки запроса

Поле Challenge содержит:

Поле	Описание
Title	Текст, который вызывающая система может отобразить пользователю в своём интерфейсе
TextChallenge	Дополнительные данные для подтверждения операции

Содержимое поля TextChallenge зависит от метода подтверждения (OTP-via-SMS, myDSS, и т.д.)

Примечание

RefId - Идентификатор транзакции, созданной на Сервисе Подтверждения Операций. Идентификатор необходимо будет использовать при последующих обращениях на конечную точку /confirmation.

Примечание

При обработке ответа Сервиса Подтверждения Операций вызывающее приложение должно смотреть на значение двух флагов: IsFinal и IsError.
Если получен ответ с IsError - true, то дальнейшее подтверждение транзакции не возможно.
Если получен ответ с IsFinal - false, то подтверждение транзакции ещё не завершено.

Дальнейшие действия пользователя зависят от метода подтверждения (OTP-via-SMS, myDSS, и т.д.)

Пример подтверждения операции через мобильное приложение myDSS смотреть здесь

Результатом подтверждения транзакции на Сервисе Подтверждения Операций является AccessToken, содержащий идентификатор подтверждённой транзакции.

Получение результата

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

В заголовке Authorization HTTP-запроса клиент должен указать токен полученный на шаге "Подтверждение транзакции" Authorization: Bearer <access_token2>.

Примеры запроса

Тип транзакции	Код транзакции	Метод
SignDocument	2	/documents
SignDocuments	4	/documents/packagesignature
DecryptDocument	8
CreateRequest	16	/request
ChangePin	32
RenewCertificate	64
RevokeCertificate	128
HoldCertificate	256
UnholdCertificate	512
DeleteCertificate	1024

Примечание

Методы вызываются без параметров. Исключение составляют методы требующие ввода ПИН-код: подпись документа, подпись пакета документов.