Подтверждение операций с помощью myDSS

Раздел содержит руководство разработчика по подтверждению (отклонению) операций с помощью myDSS на примере подтверждения операции подписи. В разделе приведены основные сценарии использования, примеры HTTP-запросов и ответов REST-сервисов DSS.

Сценарии должны выполняться Пользователем DSS.

myDSS поддерживает два сценария подтверждения (отклонения) операций:

Online - мобильное устройство пользователя имеет выход в интернет. Пользователю придёт Push-уведомление о необходимости подтвердить операцию. Мобильное приложение myDSS загрузит с сервера сведения об операции (сопровождающий текст и подписываемый документ). Пользователю необходимо ознакомиться с подписываемыми данными и выразить своё согласие (отказ) на подписание документа, нажав кнопку "Подтвердить" ("Отказаться") в мобильном приложении.

Offline - мобильное устройство пользователя не имеет выхода в Интернет. В данном сценарии пользователю необходимо отобразить QR-код, содержащие сведения о подтверждаемой операции. После считавания QR-кода, пользователю в мобильном приложении отобразится код подтверждения (отмены), который необходимо будет ввести в интерфейс DSS вручную.

Внимание!

В Offline сценарии на мобильном устройстве пользователя не может быть отображён подписываемый документ. Отобразить возможно только сопровождающий операцию текст.

Последовательность шагов при подтверждение операции подписи:

1. Аутентификация пользователя на Центре Идентификации
2. Создание транзакции подписи на Сервисе Подписи
3. Подтверждение транзакции подписи на Сервисе Подтверждения Операций
4. Получение подписанного документа на Сервисе Подписи

Примечание

Подтверждение других оперций на Сервисе Подписи (создание запроса на сертификат, аннулирование сертификата, подпись пакета документов и т.п.) состоит из аналогичной последовательности шагов - отличие в типе транзакции, создаваемоей на Сервисе Подписи.

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

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

Последовательность действий при синхронном-online подтверждении

Асинхронная - пользователь ожидает оповещения о завершении транзакции на адрес CallbackUri, переданный в первом запросе на конечную точку /confirmation. После подтверждения (отклонения) транзакции на мобильном устройстве на адрес CallbackUri, придет оповещение о завершении транзакции. В случае успешного завершения транзакции пользователь должен повторно обратиться на конечную точку /confirmation для получения нового AccessToken.

Последовательность действий при асинхронном-online подтверждении

Последовательность действий при Offline подтверждении

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

Предварительные условия

• Пользователю создана учётная запись в DSS;
• Пользователю назначена аутентификация через myDSS;
• Пользователю выпущен сертификат эдектронной подписи;
• На сервере DSS зарегистрирован OAuth20 клиент.

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

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

Примечание

У Администратора DSS необходимо получить значение параметров client_id и resource. resource - идентификатор Сервиса Подписи, имеет вид: urn:cryptopro:dss:signserver:<SignServerAppName>

Примечание

Для отображения подписываемого документа в мобильном приложении на Центре Идентификации должны быть настроены плагины преобразования документов - см. раздел Отображение документов

Аутентификация пользователя на Центре Идентификации

В примере рассматривается авторизация с использованием учётных данных пользователя (логин/пароль). Подробная информация по протоколу аутентификации: The OAuth 2.0 Authorization Framework

Параметры запроса:

• grant_type - тип разрешения, в данном сценарии равен password.
• password – пароль пользователя.
• resource – идентификатор Сервиса Подписи.

В заголовке Authorization HTTP-запроса клиент должен передать идентификатор OAuth-клиента и секрет (если используется): Authorization: Basic Base64(<client_id>:<secret>)

Примечание

В примере значение параметр password оставлено пустым, так как пользователю в качестве первичной аутентификации назначен метод "Только Идентификация"

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

POST https://host/STS/oauth/token HTTP/1.1
Authorization: Basic dGVzdENsaWVudDo=
Content-Type: application/x-www-form-urlencoded
Host: host
Content-Length: 101
Expect: 100-continue
Connection: Keep-Alive

grant_type=password&username=mydss&password=&resource=urn%3Acryptopro%3Adss%3Asignserver%3Asignserver

