Токены

После успешного входа Авториза возвращает приложению данные и токены, которые позволяют приложению понять, кто вошёл, и при необходимости обращаться к защищённым API.

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

При использовании SDK для фронтенда получение, хранение и обновление токенов выполняются SDK автоматически.

ID Token

ID Token — это токен OpenID Connect, который сообщает приложению результат аутентификации пользователя.

Он содержит идентификатор пользователя и другие данные, доступные приложению в соответствии с запрошенными scopes.

Пример:

{
  "sub": "4fb3e1af-6e34-4ef1-b4f0-0f2c2b2d6c65",
  "email": "user@example.com",
  "name": "Иван Иванов"
}

Основные поля

sub — идентификатор пользователя

Основным идентификатором пользователя внутри проекта является значение sub.

Например:

{
  "sub": "4fb3e1af-6e34-4ef1-b4f0-0f2c2b2d6c65"
}

Это идентификатор профиля пользователя в конкретном проекте, а не глобальный идентификатор пользователя Авторизы.

Один человек может иметь разные профили в разных проектах:

Пользователь
    │
    ├── Профиль проекта A → sub = ABC
    │
    └── Профиль проекта B → sub = XYZ

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

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

• пользователь может изменить email;
• email может отсутствовать в полученных данных;
• разные проекты получают разные профили одного пользователя.

Важно: ID Token предназначен для передачи приложению информации о пользователе. Для доступа к защищённому API используется Access Token.

Access Token

Access Token используется, когда приложение должно обратиться к защищённому API от имени пользователя.

Обычно он передаётся в HTTP-запросе:

Authorization: Bearer ACCESS_TOKEN

Сервер API должен проверить полученный токен перед тем, как предоставить доступ.

В текущей версии Авторизы Access Token имеет формат JWT.

Важно: Access Token также содержит значение sub, чтобы API могло его использовать для идентификации.

Что проверяет API

Сервер, принимающий Access Token, должен проверить как минимум:

• подпись токена;
• iss — источник токена;
• aud — для какого приложения или API предназначен токен;
• exp — срок действия токена.

Простого декодирования JWT недостаточно.

Например, получить содержимое JWT можно без знания ключа подписи, поэтому само наличие правильных claims ещё не означает, что токен настоящий.

Важное ограничение

Access Token, выданный вашему приложению, предназначен для доступа к API, для которого этот токен был выдан.

Он не предназначен для вызова внутренних API Авторизы.

Срок действия Access Token

В текущей конфигурации Access Token действует 1 час.

После истечения срока действия приложение может:

1. получить новый токен с помощью Refresh Token;
2. если Refresh Token недействителен — запустить повторную авторизацию.

SDK выполняет эту работу автоматически.

Refresh Token

Refresh Token позволяет приложению получить новый Access Token, не заставляя пользователя снова вводить данные для входа.

Refresh Token используется, когда Access Token истёк или скоро истечёт.

Для получения Refresh Token приложение должно запросить scope:

offline_access

Как это работает

Access Token
    │
    │ истёк
    ▼
Refresh Token
    │
    │ запрос нового токена
    ▼
Авториза
    │
    ▼
Новый Access Token

В текущей конфигурации Refresh Token действует 14 дней.

Если Refresh Token истёк или стал недействительным, приложение должно выполнить повторную авторизацию пользователя.

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

Что важно запомнить

В текущей конфигурации Authoriza срок действия Authorization Code составляет 10 минут, ID Token и Access Token — 1 час, Refresh Token — 14 дней. Эти значения могут измениться.

Authorization Code используется один раз. Access Token передаётся только тому API, для которого он выпущен. ID Token используется приложением для идентификации пользователя, а не как замена Access Token.

Для подробного объяснения scopes и выбора минимального набора перейдите к статье Scopes. Устройство JWT, проверка подписи и JWKS разобраны в статье о JWT и JWKS. Значение sub и связь с профилем описаны в основных концепциях.

Хранение токенов

Для Confidential-приложения предпочтительна серверная сессия. В SPA токены требуют отдельной оценки XSS-рисков. Не передавайте токены в query string, не выводите их в логи и не храните credentials в репозитории.

SDK Authoriza хранит сессию, получает Access Token и выполняет refresh при необходимости. Подробности API SDK находятся в руководстве по SDK. При использовании другой OIDC-библиотеки следуйте её модели хранения и обновления токенов.

Следующий шаг

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