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

В данном разделе:

• Общие сведения
• Сведения об операции
• Отображаемые сведения об операциях
• Настройки
• Процесс подтверждения операций
• Виды операций
• Выбор метода вторичной аутентификации
• Отмена вторичной аутентификации
• Дополнительные отображаемые данные
• Время жизни операций

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

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

• пароль,
• сертификат,
• маркер доступа, полученные от стороннего Центра Идентификации.

Отдельным видом первичной аутентификации можно считать только идентификацию. В этом случае пользователю достаточно предъявить только логин для прохождения первичной аутентификации.

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

Вторым фактором аутентификации пользователя может служить:

• мобильное приложение со встроенным Ключ SDK
• одноразовый пароль, доставляемый по SMS или Email
• одноразовый пароль, получаемый по протоколу OATH

Примечание

Одноразовые пароли OATH могут быть получены при помощь мобильных приложений Яндекс.Ключ, Google Authenticator, Microsoft Authenticator и других. Также одноразовые пароли могут быть получены при помощи аппаратных токенов/брелоков.

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

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

• операции Сервиса Подписи,
• вход пользователя,
• произвольные операции.

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

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

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

• Администратором в настройках Центра Идентификации
• Оператором при создании или изменении учетной записи пользователя на Центре Идентификации

Сведения об операции

Любая операция характеризуется:

• Идентификатором
• Типом операции
• Временем жизни
• Статусом
• Идентификатором пользователя
• Данными

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

Пользователь и/или прикладная система могут получить сведения об операциях через API Сервиса Обработки Операций. Данная конечная точка может быть использована для контроля статуса операции. Например, если прикладная система не получила callback с результатами подтверждения операции, или необходимо получить информацию о ранее подтвержденных операциях.

КриптоПро Ключ позволяет подтверждать следующие типы операций:

Операция	Код	Описание
Issue	1	Выпуск маркера безопасности (Вход пользователя)
SignDocument	2	Подпись документа
SignDocuments	4	Пакетная подпись документа
DecryptDocument	8	Расшифрование документа
CreateRequest	16	Создание запроса на сертификат
ChangePin	32	Смена ПИН-кода
RenewCertificate	64	Обновление сертификата
RevokeCertificate	128	Отзыв сертификата
DeleteCertificate	1024	Удаление сертификата
PrivateKeyAccess	2048	Доступ к закрытому ключу
ScopeConfirmation	-	Подтверждение произвольных операций

Операция Issue относится к любому выпуску маркера безопасности пользователя с подтверждением. В частности ее можно рассматривать как "Вход пользователя" с подтвреждением.

ScopeConfirmation относится к подтверждению операций, зарегистрированных Администратором. Администратор может зарегистрировать любое количество операций, выполнение которых требует подтверждения пользователем. Но в аудите все подтвержденные операции будут отображаться с одинаковым кодом события.

В v2 API операции типа SignDocuments не используются. В v2 API нет различий между подписью одного документа и подписью пакета документов (в отличие от v1 API), поэтому операции подписи имеют тип SignDocument.

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

Статус операции	Описание
Created	Операция создана
Challenged	Запрошено подтверждение операции
Confirmed	Операция подтверждена пользователем
Declined	Операция отклонена пользователем
Completed	Операция выполнена
Expired	Операция истекла
Cancelled	Операция отменена на сервере
Error	Обработка операции завершилась ошибкой

Ниже представлена схема переходов статусов операции.

Для операций Issue, ScopeConfirmation статус Created не поддерживается, начальное состояние для данных операций Challenged.

Для операций Issue, ScopeConfirmation статус Completed не поддерживается, успешному завершению операций соответствует статус Confirmed.

Штатным изменением статуса операции является: Created -> Challenged -> Confirmed -> Completed.

Время жизни операции настраивается Администратором. Время подтверждения операции задается на Центре Идентификации - параметр OtpConfirmationTimeOut командлетов Get-IdsProperties, Set-IdsProperties. Время выполнения операции задается на Сервисе Подписи - параметр TokenTimeout командлетов Get-SignProperties, Set-SignProperties.

Так же прикладная система может явно указать срок жизни операции. Для поддержки данного сценария Администратор должен задать максимально допустимое время жизни операций в параметра MaxTransactionLifetime командлетов Get-IdsProperties, Set-IdsProperties.

