Токены

После успешного входа пользователя приложение получает от Авторизы токены OpenID Connect.

В Авторизе используются три типа токенов:

• ID Token — сообщает, кто именно вошел в приложение;
• Access Token — используется приложением для работы от имени пользователя;
• Refresh Token — позволяет получать новые токены без повторного ввода логина и пароля.

Как приложение получает токены

После успешного входа Авториза не передает токены напрямую через Redirect URI. Вместо этого приложение получает временный код авторизации:

https://app.example.com/callback?code=abc123&state=...

Далее приложение должно отправить этот код в Token Endpoint и обменять его на токены.

Шаг 1. Пользователь проходит вход в Авторизе

Пользователь нажимает кнопку входа в приложении, приложение перенаправляет его в Авторизу, и после успешной аутентификации Авториза вызывает Redirect URI приложения.

Пример callback:

https://app.example.com/callback?code=abc123&state=...

Шаг 2. Приложение обменивает code на токены

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

POST /oidc/token HTTP/1.1
Host: oidc.authoriza.ru
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&
code=abc123&
redirect_uri=https://app.example.com/callback&
client_id=YOUR_CLIENT_ID

В зависимости от типа приложения запрос также может содержать client_secret.

Пример успешного ответа

{
  "id_token": "eyJhbGciOi...",
  "access_token": "eyJhbGciOi...",
  "refresh_token": "def50200...",
  "token_type": "Bearer",
  "expires_in": 3600
}

refresh_token возвращается только если приложение запросило offline_access, и использует grant type refresh_token (можно проверить в Кабинете Разработчика, сейчас по умолчанию grant_type refresh_token выдается всем приложениям).

ID Token

Что это такое

ID Token — это токен, который подтверждает факт успешной аутентификации пользователя.

Он нужен приложению, чтобы понять:

• что пользователь действительно вошел через Авторизу;
• какой профиль пользователя был аутентифицирован;
• какие базовые данные о пользователе были возвращены вместе со входом.

Для чего использовать ID Token

ID Token обычно используется:

• для завершения входа в приложении;
• для получения идентификатора профиля пользователя;
• для чтения базовых данных пользователя, если они включены в claims.

Главное поле в ID Token:

• sub — UUID профиля пользователя в рамках проекта

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

Пример ID Token payload

{
  "sub": "4fb3e1af-6e34-4ef1-b4f0-0f2c2b2d6c65",
  "email": "user@example.com",
  "name": "Иван Иванов",
  "aud": "2386ed26-7474-412c-ba51-d33d574eca07",
  "exp": 1718960000,
  "iat": 1718956400,
  "iss": "https://oidc.authoriza.ru/oidc"
}

Что означают основные поля

Что важно знать про sub

Поле sub в ID Token и Access Token — это UUID профиля, а не внутренний идентификатор пользователя Авторизы. Это уникальный и неизменный идентификатор профиля пользователя для проекта, в котором создано приложение.

Это важно по двум причинам:

1. Email может измениться
2. Один и тот же пользователь может иметь разные профили в разных проектах

Чего не стоит делать с ID Token

Ошибка: использовать ID Token для вызова API клиента

ID Token нужен для подтверждения аутентификации на пользовательском устройстве, а не для доступа к API.

Для запросов к backend API клиента следует использовать Access Token.

Access Token

Что это такое

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

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

Для чего использовать Access Token

Access Token обычно используется:

• при вызове backend API клиента;
• при передаче данных о текущем пользователе между frontend и backend;
• для проверки прав и контекста текущей сессии на стороне ресурсного сервера.

Если backend клиента доверяет токенам Авторизы, он может принимать Access Token как bearer-токен и проверять его подпись, срок действия и claims.

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

Пример Access Token payload

{
  "jti": "c8e4e7f2-5d5f-4e6e-ae1f-6d3d3a1b9d12",
  "sub": "4fb3e1af-6e34-4ef1-b4f0-0f2c2b2d6c65",
  "iat": 1718956400,
  "exp": 1718960000,
  "scope": "openid email profile",
  "client_id": "2386ed26-7474-412c-ba51-d33d574eca07",
  "iss": "https://oidc.authoriza.ru/oidc",
  "aud": "2386ed26-7474-412c-ba51-d33d574eca07"
}

