--- title: Подготовка к выполнению аутентифицированного запроса к API description: Как сформировать и подписать JWT, запросить токен доступа у платформы OAuth2 и обработать ответ с токеном и его срок действия. canonical: https://developer.unico.io/ru/dual-api/developers/regional-solutions/card-not-present-verification/integration/authentication/preparing-authenticated-request locale: ru generated_by: markdown-export --- После создания и настройки учётной записи службы ваше приложение должно выполнить следующие шаги: 1. Создать JSON Web Token (JWT), который включает заголовок (header), полезную нагрузку (payload) и подпись (signature); 2. Запросить токен доступа (`AccessToken`) у платформы аутентификации OAuth2; 3. Обработать JSON-ответ, который вернёт платформа аутентификации. Если ответ содержит токен доступа, вы можете использовать его для выполнения запросов к API продуктов Unico, к которым учётная запись службы имеет права доступа. (Если ответ не содержит токена доступа, возможно, ваш JWT и запрос токена сформированы неверно, либо учётная запись службы не имеет необходимых прав доступа к запрашиваемым ресурсам.) Токен доступа, сгенерированный в упомянутом выше запросе, по умолчанию действителен в течение 3600 секунд, но это значение может отличаться в зависимости от настроек безопасности, установленных для вашей компании. Когда срок действия токена доступа истекает, ваше приложение должно сгенерировать новый JWT, подписать его и запросить новый токен доступа у платформы аутентификации. ### 1 — Создание JWT JWT состоит из трёх частей: **заголовка** (header), **полезной нагрузки** (payload) и **подписи** (signature). Заголовок и полезная нагрузка являются JSON-объектами. Эти JSON-объекты сериализуются в UTF-8, а затем кодируются с использованием кодировки **Base64url**¹. Такое кодирование обеспечивает устойчивость к изменениям кодирования при повторных операциях кодирования. Заголовок, полезная нагрузка и подпись объединяются с помощью символа точки (`.`). JWT формируется следующим образом: ``` {Header in Base64url}.{Payload in Base64url}.{Signature in Base64url} ``` Базовый текст для подписи формируется следующим образом: ``` {Header in Base64url}.{Payload in Base64url} ``` #### 1.1 — Формирование заголовка JWT Заголовок состоит из двух полей, которые определяют алгоритм подписи и формат токена. Оба поля обязательны, и каждое поле имеет только одно значение. Учётные записи служб используют алгоритм RSA SHA-256 и формат токена JWT. Таким образом, JSON-представление заголовка выглядит следующим образом: ```json {"alg":"RS256","typ":"JWT"} ``` Представление в Base64url выглядит следующим образом: ``` eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9 ``` #### 1.2 — Формирование полезной нагрузки JWT Полезная нагрузка JWT содержит информацию о JWT, включая запрашиваемые права доступа (scopes), учётную запись, запрашивающую доступ, издателя, время выдачи токена и срок его действия. Большинство полей обязательны. Как и заголовок JWT, полезная нагрузка представляет собой JSON-объект и используется при формировании подписи. #### 1.3 — Обязательные поля Обязательные поля JWT приведены в таблице ниже. Они могут располагаться в любом порядке внутри полезной нагрузки. | Название | Описание | |---|---| | `iss` | Идентификатор учётной записи службы внутри компании. | | `scope` | Список прав доступа, запрашиваемых приложением, разделённый пробелами или знаком плюс (`+`). Если требуются все права доступа учётной записи, используйте для этого символ звёздочки (`*`). | | `aud` | Адрес платформы аутентификации, выдающей токены доступа. Это значение всегда должно быть точно `https://identityhomolog.acesso.io`. Распространённые ошибки, которые **не работают**: добавление завершающего слэша (`https://identityhomolog.acesso.io/`) или использование HTTP вместо HTTPS. | | `exp` | Время истечения срока действия токена, указанное в секундах с 00:00:00 UTC 1 января 1970 года. Это значение имеет максимальную длительность 1 час с момента выдачи JWT. Оно должно быть **числовым** — значение в кавычках, например `"1524161193"`, является строкой и не будет работать; `1524161193` — это число, и оно будет работать. | | `iat` | Время выдачи JWT, указанное в секундах с 00:00:00 UTC 1 января 1970 года. Это значение должно быть **числовым**, по тому же правилу, что и `exp`. | Поле `iat` должно отражать текущее время в требуемом формате, а поле `exp` должно соответствовать следующему расчёту: ``` exp = iat + 3600 ``` Представление обязательных JSON-полей в полезной нагрузке JWT выглядит следующим образом: ```json { "iss": "service_account_name@tenant_id.iam.acesso.io", "aud": "https://identityhomolog.acesso.io", "scope": "*", "exp": 1626296976, "iat": 1626293376 } ``` #### 1.4 — Вычисление подписи Спецификация **JSON Web Signature (JWS)**² — это механизм, определяющий расчёт подписи для JWT. Входными данными для расчёта подписи является массив байтов следующего содержимого: ``` {Header in Base64url}.{Payload in Base64url} ``` Для вычисления подписи необходимо использовать тот же алгоритм, который указан в заголовке JWT. Единственный алгоритм подписи, поддерживаемый платформой аутентификации OAuth2, — это RSA с использованием SHA-256, обозначаемый как `RS256` в поле `alg` заголовка JWT. Подпишите представление входного содержимого в UTF-8 с помощью SHA256withRSA (также известного как RSASSA-PKCS1-V1_5-SIGN с хеш-функцией SHA-256), используя приватный ключ, который был создан и связан с учётной записью службы (файл `.key.pem`, сгенерированный по запросу, полученному по электронной почте). Результатом будет массив байтов. Затем подпись необходимо закодировать в Base64url. Заголовок, полезную нагрузку и подпись следует объединить символом точки. Результатом является JWT. Также можно использовать готовые библиотеки для создания JWT. В качестве справочного материала список библиотек можно найти на сайте [jwt.io](https://jwt.io/). ### 2 — Выполнение запроса токена доступа После генерации подписанного JWT приложение может использовать его для запроса токена доступа. Запрос токена доступа представляет собой POST HTTPS-запрос, тело которого должно быть закодировано в формате URL. URL приведён ниже: ``` https://identityhomolog.acesso.io/oauth2/token ``` В POST HTTPS-запросе обязательны следующие параметры: | Название | Описание | |---|---| | `grant_type` | Используйте следующий текст, закодированный в формате URL при необходимости: `urn:ietf:params:oauth:grant-type:jwt-bearer` | | `assertion` | JWT, включая подпись. | ``` POST /oauth2/token HTTP/1.1 Host: identityhomolog.acesso.io Content-Type: application/x-www-form-urlencoded grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer&assertion= ``` ### 3 — Обработка ответа платформы аутентификации Если JWT и запрос токена доступа сформированы правильно, а учётная запись службы имеет необходимые права доступа, платформа аутентификации вернёт JSON-объект, содержащий токен доступа: ```json { "access_token": "", "token_type": "Bearer", "expires_in": "3600" } ``` Токен доступа, возвращённый в поле `access_token` JSON-объекта, также является токеном JWT, который следует использовать в API продуктов Unico. Если при запросе произошла ошибка, проверьте тип ошибки в разделе [Ошибки аутентификации](./additional-resources/authentication-errors). ### 4 — Срок действия токена доступа Срок действия токена доступа может изменяться. Его продолжительность указывается в поле `expires_in`, которое возвращается вместе с токеном доступа. Один и тот же токен доступа следует использовать в течение всего срока его действия для всех вызовов API продуктов. **Не запрашивайте новый токен доступа до тех пор, пока срок действия текущего токена не будет приближаться к истечению.** Мы рекомендуем использовать запас в 600 секунд (10 минут): ``` new Date((token.exp - 600) * 1000) ``` Где `token.exp` — это временная метка истечения срока действия токена. :::note По умолчанию токен, отправленный компании, действителен 1 час, но это можно изменить. Рекомендуется всегда использовать `expires_in` в качестве основы и вычитать из него 600 секунд, чтобы запросить новый токен. ::: **Примеры:** ``` Стандартный сценарий: expires_in: 3600 (1ч) — токен сгенерирован в 14:42 Запрашивайте новый токен только в 15:32, то есть 14:42 + (3600 - 600) ``` ``` Сценарий с изменённой продолжительностью: expires_in: 7200 (2ч) — токен сгенерирован в 14:42 Запрашивайте новый токен только в 16:32, то есть 14:42 + (7200 - 600) ``` :::warning **Не используйте фиксированное время для получения нового токена, так как срок действия полученного токена может быть короче установленного времени, что может привести к сбоям при использовании сервисов.** ::: --- ¹ Согласно RFC 4648 для кодирования BaseN, формат Base64url аналогичен Base64, за исключением того, что символ `=` опускается, а символы `+` и `/` заменяются на `-` и `_` соответственно. ² JSON Web Signature: [https://tools.ietf.org/html/rfc7515](https://tools.ietf.org/html/rfc7515).