• Если MaxTransactionLifetime равен 0, то переданное прикладной системой время жизни операции игнорируется.
• Если MaxTransactionLifetime отличен от 0, то переданное прикладной системой время жизни операции должно быть меньше указанного значения.
• Если прикладная система укажет время жизни операции больше чем MaxTransactionLifetime, то операция будет создана со временем жизни MaxTransactionLifetime.
• Если прикладная система не укажет время жизни операции, то операция будет создана со временем жизни по умолчанию OtpConfirmationTimeOut.

Таким образом только прикладная система может задать разные сроки действия для различных операций. По умолчанию любые операции создаются со временем жизни по умолчанию OtpConfirmationTimeOut.

Настройками должно быть обеспечено условие TokenTimeout > OtpConfirmationTimeOut. То есть время выполнения операции должно быть больше, чем время подтверждения операции.
Если время выполнения будет меньше времени подтверждения, то возможны случаи когда сервер не успеет выполнить операцию после получения подтверждения пользователя и операция будет помечена как истекшая Expired.

Разница между TokenTimeout и OtpConfirmationTimeOut зависит от сценария подтверждения операции и нагрузки как на сервер, так и на прикладную систему. Если используется асинхронное подтверждение операций, то разница может составлять десятки секунд или минуты. Если используется синхронное подтверждение, то разница зависит от прикладной системы, вызывающей серверное API.

Отображаемые сведения об операциях

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

Настройки

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

• Для прикладной системы зарегистрирован OAuth-клиент
• Для учетной записи пользователя заданы методы первичной и вторичной аутентификации
• Для учетной записи пользователя заданы операции требующие подтверждения
• Зарегистрирован ресурс, для которого будет выполняться подтверждение операции
• Выполнены необходимые настройки методов вторичной аутентификации
• Настроены модули оповещения о статусе операции (опционально)

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

Подтверждение операций производится через конечные точки:

• https://hostname/<sts_app_name>/v2.0/confirmation
• https://hostname/<sts_app_name>/v2.0/confirmation/cert

Конечная точка /v2.0/confirmation/cert используется в случае, если прикладная система используется OAuth-клиент с аутентификацией по сертификату.

Процесс подтверждения операций состоит из следующих шагов:

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

Примечание

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

• Мобильное приложение со встроенным SDK
• SMS

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

Первичная аутентификация производится по протоколу OAuth 2.0 в соответствии с выбранным методом и сценарием аутентификации. Результатом первичной аутентификации пользователя является маркер доступа (JWT-токен). Полученный маркер должен быть использован при вызове методов API в дальнейшем.

Маркер доступа имеет ограниченный срок действия. После истечения срока действия прикладная система должна получить новый маркер доступа для возможности вызова методов API. Срок действия маркера доступа задается Администратором в настройках OAuth-клиента, назначенного прикладной системой. Время жизни задается через параметр AccessTokenLifetime команд Get-IdsClient, Set-IdsClient. По умолчанию время жизни маркера доступа равно 10 минутам.

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

Примечание

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

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

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

Создание операции на Сервисе Подписи находится за рамками данного раздела. Результатом создания операции на Сервисе Подписи является идентификатор операции Operation->Id. Пример ответа Сервиса Подписи, содержащий идентификатор операции:

Пример ответа Сервиса Подписи

{
    "Operation": {
        "Id": "30110c89-231b-40ba-a03e-3cab41a1d35e",
        "Result": null,
        "Status": "Created",
        "Error": null,
        "ErrorDescription": null,
        "ExpirationDate": 1641558446
    }
}

Прикладная система должна проверить значение поля Operation->Status перед продолжением выполнения сценарий. Если выполнение операции требует подтверждения пользователя, то поле Operation->Status будет иметь значение Created.

Требование подтверждения операции настраивается в профиле пользователя на Центре Идентификации.

Если в профиле пользователя не задано требование подтверждения операции, прикладная система может принудительно выполнить операцию с подтверждением передав флаг ForceConfirmation при создании операции.

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

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

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

После выполнения данного шага операция перейдет в статус Challenged.

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

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

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

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

Параметр OperationId при подтверждении Входа или произвольной операции не используется.

Пример

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

Content-Length: 192

{
  "ClientId" : "sample_client",
  "Resource" : "urn:cryptopro:dss:signserver:SignServer",
  "OperationId" : "30110c89-231b-40ba-a03e-3cab41a1d35e",
  "CallbackUri":"https://hostname2/callbackreciever/callback"
}

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

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

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

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

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

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

