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

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

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

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

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

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

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

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

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

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

  • User - пользователь.
  • Admin - оператор.
  • Service - система (используется только для назначения Аудит)

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

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

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

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

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

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

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

WS-Trust

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

<wst:RequestSecurityToken>
  ...
  <auth:AdditionalContext>
    <auth:ContextItem Name="xs:anyURI" Scope="xs:anyURI" ? ...>
      (<auth:Value>xs:string</auth:Value> |
       xs:any ) ?
    </auth:ContextItem> *
    ...
  </auth:AdditionalContext> 
  ...
</wst:RequestSecurityToken>

Для указания области использования и параметров используются следующие имена элементов контекста: http://dss.cryptopro.ru/identity/claims/confirmationscope и http://dss.cryptopro.ru/identity/claims/confirmationscopeparam

Пример

<trust:RequestSecurityToken xmlns:trust="http://docs.oasis-open.org/ws-sx/ws-trust/200512">
    <wsp:AppliesTo xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy">
    <wsa:EndpointReference xmlns:wsa="http://www.w3.org/2005/08/addressing">
        <wsa:Address>https://relying-party/</wsa:Address>
    </wsa:EndpointReference>
    </wsp:AppliesTo>
    <trust:KeyType>http://docs.oasis-open.org/ws-sx/ws-trust/200512/SymmetricKey</trust:KeyType>
    <trust:RequestType>http://docs.oasis-open.org/ws-sx/ws-trust/200512/Issue</trust:RequestType>
    <auth:AdditionalContext xmlns:auth="http://docs.oasis-open.org/wsfed/authorization/200706">
    <auth:ContextItem Name="http://dss.cryptopro.ru/identity/claims/confirmationscope">
        <auth:Value>test-confirmation-scope</auth:Value>
    </auth:ContextItem>
    <auth:ContextItem Name="http://dss.cryptopro.ru/identity/claims/confirmationscopeparam">
        <auth:Value>Param1:ValueOfParam1</auth:Value>
    </auth:ContextItem>
    </auth:AdditionalContext>
</trust:RequestSecurityToken>

Oauth 2.0

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

Пример

GET /STS/oauth/authorize?client_id=eea2fd3f-5c70-4d74-a594-f1e7bf81b4d7
   &response_type=code
   &scope=openid+offline_access+dss+test-confirmation-scope
   &redirect_uri=urn%3Aietf%3Awg%3Aoauth%3A2.0%3Aoob%3Aauto
   &resource=https%3A%2F%2Fhostname%2FSignServer%2Frest%2Fapi
   &dss_scope_params=eyJDcFRpbWUiOiIxNy4wMS4yMDE4IDE0OjQ5OjU1In0 HTTP/1.1

Подстановочные параметры должны быть предварительно закодированы по следующему алгоритму:

  1. Все параметры и их значения представить в виде JSON объекта, в котором название свойства соответствует названию параметра, а значение свойства – значению параметра.
  2. Полученный JSON-объект представить, как строку в кодировке UTF-8, и преобразовать в массив байтов.
  3. Полученный массив байтов преобразовать в строку c помощью алгоритма BASE64URL.

Пример

Пусть в шаблоне требуется задать параметр CpTime со значением 17.01.2018 14:49:55. Соответствующий этим данным JSON объект будет выглядеть {"CpTime":"17.01.2018 14:49:55"}.

В кодировке BASE64URL eyJDcFRpbWUiOiIxNy4wMS4yMDE4IDE0OjQ5OjU1In0.

При использовании следующего шаблона

Подтверждение тестовой операции. Время {0:CpTime}

на устройство пользователя будет отправлено сообщение:

Подтверждение тестовой операции. Время 17.01.2018 13:20:27

ЦИ проверяет, что все указанные в шаблоне параметры переданы в запросе, и, если это не так, вернет ошибку. В запросе может быть указана только одна область использования маркера.

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

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

Пример

