Перевыпуск маркера доступа

Сценарий описывается в разделе 1.5 RFC6749.

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

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

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

Компромиссным решением в такой ситуации является использование т.н. маркера обновления (refresh_token). Маркером обновления называется долговременный маркер безопасности, выпускаемый Центром Идентификации. Он позволяет осуществлять прозрачный для пользователя перевыпуск маркера доступа.

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

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

Запроса маркеров доступа и обновления

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

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

GET https://<hostname>/<stsappname>/oauth/authorize?response_type=code&scope=dss+offline_access&redirect_uri=urn:ietf:wg:oauth:2.0:oob:auto&resource=urn:cryptopro:dss:signserver:signserver&client_id=TestClient HTTP/1.1
cache-control: no-cache
Accept: */*
accept-encoding: gzip, deflate
Connection: close

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

client_id - идентификатор клиента OAuth, зарегистрированный на ЦИ DSS. Для регистрации клиента и его последующей конфигурации можно воспользоваться командлетами Windows PowerShell Add-DssClient и Set-DssClient соответственно.

Примечание

При регистрации клиента параметр AllowedFlow должен содержать значение AuthorizationCode.

Примечание

Для включения возможности получения маркера обновления используется параметр -AllowedFlow RefreshToken. (В версиях КриптоПро DSS 2882 и более ранних данный параметр назывался –AllowOfflineAccess).

Параметр используется только в Исполнениях «DSS + myDSS», «DSS SDK» и «DSS Client SDK», «DSS + AirKey Lite».

response_type - в данном сценарии имеет значение code.
scope - области использования маркера. Должен содержать значение dss, а также значение offline_access, сообщающее ЦИ о необходимости включения маркера обмена при выдаче маркера доступа.
redirect_uri - зарегистрированный на Центре Идентификации адрес возврата (по этому адресу будет возвращён запрошенный код авторизации).

Примечание

Значение параметра должно соответствовать значению адреса возврата, заданного при регистрации клиента на ЦИ.

Для случаев, в которых не планируется использование выделенного HTTP-сервиса для обработки URI перенаправления, рекомендуется использовать зарезервированный URI urn:ietf:wg:oauth:2.0:oob:auto.

resource - идентификатор ресурса, для доступа к которому выпускается токен. В случае Сервиса Подписи идентификатор фиксирован и имеет вид urn:cryptopro:dss:signserver:<signserverAppName>.

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

Параметр client_id в теле запроса должен был заменен на заголовок Auhtorization HTTP-запроса, имеющий значение Basic Base64(client_id:client_secret).

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

После успешной аутентификации ЦИ сформирует следующий ответ, который отправит на redirect_uri:

HTTP/1.1 302 Found
Location: urn:ietf:wg:oauth:2.0:oob:auto#code=c86322fd3a4cf85fb51249ab3fb4fcd1
Content-Length: 0

Параметр code (стоящий после символа #) содержит код авторизации, который необходимо извлечь из заголовка Location.

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

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

Для получения маркера доступа используется конечная точка /token. Клиент формирует следующий HTTP-запрос:

POST https://<hostname>/<stsappname>/oauth/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded
cache-control: no-cache
Accept: */*
content-length: 139

grant_type=authorization_code&code=9e554074113426cb2f4430f51b68170a&redirect_uri=urn:ietf:wg:oauth:2.0:oob:auto&client_id=sample&scope=offline_access

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

grant_type - в данном сценарии имеет значение authorization_code.
code - код авторизации, полученный на предыдущем этапе.
redirect_uri - зарегистрированный на Центре Идентификации адрес возврата (по этому адресу будет возвращён запрошенный код авторизации).
scope - области использования маркера. Должен содержать значение offline_access, сообщающее ЦИ о необходимости включения маркера обмена при выдаче маркера доступа.

Примечание

client_id - идентификатор клиента OAuth, зарегистрированный на ЦИ DSS.

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

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

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

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

Внимание!

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

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

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

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

{
    "access_token":"eyJ0eXAiOiJKV1Q ... LnS1sAunDSE1hh3A5n8W7lhPSM4z_VA",
    "expires_in":300,
    "token_type":"Bearer",
    "refresh_token": "774fae55a7e64c8238c35695c4198198"
}

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

Пример сообщения об ошибке

HTTP/1.1 400 Bad Request
Cache-Control: no-cache
Pragma: no-cache
Expires: -1
Date: Fri, 21 Dec 2018 13:46:42 GMT
Connection: close

{"error":"invalid_client"}

Запрос перевыпуска маркера доступа

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


POST http://<hostname>/<stsappname>/oauth/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded
accept-encoding: gzip, deflate
content-length: 92
Connection: keep-alive

grant_type=refresh_token&client_id=TestClient&refresh_token=774fae55a7e64c8238c34995c4198198

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

grant_type - в данном сценарии имеет значение refresh_token.
refresh_token - маркер обмена, полученный от Центра Идентификации.
client_id - идентификатор клиента OAuth, зарегистрированный на ЦИ DSS.

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

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

{
    "access_token":"eyJ0eXAiOiJKV1Q ... LnS1sAunDSE1hh3A5n8W7lhPSM4z_VA",
    "expires_in":300,
    "token_type":"Bearer",
    "refresh_token": "774fae55a7e64c8238c35695c4198198"
}

Маркер обновления и вторичная аутентификация

Использование маркера обновления позволяет пропускать аутентификацию пользователя (в т.ч. и вторичную) при получении маркера доступа через конечную точку 'oauth/token', при этом подтверждение операций, требующих доступ к ЗК, а также подтверждение произвольных операций всё равно будет требовать использования одного из методов вторичной аутентификации.