Что означают основные поля

Что важно знать про Access Token

1. Access Token имеет ограниченный срок жизни

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

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

2. Access Token — это токен доступа, а не вечная сессия

Нельзя считать, что если пользователь однажды вошел, то Access Token можно использовать бесконечно.

Если приложение работает с длительными сессиями, ему нужен Refresh Token.

3. Не стоит использовать Access Token как единственное хранилище пользовательских данных

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

Тем более, что для протокола OpenID Connect типичным может являться поведение, когда пользовательские данные меняются. Но до тех пор, пока не будут выпущены новые токены, а будут использоваться старые - часть информации о пользователе в них будет устаревшей. Для получения самой актуальной информации, в чувствительных сценариях, нужно использовать эндпоинт userinfo по протоколу OpenID Connect.

Стабильный идентификатор пользователя для вашего приложения — это sub из токена.

Refresh Token

Что это такое

Refresh Token позволяет получить новый Access Token и новый ID Token без повторного входа пользователя.

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

Когда выдается Refresh Token

Refresh Token выдается не всегда.

Для его получения должны выполняться следующие условия:

1. приложение должно поддерживать grant type refresh_token (в Кабинете Разработчика);
2. в запросе аутентификации должен быть запрошен scope offline_access.

Как запросить Refresh Token

При запуске аутентификации приложение должно запросить scope offline_access.

Пример scopes:

openid profile email offline_access

Как обновить токены

Когда Access Token истек, приложение может отправить запрос в Token Endpoint с grant_type=refresh_token.

Пример:

POST /oidc/token HTTP/1.1
Host: oidc.authoriza.ru
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&
refresh_token=YOUR_REFRESH_TOKEN&
client_id=YOUR_CLIENT_ID

В ответ приложение получает новые токены.

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

{
  "id_token": "eyJhbGciOi...",
  "access_token": "eyJhbGciOi...",
  "refresh_token": "def50200...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Как ведет себя Refresh Token в текущей версии

В текущей конфигурации Авторизы:

• Refresh Token живет 14 дней
• при refresh-запросе выдается новый ID Token и новый Access Token
• сам Refresh Token обычно остается тем же

Иными словами, один и тот же Refresh Token может использоваться многократно до окончания срока действия.

Срок жизни токенов

В текущей конфигурации используются следующие значения:

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

Как читать JWT

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

JWT состоит из трех частей, разделенных точкой:

header.payload.signature

Например:

eyJhbGciOi...eyJzdWIiOi...abc123

Вторая часть (payload) содержит claims токена в формате JSON.

Что можно читать из JWT

Обычно разработчику полезно смотреть на:

• sub — идентификатор профиля пользователя
• exp — срок действия токена
• iat — время выпуска токена
• scope — выданные разрешения
• client_id / aud — для какого приложения выпущен токен

Важно: чтение JWT не заменяет проверку токена

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

Если backend клиента принимает Access Token как bearer-токен, он должен как минимум:

• проверить подпись токена;
• проверить iss;
• проверить aud;
• проверить срок действия (exp).

Подробности о проверке подписи и использовании JWKS см. в разделе OpenID Connect.

Типичные ошибки

1. Использовать email как постоянный идентификатор пользователя

Неправильно:

user_id = email

Правильно:

user_id = sub

sub — это UUID профиля пользователя, и именно он является стабильным идентификатором в рамках проекта.

2. Не учитывать срок жизни Access Token

Access Token живет ограниченное время.

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

3. Не обрабатывать истекший или недействительный Refresh Token

Refresh Token тоже имеет срок действия.

Если refresh-запрос завершился ошибкой, приложение должно быть готово повторно отправить пользователя на вход через Авторизу.

4. Хранить Refresh Token небезопасно

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

Подход к хранению зависит от типа приложения:

• backend / server-side приложение — хранить на сервере;
• SPA — использовать только при понимании рисков;
• мобильное приложение — хранить в защищенном хранилище платформы.

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

Если нужно сохранить пользователя в собственной базе данных клиента, используйте:

sub

Это UUID профиля пользователя в проекте.

Не используйте для этой цели:

• email;
• имя пользователя;
• временные значения из frontend-сессии.