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

В данном разделе описывается последовательность действий для подтверждения операции по одноразовым паролям, отправляемых по СМС. Все запросы выполняются от Пользователя.

Внимание!

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

Предварительно должно быть:

  1. Пользователю создана учетная запись в СЭП.
  2. Пользователю назначена вторичная аутентификация по одноразовым паролям, отправляемых по СМС, и заданы операции, требующие подтверждения.
  3. Пользователю выпущен сертификат подписи.
  4. Зарегистрированный на сервере OAuth 2.0 клиент.

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

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

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

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

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

Примечание

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

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

POST https://{{hostname}}/{{instanceName}}/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, выпущенный Центром Идентификации
  • 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 не зарегистрирована.

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

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

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

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

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

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

В данном примере показано, как пользователь инициирует подписание документа, после того как аутентифицировался в Сервисе Подписи. Параметры создания транзакций для других операций приведены здесь

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

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

POST https://{{hostname}}/{{instanceNamce}}/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 Неверно указаны параметры подписи

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

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

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

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

  • TransactionTokenId – Идентификатор транзакции, созданной на Сервисе Подписи (пункт 1.1).
  • Resource – Идентификатор Сервиса Подписи в формате urn:cryptopro:dss:signserver:<signserver app name> (по умолчанию имеет значение urn:cryptopro:dss:signserver:signserver).
  • ClientId - идентификатор OAuth клиента.
  • ClientSecret - пароль OAuth клиента (для неконфиденциальных клиентов данный параметр не указывается).

2.1 POST-запрос на подтверждение созданной транзакции

POST https://{{hostname}}/{{instanceName}}/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",
}

В зависимости от количества подключенных способов подтверждения операций возможно два варианта ответа на запрос:

  • Если у Пользователя подключен один метод подтверждения операций, то при успешном выполнении запроса он получит одноразовый пароль на указанный номер мобильного телефона (Пример ответа 1).
  • Если у Пользователя подключено несколько методов подтверждения операций, то при успешном выполнении запроса он получит доступные методы подтверждения операции (Пример ответа 2). В этом случае необходимо выбрать метод подтверждения операции (пункт 2.1.1).

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

При успешном выполнении запроса Пользователь должен получить на свой номер мобильного телефона одноразовый пароль. Необходимо запомнить идентификатор транзакции RefID для ее подтверждения в пункте 2.2.

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": [
            {
                "AuthnMethod": "http://dss.cryptopro.ru/identity/authenticationmethod/otpviasms",
                "RefID": "5460867e-be6a-4940-bebc-9aeb516fa448",
                "Label": "02.11.2018 9:47:05. Подпись документа. testPdf.pdf. Идентификатор операции gcoaryoy. Пользователь Test2. Сертификат: test2.",
                "MaxLenSpecified": false,
                "HideTextSpecified": false,
                "ExpiresIn": 86400,
                "ExpiresInSpecified": true
            }
        ],
        "ContextData": {
            "RefID": "5460867e-be6a-4940-bebc-9aeb516fa448"
        }
    },
    "IsFinal": false,
    "IsError": false
}

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

Необходимо запомнить идентификатор транзакции RefID для выбора метода ее подтверждения в пункте 2.1.1.

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": "Для подтверждения операции необходимо выбрать способ аутентификации"
        },
        "ChoiceChallenge": [
            {
                "Choice": [
                    {
                        "RefID": "http://dss.cryptopro.ru/identity/authenticationmethod/otpviasms",
                        "Label": "Аутентификация с помощью СМС"
                    },
                    {
                        "RefID": "http://dss.cryptopro.ru/identity/authenticationmethod/mobile",
                        "Label": "Аутентифкация c помощью мобильного приложения"
                    }
                ],
                "RefID": "7406c54e-0ba5-4340-bbaa-3c2feebdc852",
                "Label": "Для подтверждения операции необходимо выбрать способ аутентификации",
                "ExactlyOne": true,
                "ExactlyOneSpecified": true,
                "ExpiresIn": 86400,
                "ExpiresInSpecified": true
            }
        ],
        "ContextData": {
            "RefID": "7406c54e-0ba5-4340-bbaa-3c2feebdc852"
        }
    },
    "IsFinal": false,
    "IsError": false
}

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

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

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

Поле Описание
Title Текст, который вызывающая система может отобразить пользователю в своем интерфейсе
TextChallenge Дополнительные данные для подтверждения операции
ChoiceChallenge Возвращается только в случае, если у Пользователя включено несколько способов подтверждения транзакций. Содержит информацию об этих способах подтверждения транзакций.

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

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

RefId - Идентификатор транзакции, созданной на Сервисе Операций. Его необходимо будет использовать при последующих обращениях на конечную точку /confirmation (пункты 2.1.1 и 2.2).

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

Поле Описание
RefID Идентификатор транзакции, созданной на Сервисе Операций
Choice Информация о доступных способах подтверждения транзакций

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

