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

Примечание

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

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

Перед началом интеграции Администратору DSS необходимо:

  • Выпустить и зарегистрировать на DSS cертификат аутентификации Оператора DSS
  • Зарегистрировать OAuth-клиента

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

  1. Инициация аутентификации.
  2. Получение кода авторизации.
  3. Получение маркера доступа Оператора.
  4. Получение делегирующего маркера доступа.

Инициация аутентификации

Данный шаг заключается в отправке GET-запроса на аутентификацию на конечную точку /authorize/certificate. Примера запроса представлен ниже.

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

https://<hostname>/<stsappname>/oauth/authorize/certificate?client_id=sample&response_type=code&scope=dss&redirect_uri=urn:ietf:wg:oauth:2.0:oob:auto&resource=urn:cryptopro:dss:signserver:signserver

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

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

При регистрации клиента параметр AllowedFlow должен включать в себя разрешения AuthorizationCode и ResourceOwner.

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

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

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

  • resource - идентификатор ресурса, для доступа к которому выпускается токен.

Получение кода авторизации

В случае успешной аутентификации

  • ответ сервера будет иметь статус HTTP 302
  • В заголовке Location будет содержаться код авторизации

В примере используется специальное значение redirect_uri, клиенту необходимо из заголовка Location извлечь значение параметра code. Значение параметра code будет использовано для получения AccessToken на следующем шаге.

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

HTTP/1.1 302 Found
Cache-Control: no-cache
Pragma: no-cache
Expires: -1
Location: urn:ietf:wg:oauth:2.0:oob:auto?code=65e4322a9751cf9ba43012692ce02ec1
Date: Fri, 07 Sep 2018 10:30:24 GMT
Content-Length: 0

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

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

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

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

POST https://<hostname>/<stsappname>/oauth/token HTTP/1.1
cache-control: no-cache

grant_type=authorization_code&code=e1b74adb33d77c51bf0f9121b8b88662&redirect_uri=urn:ietf:wg:oauth:2.0:oob:auto&client_id=sample

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

  • grant_type - в данном сценарии имеет значение authorization_code.
  • code - код авторизации, полученный на предыдущем этапе.
  • redirect_uri - зарегистрированный на Центре Идентификации адрес возврата (по этому адресу будет возвращен запрошенный код авторизации).
Примечание

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

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

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

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

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

Примечание

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

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

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

Также необходимо указать операторский сертификат в качестве клиентского SSL/TLS сертификата, по нему будет осуществляться аутентификация оператора на ЦИ.

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

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

Для получения AccessToken для делегирования используется конечная точка oauth/token. Подробная информация по протоколу получения AccessToken для делегирования: OAuth 2.0 Token Exchange.

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

  • grant_type - тип разрешения, в данном сценарии равен urn:ietf:params:oauth:grant-type:token-exchange.
  • resource – идентификатор Сервиса Подписи.
  • actor_token - Маркер доступа, полученный на предыдущем шаге
  • actor_token_type – тип маркера доступа, должен иметь значение urn:ietf:params:oauth:token-type:jwt.
  • subject_token_type – тип маркера доступа, должен иметь значение urn:ietf:params:oauth:token-type:jwt.
  • subject_token – неподписанный JWT-токен, содержащий логин управляемого пользователя.

В декодированном виде subject_token имеет вид:

{
    "alg": "none",
    "typ": "JWT"
}.
{
    "unique_name": "mydss",
    "nbf": 1488312889,
    "exp": 1488316489,
    "iat": 1488312889
}
.

Пример кодирования JWT-токена можно посмотреть по ссылке.

Первая часть (до точки) называется header, вторая – payload. Для получения закодированного значения необходимо выполнить следующее преобразование: 

Base64UrlEncode(Utf8GetBytes(header)) + “.” + Base64UrlEncode(Utf8GetBytes(payload)) + “.”
Примечание

Поле unique_name должно содержать логин пользователя, для которого осуществляется делегация прав.

Поля nbf, exp и iat представляют из себя даты в формате Unix Epoch и задают дату начала действия токена, дату истечения срока действия и дату подписания токена соответственно.

Внимание!

Символ “.” в конце получившегося значения является обязательным.

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

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

POST https://<hostname>/<stsappname>/oauth/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Authorization: Basic c2FtcGxlOg==

accept-encoding: gzip, deflate
content-length: 2908

grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Atoken-exchange&resource=urn%3Acryptopro%3Adss%3Asignserver%3Asignserver&actor_token=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Im5mNzJaMkE4VnJqWUZjQkVSLW9ycm9GNWpTcyJ9.eyJ1bmlxdWVfbmFtZSI6ImFkbWluIiwibmFtZWlkIjoiNGYyZjc2OTktODBkMS00YmQwLWIxZWEtNjQ4MWE2NjIyZjJhIiwiZHNzX2lzcyI6InJlYWxzdHMiLCJkc3NfdXVpZCI6IlN1WGNDS3lGUjFBVUVPWWtnbWhycW1qZ3BFND0iLCJodHRwOi8vZHNzLmNyeXB0b3Byby5ydS9pZGVudGl0eS9jbGFpbXMvZGlzcGxheW5hbWUiOiJhZG1pbiIsImh0dHA6Ly9zY2hlbWFzLnhtbHNvYXAub3JnL3dzLzIwMDUvMDUvaWRlbnRpdHkvY2xhaW1zL3g1MDBkaXN0aW5ndWlzaGVkbmFtZSI6IkNOPURTU0FkbWluIiwicm9sZSI6IkFkbWlucyIsImh0dHA6Ly9kc3MuY3J5cHRvcHJvLnJ1L2lkZW50aXR5L2NsYWltcy9hY3Rpb24vaXNzdWUiOiJ0ZmE6ZmFsc2UiLCJodHRwOi8vZHNzLmNyeXB0b3Byby5ydS9pZGVudGl0eS9jbGFpbXMvYWN0aW9uL3NpZ25kb2N1bWVudCI6InRmYTpmYWxzZSIsImh0dHA6Ly9kc3MuY3J5cHRvcHJvLnJ1L2lkZW50aXR5L2NsYWltcy9hY3Rpb24vc2lnbmRvY3VtZW50cyI6InRmYTpmYWxzZSIsImh0dHA6Ly9kc3MuY3J5cHRvcHJvLnJ1L2lkZW50aXR5L2NsYWltcy9hY3Rpb24vZGVjcnlwdGRvY3VtZW50IjoidGZhOmZhbHNlIiwiaHR0cDovL2Rzcy5jcnlwdG9wcm8ucnUvaWRlbnRpdHkvY2xhaW1zL2FjdGlvbi9jcmVhdGVyZXF1ZXN0IjoidGZhOmZhbHNlIiwiaHR0cDovL2Rzcy5jcnlwdG9wcm8ucnUvaWRlbnRpdHkvY2xhaW1zL2FjdGlvbi9jaGFuZ2VwaW4iOiJ0ZmE6ZmFsc2UiLCJodHRwOi8vZHNzLmNyeXB0b3Byby5ydS9pZGVudGl0eS9jbGFpbXMvYWN0aW9uL3JlbmV3Y2VydGlmaWNhdGUiOiJ0ZmE6ZmFsc2UiLCJodHRwOi8vZHNzLmNyeXB0b3Byby5ydS9pZGVudGl0eS9jbGFpbXMvYWN0aW9uL3Jldm9rZWNlcnRpZmljYXRlIjoidGZhOmZhbHNlIiwiaHR0cDovL2Rzcy5jcnlwdG9wcm8ucnUvaWRlbnRpdHkvY2xhaW1zL2FjdGlvbi9ob2xkY2VydGlmaWNhdGUiOiJ0ZmE6ZmFsc2UiLCJodHRwOi8vZHNzLmNyeXB0b3Byby5ydS9pZGVudGl0eS9jbGFpbXMvYWN0aW9uL3VuaG9sZGNlcnRpZmljYXRlIjoidGZhOmZhbHNlIiwiaHR0cDovL2Rzcy5jcnlwdG9wcm8ucnUvaWRlbnRpdHkvY2xhaW1zL2FjdGlvbi9kZWxldGVjZXJ0aWZpY2F0ZSI6InRmYTpmYWxzZSIsImh0dHA6Ly9kc3MuY3J5cHRvcHJvLnJ1L2lkZW50aXR5L2NsYWltcy9hY3Rpb24vcHJpdmF0ZWtleWFjY2VzcyI6InRmYTpmYWxzZSIsImRzc19ncm91cCI6IkRlZmF1bHQiLCJodHRwOi8vZHNzLmNyeXB0b3Byby5ydS9pZGVudGl0eS9jbGFpbXMvYWNjZXNzcG9saWN5IjoiMCIsImNlcnR0aHVtYnByaW50IjoiMzUwMUQ0MzUzRjg2N0JGMzU3NDZERDU4MkFCNTJBRDk1RDI1MTVBMyIsImh0dHA6Ly9kc3MuY3J5cHRvcHJvLnJ1L2lkZW50aXR5L2NsYWltcy9nb3N0LXRodW1icHJpbnQiOiJ1SFlPa055eGx1L3YwOUhPL2NTeVpXcmdScnlMcEx2QUoyMWpjY3N2NG9nPSIsImlzcyI6InJlYWxzdHMiLCJleHAiOjE1NDUyMjAyODgsIm5iZiI6MTU0NTIxOTk4OH0.d39MW4POiItKwStWHQg_y1wInPaDy4TzLYfaLeZDgIqv3uEG4MJc11sA8va5aJxiIwxBkkdXYKwmHs1em0kJ30OhsEJxFKkaYe8T9iBV93DlCAyoI_r6Oy9CO06-7I936uCQ0vBNEdk0-qg-iT4STK_qpHtPhTIlloN0kjGjNDKyvRhH8wUDjz_08j3MfQ4B31QGuz81K70rM_G4l3DmckTvi7TG6n_PVm1VUqxCyyYqpID7NmeJ6RoLjv-axKrk1Zl3J3q6aIbcuWlRrnsq6VP0j1ok4EXOVtR1ak57GUZHu3EMs9WxiZmvOMKqeTyHmsLpF-fIznS0lCdj0byGFA&actor_token_type=urn%3Aietf%3Aparams%3Aoauth%3Atoken-type%3Ajwt&subject_token_type=urn%3Aietf%3Aparams%3Aoauth%3Atoken-type%3Ajwt&subject_token=ewogICAgImFsZyI6ICJub25lIiwKICAgICJ0eXAiOiAiSldUIgp9.ewogICAgInVuaXF1ZV9uYW1lIjogIlRlc3QxIiwKICAgICJuYmYiOiAxNTQ1MDU2ODc2LAogICAgImV4cCI6IDE1NzY3NjU2NzYsCiAgICAiaWF0IjogMTU0NTIyOTY3Ngp9.

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

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

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

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

HTTP/1.1 200 OK
Cache-Control: no-cache
Pragma: no-cache
Content-Length: 2704
Content-Type: application/json; charset=utf-8
Expires: -1
Date: Wed, 19 Dec 2018 11:46:31 GMT
Connection: close

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