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

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

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

Пререквизиты

• Зарегистрированный OAuth-клиент для интегрируемой системы

Примечание

Рекомендуем использовать сервисный OAuth-клиент

• Пользователю создана учетная запись в Центре Идентификации
• Пользователю выпущен сертификат подписи

Примечание

Последовательность действий по созданию УЗ пользователя приведена в разделе Подключение метода аутентификации через DSS SDK

• На Сервисе Обработки Документов (СОД) зарегистрированы плагины для отображения документов.

Общие сведения

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

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

Примечание

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

Все запросы к Сервису Подписи и Сервису Обработки Документов должны быть аутентифицированы с помощью 'access_token'. 'access_token' передаётся в заголовке Authorization с типом Bearer. 'access_token' выдаёт Центр Идентификации после успешной аутентификации пользователя. Сценарии аутентификации пользователя приведены в разделе Аутентификация

Подпись может быть выполнена в

• синхронном режиме
• асинхронном режиме.

Режимы отличаются этапом, на котором интегрируемая система получит callback о подтверждении операции.

Примечание

Синхронный режим сохранён для обратной совместимости с предыдущими версиями КриптоПро DSS (2.0.2882 и ранее).

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

• выгрузить из Сервиса Обработки Документов подписанный документ

Примечание

В случае ошибок подтверждения операции, отклонения операции вызывающая система получит callback от Центра Идентификации.

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

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

• получить 'access_token' в Центре Идентификации, содержащий сведения о подтверждённой операции
• с полученным 'access_token' запросить подпись документа на Сервисе Подписи

• выгрузить из Сервиса Обработки Документов подписанный документ

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

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

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

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

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

Конечная точка	Сервис	Описание
https://<host>/<StsAppName>/oauth	Сервис Аутентификации	Аутентификация пользователей для возможности обращений к сервисам: * Сервису Подписи * Сервису Обработки Документов * Сервису Подтверждения Операций
https://<host>/<DocStoreAppName>/	Сервис Преобразования документов	Загрузка документов для подписания и получение подписанных документов
https://<host>/<SignServerAppName>/rest/api/v2/signature/	Сервис Подписи	Создание операции и получение результатов, подтвержденной операции
https://<host>/<StsAppName>/v2.0/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-клиент не зарегистрирован или неверно указан clienID
400	unauthorized_client	OAuth-клиент использует незарегистрированный сценарий аутентификации (Flow)
400	invalid_request	Неверно сформирован параметр resource
500	An error has occurred	1. Проверяющая сторона с идентификатором resource не зарегистрирована.

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

Описание API Сервиса Преобразования документов - Сервис Преобразования документов

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

• хэш от документа (ГОСТ Р 34.11-2012)
• Выжимка из документа
• Печатное представление документа
• PDF-представление документа

Документ загружается на сервер в поточном режиме. После загрузки сервис вернёт ID загруженного документа. Идентификатор загруженного документа необходимо будет передать в Сервис Подписи при создании операции подписи.

Выжимка из документа и PDF-представление документа являются обязательными атрибутами документа при подтвержении операции подписи через DSS SDK. PDF-представление документа всегда формируется сервисом. Выжимка из документа может быть сформирована как сервисом так и передана из вызывающей системы PostDocumentInput в параметре AdditionalInfo в ключе SnippetTemplate.

Печатное представление документа может быть сформировано как сервисом так и передано из вызывающей системы PostDocumentInput в параметре AdditionalInfo в ключе DocumentTemplate.

Содержимое документа передается в теле запроса с Content-Type: application/octet-stream, а дополнительные параметры PostDocumentInput – в отдельном HTTP заголовке CPDSS-POSTDOC, закодированном в формат Base64.

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

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

POST /documentstore/api/documents HTTP/1.1
Host: dss-sdk.cryptopro.ru
Content-Type: application/octet-stream
CPDSS-POSTDOC: eyJGaWxlbmFtZSI6InRlc3QudHh0In0=
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGc ... PvtpXJYEdSiGHeFeQ
Content-Length: 1556

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