Поле	Описание
Image	Не используется QR-код для Offline подтверждения операции.
RefID	Идентификатор операции, созданной на Сервисе Операций
ExpiresIn	Срок действия операции, созданной на Сервисе Операций в секундах
CreatedAt	Время создания аутентификационного испытания (unix-time)
AuthnMethod	Идентификатор метода, используемый для подтверждения операции
Label	Описание операции, которое вызывающая система может отобразить пользователю в своем интерфейсе
Title	Краткое описание операции, которое вызывающая система может отобразить пользователю в своем интерфейсе

Примечание

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

Примечание

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

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

{
    "Challenge": {
        "Title": {
            "Value": "Подтвердите операцию на устройстве с помощью приложения."
        },
        "TextChallenge": [
            {
                "Label": "Подпись документа. test2.txt. Тип подписи: CMS. Сертификат: For Test. Идентификатор запроса rtf9ayay",
                "ExpiresIn": 600,
                "CreatedAt": 1641554849,
                "ExpiresInSpecified": true,
                "IsHidden": false,
                "AuthnMethod": "http://dss.cryptopro.ru/identity/authenticationmethod/mydss",
                "RefID": "30110c89-231b-40ba-a03e-3cab41a1d35e",
                "Title": "Подтвердите операцию на устройстве с помощью приложения."
            }
        ],
        "ContextData": {
            "RefID": "30110c89-231b-40ba-a03e-3cab41a1d35e"
        }
    },
    "IsFinal": false,
    "IsError": false
}

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

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

Если для подтверждения операции требуется предъявить одноразовый пароль (отправленный в SMS, Email или полученный с помощью мобильного приложения или токена OATH), то прикладная система должна дождаться от пользователя ввода одноразового пароля в ее интерфейсе и передать его на сервер на следующем шаге. См. раздел Аутентификация и подтверждение операций по одноразовым паролям.

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

• асинхронный режим: ожидать оповещение о подтверждении пользователем операции на адрес указанный в параметре CallbackUri.
• синхронный режим: периодически опрашивать Сервис Операций о статусе операции.

Примечание

Если используется асинхронное подтверждение операций на Сервисе Подписи, то на адрес, указанный в параметре RequestSecurityTokenResponse->CallbackUri в запросе к /v2.0/confirmation, придет оповещение только в случае:

• отклонения пользователем операции
• истечения срока жизни операции
• ошибок проверки кода подтверждения полученного от пользователя

Таким образом при асинхронном подтверждение операций на Сервисе Подписи, оповещение об успешном подтверждении операций пользователем не отправляется. Оповещение будет отправлено после подписания документов на адрес указанный в запросе к Сервису Подписи SignatureOperation->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.

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

Поле	Описание
Resource	идентификатор ресурса.
ClientId	идентификатор OAuth-клиента.
ClientSecret	пароль OAuth-клиента (для неконфиденциальных клиентов параметр не указывается).
ChallengeResponse	ответ на аутентификационное испытание

В поле ChallengeResponse передается:

Поле	Описание
TextChallengeResponse[]	ответ на аутентификационное испытание
ChoiceChallengeResponse[]	выбор метода вторичной аутентификации
ControlChallengeResponse	управляющее действие

В поле TextChallengeResponse передается:

Поле	Описание
Value	значение одноразового пароля или кода подтверждения
RefId	идентификатор операции

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

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

POST https://{{hostname}}/{{IdsInstanceName}}/v2.0/confirmation HTTP/1.1
Authorization: Bearer eyJ0eXAiOiJKV1 ... mXqvC5_3W244A
Content-Type: application/json; charset=utf-8
Content-Length: 212

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

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

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