POST /STS/confirmation HTTP/1.1
Authorization: Bearer eyJ0…
Content-Type: application/json; charset=utf-8
Host: hostname

{
   "Resource":"https://dss.cryptopro.ru/SignServer/rest/api",
   "ClientId":"oauth-client-id",
   "ClientSecret":"oauth-client-secret",
   "ConfirmationScope":"test-confirmation-scope",
   "ConfirmationParams": {
        "CpTime":"17.01.2018 17:54:02"
   }
}

В данном примере в качестве идентификатора области использования передается значение test-confirmation-scope, а в качестве значения параметра CpTime - 17.01.2018 17:54:02. При использовании следующего шаблона

Подтверждение тестовой операции. Время {0:CpTime}

на устройство пользователя будет отправлено сообщение:

Подтверждение тестовой операции. Время 17.01.2018 13:20:27

ЦИ проверяет, что все указанные в шаблоне параметры переданы в запросе, и, если это не так, вернет ошибку.

В запросе может быть указана только одна область использования маркера.

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

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

Пример

Пример

POST /STS/v2.0/confirmation HTTP/1.1
Authorization: Bearer eyJ0…
Content-Type: application/json; charset=utf-8
Host: hostname

{
    "Resource": "https://dss.cryptopro.ru/SignServer/rest/api",
    "ClientId":"oauth-client-id",
    "ClientSecret":"oauth-client-secret",
    "ChallengeResponse":
    {
        "ControlChallengeResponse": 
        {
            "RefId": "a7b55177-a974-46a4-ad0d-046b14f2654e",
            "ControlAction": "Cancel"
        }
    }
}

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

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "IsFinal": true,
    "IsError": true,
    "Error": "authentication_cancelled"
}

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

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

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

Пример

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

<?xml version="1.0" encoding="utf-8"?>
<dtbs xmlns="http://www.cryptopro.ru/schemas/2014/08/dtbs">
    <row>
        <name>Наименование документа</name>
        <value>Платежное поручение</value>
    </row>
    <row>
        <name>Банк получателя</name>
        <value>АКБ "Рога и копыта"</value>
    </row>
    <row>
        <name>Счет получателя</name>
        <value>40781032100000000000</value>
    </row>
    <row>
        <name>Сумма платежа</name>
        <value>100 RUB</value>
    </row>
</dtbs>

Преобразовав указанный XML в UTF8 и в BASE64, получим строку (переносы строк добавлены для удобства чтения):

PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0idXRmLTgiPz4NCjxkdGJzIHht
bG5zPSJodHRwOi8vd3d3LmNyeXB0b3Byby5ydS9zY2hlbWFzLzIwMTQvMDgvZHRi
cyI+DQogICAgPHJvdz4NCiAgICAgICAgPG5hbWU+0J3QsNC40LzQtdC90L7QstCw
0L3QuNC1INC00L7QutGD0LzQtdC90YLQsDwvbmFtZT4NCiAgICAgICAgPHZhbHVl
PtCf0LvQsNGC0ZHQttC90L7QtSDQv9C+0YDRg9GH0LXQvdC40LU8L3ZhbHVlPg0K
ICAgIDwvcm93Pg0KICAgIDxyb3c+DQogICAgICAgIDxuYW1lPtCR0LDQvdC6INC/
0L7Qu9GD0YfQsNGC0LXQu9GPPC9uYW1lPg0KICAgICAgICA8dmFsdWU+0JDQmtCR
ICLQoNC+0LPQsCDQuCDQutC+0L/Ri9GC0LAiPC92YWx1ZT4NCiAgICA8L3Jvdz4N
CiAgICA8cm93Pg0KICAgICAgICA8bmFtZT7QodGH0ZHRgiDQv9C+0LvRg9GH0LDR
gtC10LvRjzwvbmFtZT4NCiAgICAgICAgPHZhbHVlPjQwNzgxMDMyMTAwMDAwMDAw
MDAwPC92YWx1ZT4NCiAgICA8L3Jvdz4NCiAgICA8cm93Pg0KICAgICAgICA8bmFt
ZT7QodGD0LzQvNCwINC/0LvQsNGC0LXQttCwPC9uYW1lPg0KICAgICAgICA8dmFs
dWU+MTAwIFJVQjwvdmFsdWU+DQogICAgPC9yb3c+DQo8L2R0YnM+