Сервис возвращает ID загруженного документа.

{
    "DocumentId": "8336ca2d-10b9-499a-8f85-6292003ffdff"
}

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

Описание API Сервиса Подписи - Сервис Подписи

На данном шаге создаётся операция подписи, которая будет подтверждена с помощью DSS SDK.

При создании операции подписи необходимо указать:

• список подписываемых документов
• идентификатор сертификата подписи
• параметры подписи

Результатом вызова является ID операции подписи. Operation -> Id будет использован на следующем шаге при запросе подтверждения операции.

Примечание

Вызвающая система должна сохранить индентификатор созданной операции. Идентификатор может быть использован для проверки статуса операции, например, если вызывающая система не получила callback о завершении подтверждения операции в DSS SDK.

Если сертификат пользователя назначен 'Сертификатом по умолчанию', то в параметре CertificateId может быть передано значение 0.

Пареметры подписи могут быть переданы в двух вариантах:

• шаблон подписи (ProcessingTemplateId)
• явно задание параметров подписи (Parameters)

Шаблон подписи должен быть предварительно создан Администратором DSS. Идентификатор шаблона может быль либо явно задан в настройках вызывающей системы, либо может быть получен из политики Сервиса Подписи

Примечание

На Сервисе Подписи может быть задано несколько шаблонов подписи. Выбор шаблона из политики сервиса подписи может быть использован если вызывающая система поддерживает интерактивное взаимодействие с пользователем.

Описание параметров подписи и примеры задания параметов подписи приведены - Параметры подписи и Примеры запросов на подпись

Если используется режим асинхронной подписи, то в запросе необходимо указать параметры IsAsync, Callback.

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

