Подготовка к выполнению аутентифицированного запроса к API
После создания и настройки учётной записи службы ваше приложение должно выполнить следующие шаги:
- Создать JSON Web Token (JWT), который включает заголовок (header), полезную нагрузку (payload) и подпись (signature);
- Запросить токен доступа (
AccessToken) у платформы аутентификации OAuth2; - Обработать 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-представление заголовка выглядит следующим образом:
{"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 выглядит следующим образом:
{
"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.
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=<jwt>
3 — Обработка ответа платформы аутентификации
Если JWT и запрос токена доступа сформированы правильно, а учётная запись службы имеет необходимые права доступа, платформа аутентификации вернёт JSON-объект, содержащий токен доступа:
{
"access_token": "<access_token>",
"token_type": "Bearer",
"expires_in": "3600"
}
Токен доступа, возвращённый в поле access_token JSON-объекта, также является токеном JWT, который следует использовать в API продуктов Unico. Если при запросе произошла ошибка, проверьте тип ошибки в разделе Ошибки аутентификации.
4 — Срок действия токена доступа
Срок действия токена доступа может изменяться. Его продолжительность указывается в поле expires_in, которое возвращается вместе с токеном доступа. Один и тот же токен доступа следует использовать в течение всего срока его действия для всех вызовов API продуктов.
Не запрашивайте новый токен доступа до тех пор, пока срок действия текущего токена не будет приближаться к истечению. Мы рекомендуем использовать запас в 600 секунд (10 минут):
new Date((token.exp - 600) * 1000)
Где token.exp — это временная метка истечения срока действия токена.
По умолчанию токен, отправлен ный компании, действителен 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)
Не используйте фиксированное время для получения нового токена, так как срок действия полученного токена может быть короче установленного времени, что может привести к сбоям при использовании сервисов.
¹ Согласно RFC 4648 для кодирования BaseN, формат Base64url аналогичен Base64, за исключением того, что символ = опускается, а символы + и / заменяются на - и _ соответственно.
² JSON Web Signature: https://tools.ietf.org/html/rfc7515.