id_token - это JWT-токен OpenID Connect, который подтверждает факт входа пользователя в REGOS. Он нужен приложению, чтобы понять, кто вошел, и безопасно принять результат авторизации. Для вызова API используйте access_token; id_token предназначен именно для проверки входа и чтения публичных данных, которые были разрешены scope.
id_token появляется в ответе /oauth/token, если при авторизации был выдан scope openid. Если scope openid не был выдан, id_token не формируется.
Перед использованием токена приложение должно проверить его. Минимальная проверка выглядит так: нужно проверить подпись по публичным ключам REGOS из /jwks.json, убедиться, что iss соответствует адресу REGOS, aud равен вашему client_id, срок действия exp еще не истек, а nonce совпадает с тем значением, которое приложение отправляло на /oauth/authorize, если nonce использовался. Большинство OpenID Connect библиотек делают эти проверки автоматически, если им передать адрес /.well-known/openid-configuration.
После проверки можно читать поля токена. Базовые поля приходят в каждом id_token:
| Поле | Что означает |
|---|---|
iss |
Адрес сервиса REGOS, который выпустил токен. |
aud |
Идентификатор приложения, для которого выпущен токен. |
sub |
Публичный идентификатор пользователя. |
sid |
Идентификатор пользовательской сессии. |
iat |
Время выпуска токена в Unix time. |
exp |
Время окончания действия токена в Unix time. |
auth_time |
Время входа пользователя в Unix time. |
nonce |
Значение из запроса авторизации, если приложение его передавало. |
Дополнительные поля зависят от scope. Если был выдан scope email, в токене могут быть email и email_verified. Если был выдан scope phone, могут быть phone_number и phone_number_verified.
Scope profile добавляет публичные данные профиля: given_name, family_name, company, picture, gender, birthdate, country_code, timezone, language_code и telegram_chat_id. Поле gender возвращается как male или female; если пользователь не указал пол, значение будет пустым. Поле birthdate возвращается в формате YYYY-MM-DD; если дата рождения не указана, значение будет пустым.
Если был выдан scope roles, в токене могут быть значения roles. Используйте их только для тех решений, которые согласованы для вашей интеграции. Для критичных серверных проверок доступа лучше дополнительно проверять права на своей backend-стороне.
Пример расшифрованного payload id_token при scopes openid profile email:
{
"iss": "https://auth.regos.uz",
"aud": "your_client_id",
"sub": "user_identifier",
"sid": "session_identifier",
"iat": 1768550400,
"exp": 1768551000,
"auth_time": 1768550400,
"email": "user@example.com",
"email_verified": true,
"given_name": "Ali",
"family_name": "Valiyev",
"company": "Example",
"picture": "https://example.com/avatar.png",
"gender": "male",
"birthdate": "1995-04-23",
"country_code": "UZ",
"timezone": "Asia/Tashkent",
"language_code": "ru",
"telegram_chat_id": "123456789"
}Не полагайтесь на то, что все дополнительные поля всегда есть и всегда заполнены. Пользователь может не указать часть данных, а приложение может получить не все scope. Проверяйте наличие поля перед использованием и спокойно обрабатывайте пустые значения.