POST /SignServer/rest/api/v2/signature/ HTTP/1.1
Host: dss-sdk.cryptopro.ru
Content-Type: application/json
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbG ... PslMFZormrKd35nd1xRw8foIpww
Accept: */*
Content-Length: 154
Connection: keep-alive

{
    "BinaryData": [{
        "RefId" : "8336ca2d-10b9-499a-8f85-6292003ffdff"
    }],
    "Signature" : 
    { 
        "CertificateId": "0",
        "ProcessingTemplateId": "1"
    },
    "IsAsync":"true",
    "Callback":"https://hostname/callback"
}

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

{
    "Operation": {
        "Id": "5070c752-ae8a-46f4-aea3-c4d38930b915",
        "Result": null,
        "Status": "Created",
        "Error": null,
        "ErrorDescription": null,
        "ExpirationDate": "1588636611"
    }
}

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

После создания операции подписи на Сервисе Подписи необходимо отправить запрос на её подтверждение в DSS SDK. В запросе вызывающая система передаёт:

• Идентификатор операции сервиса подписи
• callback Адрес для оповещения о завершении операции

Примечание

Если интегрируемая система не передала адрес callback при вызове /v2/confirmation, то статус подтверждения операции она сможет узнать периодически опрашивая /v2.0/confirmation.

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

POST /STS/v2.0/confirmation HTTP/1.1
Host: dss-sdk.cryptopro.ru
Content-Type: application/json
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGci ... Vhmw
Content-Length: 118

{
  "Resource" : "urn:cryptopro:dss:signserver:SignServer",
  "ClientId":"oauth-client-id",
  "ClientSecret":"oauth-client-secret",
  "OperationId" : "5070c752-ae8a-46f4-aea3-c4d38930b915",
  "CallbackUri" : "https://externalhost/system/callback"
}

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

{
    "Challenge": {
        "Title": {
            "Value": "Подтвердите операцию на устройстве с помощью приложения."
        },
        "TextChallenge": [
            {
                "Label": "Подпись документа. не задано. Тип подписи: CAdES. Сертификат: txusr300.",
                "ExpiresIn": 300,
                "CreatedAt": 1575834219,
                "ExpiresInSpecified": true,
                "IsHidden": false,
                "AuthnMethod": "http://dss.cryptopro.ru/identity/authenticationmethod/mydss",
                "RefID": "ac93dc5f-f374-4c0f-a37d-cb5a90e1af97",
                "Title": "Подтвердите операцию на устройстве с помощью приложения."
            }
        ]
    },
    "IsFinal": false,
    "IsError": false
}

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

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

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

При получении запроса Сервис Подтверждения Операций и сервис 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, то подтверждение транзакции ещё не завершено.

Получение callback о подтверждении операции

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

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

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

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

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

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

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

{
    "Result":"failed",
    "TransactionId":"e19de724-0a4f-4d29-903a-0d3c93735dad",
    "Error":"all_actions_declined",
    "ErrorDescription":"Все действия входящие в состав операции 'e19de724-0a4f-4d29-903a-0d3c93735dad' были отклонены."
}

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

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

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

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

POST https://host/STS/v2.0/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	У пользователя есть неподтвержденная транзакция.

Проверка статуса подтверждения операции

Если интегрируемая система не передала адрес callback в первом запросе к /v2.0/confirmation, то статус подтверждения операции она сможет узнать периодически опрашивать Сервис Подтверждения Операция, ожидая завершение подтверждения транзакции (флаг IsFinal = true).

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

POST https://host/STS/v2.0/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)

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

Примечание

Данный вызов используется в сценарии синхронной подписи.

Описание API Сервиса Подписи - Конечная точка Signature

После получения callback и нового access_token вызывающая система обращается на Сервис Подписи непосредственно для подписания документов

Внимание!

В заголовке Authorization необходимо передать access_token, полученный на предыдущем шаге.

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

POST /SignServer/rest/api/v2/signature HTTP/1.1
Host: dss-sdk.cryptopro.ru
Content-Type: application/json
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbG ... SaA_hBR82j4nZa0g
Content-Length: 2

{}

Сервис вернёт результат подписания OperationInfo. Поле Result содержит результат подписи каждого из документов. Если статус Status документа Completed, то ID подписанного документа сохранено в поле RefId.

Загрузить подписанный документ можно с помощью метода /content

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

{
    "Operation": {
        "Id": "6ec9d54a-7f4d-4579-abe9-660ce241e185",
        "Result": {
            "ProcessedDocuments": [
                {
                    "RefId": "f7dbd740-9fad-4aea-88a7-39dfcc81c0ab",
                    "OriginalRefId": "37bcc23f-73d8-4cb9-8b54-9b47ad03fd52",
                    "Content": null,
                    "Status": "Completed",
                    "Error": null,
                    "ErrorDescription": null
                }
            ]
        },
        "Status": "Completed",
        "Error": null,
        "ErrorDescription": null,
        "ExpirationDate": 1582121878
    }
}

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

В случае ошибки подписания документа соответствующий ему элемент списка ProcessedDocuments будет иметь Status Error

{
    "Operation": {
        "Id": "6ec9d54a-7f4d-4579-abe9-660ce241e185",
        "Result": {
            "ProcessedDocuments": [
                {
                    "RefId": null,
                    "OriginalRefId": "c27464c5-acd4-4c87-81af-06d7b72fe14a",
                    "Content": null,
                    "Status": "Error",
                    "Error": "Ошибка при подписи документа:\r\nтип подписи CMS, параметры: [DocumentInfo, test.pdf], [CADESType, BES].\r\nВложенное сообщение:\r\nЗатребованный тип CAdES подписи не поддерживается: [Присоединённая подпись в потоковом режиме].",
                    "ErrorDescription": null
                }
            ]
        },
        "Status": "Completed",
        "Error": null,
        "ErrorDescription": null,
        "ExpirationDate": 1582121878
    }
}