Запрос будет выглядеть следующим образом:

{
    "Resource": "{{resource}}",
   "ClientId":"oauth-client-id",
   "ClientSecret":"oauth-client-secret",
    "ConfirmationScope": "Test",
    "CallBackUri": "{{callback_uri}}",
    "ConfirmationParams": {
        "Param1": "Подстановочный параметр 1"
    },
    "ConfirmationData" : "PD94...",
    "ConfirmationDataType" : "dtbs"
}

Помимо бинарных данных в данном запросе передается и подстановочный параметр Param1. При использовании следующего шаблона сообщения:

"Подтверждение операции {0:DocumentInfo} Параметры: {0:Param1}"

отобразит на устройстве пользователя текст (переводы строк добавляны для удобства чтения):

Подтверждение операции Наименование документа: 
Платежное поручение, Банк получателя: АКБ "Рога и копыта", 
Счет получателя: 40781032100000000000, Сумма платежа: 100 RUB.
Параметры: Подстановочный параметр 1

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

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

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

{
    "Resource": "{{resource}}",
   "ClientId":"oauth-client-id",
   "ClientSecret":"oauth-client-secret",
    "ConfirmationScope": "Test",
    "CallBackUri": "{{callback_uri}}",
    "ConfirmationParams": {
        "Param1": "Подстановочный параметр 1"
    },
   "ConfirmationDataRefs" : [
        "31FA0009-0968-4E5F-9B66-A1B6B53BA5C7",
        "DB1655AF-647E-44A4-8AB2-FF2B039B3BE1"        
    ]
}
Примечание

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

Рассмотрим подтверждение произвольной операции через API 2.0 на следующем примере:

Исходные данные

  • УЗ пользователя с логином: ee8473f2-f6c8-4527-a7bb-f0ec3d9f4131
  • Первичная аутентификация не требуется.
  • Идентификатор произвольной операции: CertificateConfirmOperation.
  • Во всех примерах переводы строк добавлены для удобства чтения.

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

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

Запрос

POST /STS/oauth/token HTTP/1.1
Host: hostname
Content-Type: application/x-www-form-urlencoded
Authorization: Basic MTJjZjR...

grant_type=password
&username=ee8473f2-f6c8-4527-a7bb-f0ec3d9f4131
&resource=urn:cryptopro:dss:signserver:SignServer
&password=

Ответ

{
    "access_token": "eyJ0...",
    "expires_in": 300,
    "token_type": "Bearer"
}

Загрузка документа в СОД

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

Запрос

POST /documentstore/api/documents HTTP/1.1
Host: hostname
Content-Type: application/octet-stream
CPDSS-POSTDOC: eyAiRmlsZU5hbWUiOiJ0ZXN0LnJ4dCIgfQ==
Authorization: Bearer eyJ0eXA...

"<file contents here>"

Ответ

{
    "DocumentId": "303306b3-c8df-4947-a9ce-9c4be24482bd"
}

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

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

Запрос

POST /STS/v2.0/confirmation HTTP/1.1
Host: hostname
Content-Type: application/json
Authorization: Bearer eyJ0eX...

{
  "Resource" : "urn:cryptopro:dss:signserver:SignServer",
  "ClientId":"oauth-client-id",
  "ClientSecret":"oauth-client-secret",
  "ConfirmationScope": "CertificateConfirmOperation",
   "ConfirmationDataRefs" : [
        "303306b3-c8df-4947-a9ce-9c4be24482bd"
    ]
}

Ответ