{
"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.

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

Если ответ Сервиса Операций содержит флаги IsFinal - true, IsError - false, то сервис вернул новый маркер доступа AccessToken. Данный маркер доступа содержит факт подтверждения операции пользователем. Если

Выполнение операции

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

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

Примечание

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

Виды операций

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

В таблице ниже перечислены операции Сервиса Подписи, которые могут быть выполнены с подтверждением.

Операция	Код	Описание
SignDocument	2	Подпись документа
SignDocuments	4	Пакетная подпись документа
DecryptDocument	8	Расшифрование документа
CreateRequest	16	Создание запроса на сертификат
ChangePin	32	Смена ПИН-кода
RenewCertificate	64	Обновление сертификата
RevokeCertificate	128	Отзыв сертификата
DeleteCertificate	1024	Удаление сертификата
PrivateKeyAccess	2048	Доступ к закрытому ключу

Вход пользователя

Произвольные операции

Дополнительные действия

Выбор метода вторичной аутентификации

Если пользователю назначено несколько методов вторичной аутентификации, то в ответ на первый запрос к конечной точке /v2.0/confirmation Сервис Операций вернет список доступных пользователю методов вторичной аутентификации. Таким образом в структуре RequestSecurityTokenResponse будет заполнено поле ChoiceChallenge.

Примечание

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

Прикладная система должна выбрать нужный метод аутентификации и указать его идентификатор в ответе RequestSecurityToken в поле ChoiceChallenge

Список идентификаторов методов вторичной аутентификации:

Идентификатор	Описание
http://dss.cryptopro.ru/identity/authenticationmethod/mydss	Аутентификация при помощи мобильного приложения
http://dss.cryptopro.ru/identity/authenticationmethod/otpviasms	Одноразовые пароли по SMS
http://dss.cryptopro.ru/identity/authenticationmethod/otpviaemail	Одноразовые пароли по Email
http://dss.cryptopro.ru/identity/authenticationmethod/oath	Аутентификация по протоколу Oath

Примечание

Идентификатор метода Аутентификация при помощи мобильного приложения может быть составным, если на сервере зарегистрированы одна или несколько Прикладных систем. Список зарегистрированных прикладных систем можно посмотреть в выводе команды Get-IdsMobileAppConfiguration. В этом случае идентификатор будет иметь вид:

http://dss.cryptopro.ru/identity/authenticationmethod/mydss?systemId=<system_id>, где <system_id> - идентификатор прикладной системы (guid).

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

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

{
    "Challenge": {
        "Title": {
            "Value": "Для подтверждения операции необходимо выбрать способ аутентификации"
        },
        "ChoiceChallenge": [
            {
                "Choice": [
                    {
                        "RefID": "http://dss.cryptopro.ru/identity/authenticationmethod/oath",
                        "Label": "Аутентификация по протоколу OATH",
                        "Icon": "{Type:\"Css\",Value:\"fa fa-ticket fa-2x\"}",
                        "Description": "Аутентификация с помощью одноразовых паролей, полученных по протоколу OATH (TOTP и HOTP)"
                    },
                    {
                        "RefID": "http://dss.cryptopro.ru/identity/authenticationmethod/mydss?systemId=8f66a7c6-4379-45fd-89e5-914a10555f3b",
                        "Label": "Аутентификация c помощью мобильного приложения",
                        "Description": "SafeTech"
                    }
                ],
                "RefID": "843e19ea-ca04-46aa-a7fb-112b6a02570f",
                "Label": "Для подтверждения операции необходимо выбрать способ аутентификации",
                "ExpiresIn": 600,
                "CreatedAt": 1641596707,
                "ExactlyOne": true,
                "ExactlyOneSpecified": true,
                "ExpiresInSpecified": true
            }
        ],
        "ContextData": {
            "RefID": "843e19ea-ca04-46aa-a7fb-112b6a02570f"
        }
    },
    "IsFinal": false,
    "IsError": false
}

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

POST /STS/confirmation HTTP/1.1
Host: <hostname>
Content-Type: application/json
Authorization: Bearer eyJ0eXAiOiJKV ... tOTZXUVFBdyJ9

{
    "Resource": "urn:cryptopro:dss:signserver:signserver",
    "ClientId": "oauth-client-id",
    "ChallengeResponse": {
        "ChoiceChallengeResponse": [
            {
                "RefId": "843e19ea-ca04-46aa-a7fb-112b6a02570f",
                "ChoiceSelected": [
                    {
                        "RefID": "http://dss.cryptopro.ru/identity/authenticationmethod/oath"
                    }
                ]
            }
        ]
    }
}

Отмена вторичной аутентификации

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

Прикладная система передать идентификатор операции и тип управлящего действия в ответе RequestSecurityToken в поле ControlChallengeResponse

Примечание

Отмена операции не отменяет отправку SMS сообщения с одноразовым паролем, или Push-уведомления об операции в мобильное приложение и т.п. То есть пользователь будет уведомлен о создании операции, но не сможет ее подтвердить, так как прикладная система Отменит ее самостоятельно.

POST /STS/confirmation HTTP/1.1
Host: <hostname>
Content-Type: application/json
Authorization: Bearer eyJ0eXAiOiJKV ... tOTZXUVFBdyJ9

{
  "Resource": "urn:cryptopro:dss:signserver:signserver",
    "ClientId": "oauth-client-id",
    "ChallengeResponse" : {
        "ControlChallengeResponse": 
        {
            "RefId": "843e19ea-ca04-46aa-a7fb-112b6a02570f",
            "ControlAction": "Cancel"
        }
  }
}

Дополнительные отображаемые данные

Прикладная система может передать дополнительные сведения об операции, которые она хочет отобразить пользователю. Дополнительные сведения передаются в поле ConfirmationParams первого запроса RequestSecurityToken к конечной точке /v2.0/confirmation.

Поле ConfirmationParams представляет собой словарь, где ключом является имя параметра. Имя параметра должно быть задано в шаблоне сообщения, передаваемого пользователю.

Шаблоны сообщений настраиваются для каждого метода аутентификации и типа операции. Просмотреть список шаблонов можно с помощью команды:

# Полный список шаблонов
Get-IdsFormatterTemplate

# Список шаблонов для выбранного метода аутентификации
Get-IdsFormatterTemplate -Destination MyDssAuth -Recipient User

# Список шаблонов для выбранного типа операции и метода аутентификации
Get-IdsFormatterTemplate -Destination MyDssAuth -Recipient User -EventTypes SecondaryAuthSign

Примечание

Для всех методов аутентификации кроме Аутентификация при помощи мобильного приложения шаблон сообщения представяет собой текст. Для Аутентификация при помощи мобильного приложения представляет собой JSON-объект. Подробное описание шаблона приведено по ссылке.

Подстановочное поле в шаблоне сообщения передается в формате:

краткая форма: {0:ParamName}

полная форма: {0:ParamName:Type:InFormat:OutFormat}

где

• ParamName - имя параметра (ключ словаря ConfirmationParams)
• Type - тип параметра
• InFormat - формат входного значения
• OutFormat - формат исходящего значения

В зависимости от типа поля InFormat, OutFormat могут быть не заполнены.

Возможные значения Type:

Значение	Описание
Default	Подстановочный параметр со значением по умолчанию Значение по умолчанию задается в пареметре OutFormat в кодировке Base64.
SubString	Извлечение подстроки из подстановочного параметра Параметры подстроки передаются в пареметре OutFormat в виде [startIndex],[lenght] в кодировке Base64
Double	Подстановочный параметр для чисел с плавающей запятой Формат входящего значения передается в параметре InFormat в кодировке Base64. Формат исходящего значения передается в параметре OutFormat в кодировке Base64
Date	Подстановочный параметр для времени Формат входящего значения передается в параметре InFormat в кодировке Base64. Формат исходящего значения передается в параметре OutFormat в кодировке Base64
StrFormat	Подстановочный параметр для строк Строка форматирования передается в пареметре OutFormat в виде "sometext1 {0} sometext2" в кодировке Base64. {0} - подстаночное поле для переданного значения.

Примечание

Значения для всех перечисленных в шаблоне подстановочных параметров обязаны быть переданы в словаре ConfirmationParams, либо быть заполнены из параметров операции. Исключение составляют параметры типа Default. Если значение для подстановочного поля типа Default не передано, то значение будет взято из OutFormat. Если значение подстановочного параметра не найдено, то запрос на подтверждение операции завершится с ошибкой.

Пример шаблона с дополнительными параметрами для операции подписи, подтверждаемой в мобильном приложении.

Подробное описание структуры шаблона приведено по ссылке

Получить и сохранить исходный шаблон сообщения для редактивования можно командой:

(Get-IdsFormatterTemplate -Destination MyDssAuth -Recipient User -EventTypes SecondaryAuthSign).Template | out-file C:\tmp\signSdkTemplate.txt

Исходный шаблон имеет вид:

{{
"values": 
    {{"dss": "КриптоПро Ключ","date": "{0:Date}","login": "{0:Login}","certid": "{0:CertificateID}", "sessionid":"{0:SessionId}","optype":"Подпись" }},
"keys": 
    {{"dss": "Сервер ЭП","date": "Время","login": "Логин пользователя","certid":"Идентификатор сертификата","sessionid":"Идентификатор запроса","optype":"Операция"}}
}}

Примечание

Обратите внимание на экранирование {, }.

Добавим в шаблон подстановочное поле с именем OrgName и пустым значением по умолчанию. В поле словарь keys необходимо добавить заголовок для данного поля.

Пример:

"orgnamelabel":"Организация"

в поле values неободимо добавить подстаночное поле для нового параметра OrgName :

Пример:

"orgnamelabel":"{0:OrgName:Default::IA==}"

В примере InFormat не заполняется. В OutFormat задано значение по умолчанию в кодировке Base64.

Измененный шаблон будет иметь вид:

{{
"values": 
    {{"dss": "КриптоПро Ключ","date": "{0:Date}","login": "{0:Login}","certid": "{0:CertificateID}", "sessionid":"{0:SessionId}","optype":"Подпись", "orgnamelabel":"{0:OrgName:Default::IA==}"}},
"keys": 
    {{"dss": "Сервер ЭП","date": "Время","login": "Логин пользователя","certid":"Идентификатор сертификата","sessionid":"Идентификатор запроса","optype":"Операция","orgnamelabel":"Организация"}}
}}

$newTEmplate = Get-Content C:\tmp\signSdkTemplate.txt
$newTEmplate = $newTEmplate -join ""

$templateId = (Get-IdsFormatterTemplate -Destination MyDssAuth -Recipient User -EventTypes SecondaryAuthSign).ID
Set-IdsFormatterTemplate -TemplateID $templateId -Template $newTEmplate
Restart-IdsInstance

Пример

POST /STS/v2.0/confirmation HTTP/1.1
Host: hostname
Content-Type: application/json
Authorization: Bearer eyJ0eXAiOiJKV1 ... h2KHtiahmbw
Content-Length: 279

{
    "ClientId" : "sample_client",
    "Resource": "urn:cryptopro:dss:signserver:SignServer",
    "OperationId": "843e19ea-ca04-46aa-a7fb-112b6a02570f",
    "CallbackUri": "https://hostname2/callbackreciever/callback",
    "ConfirmationParams": {
        "OrgName": "ООО Ландыш",
        "OrgUnit": "Отдел кадров"
    }
}

Пример ошибки формирования шаблона

{
    "IsFinal": true,
    "IsError": true,
    "Error": "authentication_failed",
    "ErrorDescription": "Ошибка при оповещении:\r\nОшибка при форматировании сообщения типа MyDssAuth для события типа SecondaryAuthSign\r\nВложенное сообщение:\r\nInvalid param format: [OrgName::IA==]. ':' expected. ParamName(m):ParamType(o):Base64(InFormat)(o):Base64(OutFormat)(o):"
}

Время жизни операций

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

Для поддержки данного сценария Администратор должен задать максимально допустимое время жизни операций в параметра MaxTransactionLifetime командлетов Get-IdsProperties, Set-IdsProperties.

• Если MaxTransactionLifetime равен 0, то переданное прикладной системой время жизни операции Ttl игнорируется.
• Если MaxTransactionLifetime отличен от 0, то переданное прикладной системой время жизни операции должно быть меньше указанного значения.
• Если прикладная система укажет время жизни операции больше чем MaxTransactionLifetime, то операция будет создана со временем жизни MaxTransactionLifetime.
• Если прикладная система не укажет время жизни операции, то операция будет создана со временем жизни по умолчанию OtpConfirmationTimeOut.

По умолчанию любые операции создаются со временем жизни по умолчанию OtpConfirmationTimeOut.

Настройками сервера должно быть обеспечено условие TokenTimeout > MaxTransactionLifetime. TokenTimeout - время выполнения операции задаваемое на сервисе подписи командлетами Get-SignProperties, Set-SignProperties.

POST /STS/v2.0/confirmation HTTP/1.1
Host: hostname
Content-Type: application/json
Authorization: Bearer eyJ0eXAiOiJKV1 ... h2KHtiahmbw
Content-Length: 279

{
    "ClientId" : "sample_client",
    "Resource": "urn:cryptopro:dss:signserver:SignServer",
    "OperationId": "843e19ea-ca04-46aa-a7fb-112b6a02570f",
    "CallbackUri": "https://hostname2/callbackreciever/callback",
    "Ttl": 3600
}

OAuth 2.0

При создании операции через конечную точку authorize желаемый срок действия передается через параметр запроса dss_transaction_lifetime. Срок действия транзакции указывается в секундах.

Пример

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