Поле Описание
RefID Идентификатор метода подтверждения транзакции
Label Название метода подтверждения транзакции
Примечание

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

2.1.1 POST Запрос на выбор метода подтверждения транзакции (только если подключено несколько методов подтверждения)

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

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

  • ChoiceSelected.RefID – Идентификатор выбранного метода подтверждения транзакции
  • RefId – Идентификатор транзакции, созданной на Сервисе Операций (пункт 2.1).
  • Resource – Идентификатор Сервиса Подписи в формате urn:cryptopro:dss:signserver:<signserver app name> (по умолчанию имеет значение urn:cryptopro:dss:signserver:signserver). 
POST https://{{hostname}}/{{instanceName}}/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",
    "ChallengeResponse" : {
    "ChoiceChallengeResponse" : [ {
        "RefId" : "49744464-5cd7-419d-891e-2495b8f49539",
        "ChoiceSelected": [{
                "RefID": "http://dss.cryptopro.ru/identity/authenticationmethod/otpviasms",
            }]
    } ]
    }
}

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

При успешном выполнении запроса Пользователь должен получить на свой номер мобильного телефона одноразовый пароль. Необходимо запомнить новый идентификатор транзакции RefID для ее подтверждения в пункте 2.2.

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": [
            {
                "AuthnMethod": "http://dss.cryptopro.ru/identity/authenticationmethod/otpviasms",
                "RefID": "5460867e-be6a-4940-bebc-9aeb516fa448",
                "Label": "02.11.2018 9:47:05. Подпись документа. testPdf.pdf. Идентификатор операции gcoaryoy. Пользователь Test2. Сертификат: test2.",
                "MaxLenSpecified": false,
                "HideTextSpecified": false,
                "ExpiresIn": 86400,
                "ExpiresInSpecified": true
            }
        ],
        "ContextData": {
            "RefID": "5460867e-be6a-4940-bebc-9aeb516fa448"
        }
    },
    "IsFinal": false,
    "IsError": false
}
Примечание

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

2.1.2 POST-запрос повторной отправки одноразового пароля по SMS

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

  • RefId – Идентификатор транзакции, созданной на Сервисе Операций (пункт 2.1 или 2.1.1).
  • ControlAction - Управляющее действие. Значение Repeat используется для повторной отправки одноразового пароля.
POST /sts/confirmation HTTP/1.1
Authorization: Bearer <access_token>
Content-Type: application/json; charset=utf-8
Host: host

{
    "Resource": " urn:cryptopro:dss:signserver:signserver",
    "ClientId":"oauth-client-id",
    "ClientSecret":"oauth-client-secret",
    "ChallengeResponse": {
         "ControlChallengeResponse": { 
                   "RefId": "49744464-5cd7-419d-891e-2495b8f49539", 
                   "ControlAction": "Repeat" 
         }
    }
}

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

{
    "Challenge": {
        "Title": {},
        "TextChallenge": [
            {
                "ExpiresIn": 1200,
                "ExpiresInSpecified": true,
                "IsHidden": false,
                "AuthnMethod": "http://dss.cryptopro.ru/identity/authenticationmethod/otpviasms",
                "RefID": "73f54bdc-6f62-4fff-884c-76a6e6992502"
            }
        ],
        "ContextData": {
            "RefID": "73f54bdc-6f62-4fff-884c-76a6e6992502"
        }
    },
    "IsFinal": false,
    "IsError": false
}

2.2 POST Запрос на получение результата подтверждения транзакции

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

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

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

  • RefId – Идентификатор транзакции, созданной на Сервисе Операций (пункт 2.1 или 2.1.1).
  • Value – Одноразовый пароль, который Пользователь получил на свой номер мобильного телефона. 
POST https://{{hostname}}/{{instanceName}}/confirmation HTTP/1.1
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJHM ... 5aPB98A3NAVduJbtz5Wti-H8CeXycwB6A
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":"5460867e-be6a-4940-bebc-9aeb516fa448",
                "Value":"12..56"}
            ]
    }
}

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

Если в ответе 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 Передан неверный код подтверждения

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

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

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

Примечание

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

3.1 POST Запрос на получение подписанного документа

POST https://{{hostname}}/{{instanceName}}/rest/api/documents HTTP/1.1
Authorization: Bearer eyJ0eXAiOiJKV1QiLC ... 5b1T6H1ytuWztMPGfz-Ow
Content-Type: application/json; charset=utf-8
Host: host
Content-Length: 2
Expect: 100-continue

{
}
Примечание

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

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

POST https://{{hostname}}/{{instanceName}}/rest/api/documents HTTP/1.1
Authorization: Bearer eyJ0eXAiOiJKV1QiLC ... 5b1T6H1ytuWztMPGfz-Ow
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 Неверно указан ПИН-код на закрытый ключ