В случае успешной аутентификации ответ будет содержать:

• access_token - AccessToken, выпущенный Центром Идентификации DSS
• token_type - Тип токена
• expires_in - Время жизни токена в секундах

Значение параметра access_token необходимо будет использовать при обращениях к Сервису Подписи и Сервису Подтверждения Операций.

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

HTTP/1.1 200 OK
Cache-Control: no-cache
Pragma: no-cache
Content-Length: 2017
Content-Type: application/json; charset=utf-8
Expires: -1

{
    "access_token":"eyJ0eXAiOiJKV ... 5Wti-H8CeXycwB6A",
    "expires_in":300,
    "token_type":"Bearer"
}

Типовые ошибки

HTTP-код	Ошибка	Описание
400	invalid_client	OAuth-клиент не зарегистрирован или неверно указан ClientID
400	unauthorized_client	OAuth-клиент использует незарегистрированный сценарий аутентификации (Flow)
400	invalid_request	Неверно сформирован параметр resource
500	An error has occurred	Проверяющая сторона с идентификатором resource не зарегистрирована.

Создание транзакции подписи на Сервисе Подписи

После прохождения аутентификации пользователь инициирует подписание документа. Для подтверждения любых операций на Сервисе Подписи используется метод /transactions В запросе необходимо указать:

• OperationCode - тип создаваемой транзакции.
• Parameters - параметры тразнакции.
• Document - подписываемый документ.

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

Идентификатор сертификата подписи CertificateID можно получить запросив список сертификатов пользователя, обратившись на конечную точку \certificates

Параметры создания транзакций других типов приведены здесь

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

В примере создаётся прикреплённая CAdES-BES подпись.

POST https://host/SignServer/rest/api/transactions HTTP/1.1
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJh ... 8CeXycwB6A
Content-Type: application/json; charset=utf-8
Host: host
Content-Length: 355049
Expect: 100-continue

{
"OperationCode":2,
"Parameters":
    [
        {"Name":"SignatureType","Value":"CMS"},
        {"Name":"CertificateID","Value":"13"},
        {"Name":"DocumentInfo","Value":"testPdf.pdf"},
        {"Name":"DocumentType","Value":"pdf"},
        {"Name":"IsDetached","Value":"false"},
        {"Name":"CADESType","Value":"BES"}
    ],
"Document":"JVBERi0xLjUNCiW1tbW14Kfu ...."
}

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

Сервис Подписи вернёт идентификатор созданной транзакции. Далее пользователю требуется подтвердить транзакцию на Сервисе Подтверждения Операций.

HTTP/1.1 200 OK
Content-Length: 38
Content-Type: application/json; charset=utf-8
Server: Microsoft-IIS/7.5

"d5ebd393-e093-4aa8-bdcf-f5e497dc6b4d"

Типовые ошибки

HTTP-код	Ошибка	Описание
400	invalid_certificate	Неверный идентификатор сертификата
400	invalid_request	Неверно указаны параметры подписи

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

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

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

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

Параметр CallbackUri - опциональный, используется в асинхронном сценарии подтверждения транзакции.

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

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",
    "ClientId":"oauth-client-id",
    "ClientSecret":"oauth-client-secret",
    "TransactionTokenId":"d5ebd393-e093-4aa8-bdcf-f5e497dc6b4d",
    "CallbackUri":"http://clienthost/callback/"
}

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

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

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

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

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

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

В поле TextChallenge содержится:

Поле	Описание
Image	QR-код для Offline подтверждения операции
RefID	Идентификатор транзакции, созданной на Сервисе Подтверждения Операций
ExpiresIn	Срок действия транзакции, созданной на Сервисе Подтверждения Операций
AuthnMethod	Идентификатор метода используемый для подтверждения транзакции

Примечание

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

Примечание

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

HTTP/1.1 200 OK
Cache-Control: no-cache
Pragma: no-cache
Content-Length: 6736
Content-Type: application/json; charset=utf-8
Expires: -1