{
    "Challenge": {
        "Title": {
            "Value": "Подтвердите операцию на устройстве с помощью приложения."
        },
        "TextChallenge": [
            {
                "Label": "Подтверждение операции выпуск сертификата.",
                "ExpiresIn": 300,
                "CreatedAt": 1579670047,
                "ExpiresInSpecified": true,
                "IsHidden": false,
                "AuthnMethod": "http://dss.cryptopro.ru/identity/authenticationmethod/mydss",
                "RefID": "d4b63163-50ae-4b67-8a5a-50f15fe2fe5c",
                "Title": "Подтвердите операцию на устройстве с помощью приложения."
            }
        ]
    },
    "IsFinal": false,
    "IsError": false
}

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

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

Запрос

POST /STS/v2.0/confirmation HTTP/1.1
Host: hostname
Content-Type: application/json
Authorization: Bearer eyJ0eXA...

{
  "Resource" : "urn:cryptopro:dss:signserver:SignServer",
  "ClientId":"oauth-client-id",
  "ClientSecret":"oauth-client-secret",
  "ChallengeResponse" : {
    "TextChallengeResponse" : [ {
      "RefId" : "d4b63163-50ae-4b67-8a5a-50f15fe2fe5c"
    } ]
  }
}

Ответ

{
    "AccessToken": "eyJ0eXAi...",
    "IsFinal": true,
    "IsError": false
}

Значение поля IsFinal равное true и значение поля IsError равное false свидетельствуют о том, что подтвреждение завершилось успешно.

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

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

Запрос

GET /STS/operations/d4b63163-50ae-4b67-8a5a-50f15fe2fe5c HTTP/1.1
Host: hostname
Authorization: Bearer eyJ0eXAiO...

Здесь d4b63163-50ae-4b67-8a5a-50f15fe2fe5c является идентификатором операции, он совпадает с идентификатором операции подтверждения.

Ответ

{
    "Id": "8cd47c3b-897c-4cc8-bf85-49dc432dd50d",
    "Type": "CertificateConfirmOperation",
    "Parameters": null,
    "Description": "Подтверждение операции выпуск сертификата.",
    "State": "Confirmed",
    "CreatedAt": 1579677157,
    "CompleteBefore": 0,
    "ConfirmBefore": 1579677457,
    "ConfirmedAt": 1579677182,
    "CompletedAt": 0,
    "UpdatedAt": 1579677182,
    "UserId": "4e22dad2-ffd1-4bdd-8451-1a29e2cf3a22",
    "Context": null,
    "Proof": null,
    "AuthenticationType": "http://dss.cryptopro.ru/identity/authenticationmethod/mydss",
    "ExternalId": "8cd47c3b-897c-4cc8-bf85-49dc432dd50d",
    "Actions": [
        {
            "Id": "4c7edc0f-2479-4bcd-8550-590c53b781ab",
            "DocumentId": "303306b3-c8df-4947-a9ce-9c4be24482bd",
            "OriginalDocumentId": null,
            "Status": "Approved",
            "State": "Pending",
            "ResultValue": null,
            "Error": null,
            "ErrorDescription": null
        }
    ]
}

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

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

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

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

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

Set-IdsClient -ClientId ScopeRestrictedClientId -AllowedScopes scope1,scope2

здесь

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

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

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

Set-IdsScope -ScopeName RememberConsentScope -RememberConsent true

здесь

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

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

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

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

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

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

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

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

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

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

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

Запрос

POST /STS/confirmation HTTP/1.1
Authorization: Basic c2dhOg==
Content-Type: application/json

{
  "Resource" : "urn:cryptopro:dss:signserver:SignServer",
  "ConfirmationScope" : "dss-access",
  "ClientId" : "cryptopro.dss.samples",
  "ClientSecret" : "WbENKmg-a0Kada6dOPpsPzJ6LIVT26b7"
}

После подтверждения успешный результат будет запомнен и приложение сможет получать маркеры доступа, указывая в запросах область использования dss-access.