{
    "Challenge":
    {
        "Title":
        {
            "Value":"Подтвердите операцию на устройстве с помощью приложения."
        },
        "TextChallenge":
        [
            {
                "Image":
                {
                    "MimeType":"image/gif",
                    "Value":"R0lGODlhLAEsAfcAAAAAAAAAMw ... AAZiO77kW77me77om77qGxcBAQA7"
                },
                "AuthnMethod":"http://dss.cryptopro.ru/identity/authenticationmethod/mobile",
                "RefID":"e7207ff7-5456-4943-bebf-a7cc624aadaa"
                "ExpiresIn":300,
                "ExpiresInSpecified":true
            }
        ],
        "ContextData":
        {"RefID":"e7207ff7-5456-4943-bebf-a7cc624aadaa"}
    },
    "IsFinal":false,
    "IsError":false}

Дальнейшее взаимодействие с Сервисом Подтверждения Операций зависит от выбранного сценария:

• синхронный
• асинхронный
• Offline

Асинхронное подтверждение транзакции

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

Сообщение о завершении транзакции содержит:

• Result - результат подтверждения транзакции (success или failed)
• TransactionId - идентификатор транзакции на Сервисе Подтверждения операций (RefId)
• Error - код ошибки
• ErrorDescription - описание ошибки

Примеры ответа на CallbackUri

Оповещение о подтверждении операции:

{
    "Result":"success",
    "TransactionId":"aa1a4a5d-bb4d-456b-87da-31818604fcd8",
    "Error":"",
    "ErrorDescription":null}

Оповещение об отказе (пользователь в мобильном приложении Отказался от подтверждения операции):

{
    "Result":"failed",
    "TransactionId":"2fbd0a40-77be-4a40-a688-a0249bba16a6",
    "Error":null,
    "ErrorDescription":null}

Оповещение об истечении строка действия транзакции.

{
"Result":"failed",
"TransactionId":"bc0ffdee-7143-439f-bf6b-d1400725d8f1",
"Error":"transaction_expired",
"ErrorDescription":"Срок действия транзакции истёк"}

Если пользователь подтвердил операцию на мобильном устройстве, необходимо обратиться на Сервис Подтверждения Операций для получения нового AccessToken. В запросе передаётся идентификатор RefId.

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

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

{
    "Resource" : "urn:cryptopro:dss:signserver:SignServer",
    "ClientId":"oauth-client-id",
    "ClientSecret":"oauth-client-secret",
    "ChallengeResponse":
    {
        "TextChallengeResponse":
        [{"RefId":"e7207ff7-5456-4943-bebf-a7cc624aadaa"}]
    }
}

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

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

HTTP/1.1 200 OK
Cache-Control: no-cache
Pragma: no-cache
Content-Length: 2215
Content-Type: application/json; charset=utf-8
Expires: -1

{
    "AccessToken":"eyJ0eXAiOiJKV1QiL ... YF3oFlBxXsK7iCkM81jQIwoldWtB5_Gw",
    "ExpiresIn":600,
    "IsFinal":true,
    "IsError":false
}

Типовые ошибки

HTTP-код	Ошибка	Описание
400	invalid_transaction	1. Срок действия транзакции истёк 2. Передан неверный идентификатор транзакции (RefId)
400	transaction_pending	У пользователя есть неподтвержденная транзакция.

Синхронное подтверждение транзакции

В синхронном режиме пользователь должен периодически опрашивать Сервис Подтверждения Операция, ожидая завершение подтверждения транзакции (флаг IsFinal = true).

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

POST https://host/STS/confirmation HTTP/1.1
Authorization: Bearer eyJ0eXAiOiJKV1 ... mXqvC5_3W244A
Content-Type: application/json; charset=utf-8
Host: host
Content-Length: 212
Expect: 100-continue

{
    "Resource" : "urn:cryptopro:dss:signserver:SignServer",
    "ClientId":"oauth-client-id",
    "ClientSecret":"oauth-client-secret",
    "ChallengeResponse":
    {
        "TextChallengeResponse":
        [{"RefId":"de34f120-55d5-4f3e-8e7a-b15c1444d747"}]}
    }
}

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

Если подтверждение не завершено, то IsFinal - false

HTTP/1.1 200 OK
Cache-Control: no-cache
Pragma: no-cache
Content-Length: 352
Content-Type: application/json; charset=utf-8
Expires: -1

{
"Challenge":
{
    "Title":{"Value":""},
    "TextChallenge":
    [{
        "AuthnMethod":"http://dss.cryptopro.ru/identity/authenticationmethod/mobile",
        "RefID":"de34f120-55d5-4f3e-8e7a-b15c1444d747"
    }],
"ContextData":{"RefID":"de34f120-55d5-4f3e-8e7a-b15c1444d747"}},
"IsFinal":false,
"IsError":false
}

Если в ответе IsFinal - true, то Сервис вернул новый AccessToken.

HTTP/1.1 200 OK
Cache-Control: no-cache
Pragma: no-cache
Content-Length: 2215
Content-Type: application/json; charset=utf-8
Expires: -1

{
"AccessToken":"eyJ0eXAiOiJKV1QiLC ... 5b1T6H1ytuWztMPGfz-Ow",
"ExpiresIn":600,
"IsFinal":true,
"IsError":false
}

Типовые ошибки

HTTP-код	Ошибка	Описание
400	invalid_transaction	1. Срок действия транзакции истёк 2. Передан неверный идентификатор транзакции (RefId)

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

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

Интегрируемая система должна отобразить пользователю QR-код (Image), полученный при первом обращении к Сервису Подтверждения Операций, и предоставить пользователю интерфейс для ручного ввода кода подтверждения (отказа) транзакции.

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

POST https://host/STS/confirmation HTTP/1.1
Authorization: Bearer eyJ0eXAiOiJKV1Q ... mlfrpmS79Xto3KEQ
Content-Type: application/json; charset=utf-8
Host: host
Content-Length: 229
Expect: 100-continue

{
    "Resource" : "urn:cryptopro:dss:signserver:SignServer",
    "ClientId":"oauth-client-id",
    "ClientSecret":"oauth-client-secret",
    "ChallengeResponse":
    {
        "TextChallengeResponse":
            [{
                "RefId":"ca6d568a-e81c-4a43-a3a2-65841f7213e3",
                "Value":"12..56"}
            ]}
    }
}

Длина кода подтверждения (отмены) настраивается Администратором на сервере DSS. Минимальная длина кода подтверждения (отмены) - 6 цифр.

Set-DssMobileAuthProperties -ConfirmationCodeLength 8

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

Если в ответе `IsFinal' - true, то Сервис вернул новый AccessToken.

HTTP/1.1 200 OK
Cache-Control: no-cache
Pragma: no-cache
Content-Length: 2215
Content-Type: application/json; charset=utf-8
Expires: -1

{
"AccessToken":"eyJ0eXAiOiJKV1QiLC ... 5b1T6H1ytuWztMPGfz-Ow",
"ExpiresIn":600,
"IsFinal":true,
"IsError":false
}

Типовые ошибки

HTTP-код	Ошибка	Описание
400	invalid_transaction	1. Срок действия транзакции истёк 2. Передан неверный идентификатор транзакции (RefId)
400	authentication_failed	Передан неверный код подтверждения (отмены)

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

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

Примечание

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

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

POST https://host/SignServer/rest/api/documents HTTP/1.1
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciCkM81 ... jQIwoldWtB5_Gw
Content-Type: application/json; charset=utf-8
Host: host
Content-Length: 2
Expect: 100-continue

{}

Примечание

Если закрытый ключ сертификата защищён на ПИН-коде, то ПИН-код должен быть указан при обращении на конечную точку /documents

Пример запроса с указанием ПИН-кода:

POST https://host/SignServer/rest/api/documents HTTP/1.1
Authorization: Bearer eyJ0eXAiOiJKV1 ... xBT_myemDbgJoQ
Content-Type: application/json; charset=utf-8
Host: host
Content-Length: 97
Expect: 100-continue

{"Signature":{"PinCode":"1234"}}

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

HTTP/1.1 200 OK
Content-Length: 356734
Content-Type: application/json; charset=utf-8
Server: Microsoft-IIS/7.5

"MIMEFRcG ... gkRSA

Типовые ошибки

HTTP-код	Ошибка	Описание
400	invalid_pin	Неверно указан ПИН-код на закрытый ключ