OpenID Connect

OpenID Connect (OIDC) — слой идентификации поверх OAuth 2.0. Он добавляет стандартный способ сообщить приложению, кто прошёл аутентификацию.

Стандарт

OIDC использует OAuth 2.0 для получения токенов и добавляет:

• scope openid;
• ID Token;
• стандартные claims, включая sub, iss, aud и exp;
• discovery-документ с параметрами провайдера.

OAuth 2.0 отвечает на вопрос «можно ли получить доступ», а OIDC — на вопрос «кто пользователь».

Практика

Приложение выбирает OIDC-библиотеку или SDK, указывает issuer и client ID, запускает Authorization Code Flow и проверяет ID Token. Формат токенов нельзя проверять только декодированием: подпись и claims должны быть валидированы библиотекой. Если термины JWT и JWKS пока незнакомы, сначала прочитайте об устройстве и проверке JWT.

Почему OAuth недостаточно для входа

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

OIDC решает эту задачу через ID Token. В нём находятся claims, описывающие субъект, issuer и срок действия токена. Приложение проверяет токен и использует sub как стабильный идентификатор пользователя в своём контексте.

Что такое discovery

OIDC discovery — механизм, с помощью которого приложение получает настройки провайдера из одного стандартного документа. Вместо ручного поиска authorization endpoint, token endpoint и ключей подписи разработчик указывает только issuer. Библиотека добавляет к нему путь discovery и загружает конфигурацию.

Issuer — базовый URL, однозначно обозначающий провайдера. Он не равен просто адресу сайта: значение issuer должно совпадать с claim iss внутри ID Token. Если приложение настроено на другой issuer, токен нужно отклонить, даже если его подпись технически корректна.

Для Authoriza базовый issuer имеет вид:

https://oidc.authoriza.ru/oidc

Проверять конкретные значения endpoint следует по актуальному discovery-документу, а не переносить их из чужого примера.

Что находится в discovery document

Discovery document — обычный JSON-документ. В нём, в зависимости от возможностей провайдера, находятся поля:

• issuer — точное значение issuer;
• authorization_endpoint — куда отправлять браузер для входа;
• token_endpoint — куда отправлять authorization code;
• jwks_uri — где получить публичные ключи для проверки JWT;
• response_types_supported — поддерживаемые типы ответа;
• grant_types_supported — поддерживаемые способы обмена;
• scopes_supported — известные scopes;
• id_token_signing_alg_values_supported — алгоритмы подписи ID Token.

Не каждое поле обязательно для любого провайдера. Клиент должен использовать фактический документ и возможности библиотеки, а не предполагать наличие endpoint по названию.

Как посмотреть discovery вручную

Для диагностики discovery document можно открыть в браузере по адресу:

https://oidc.authoriza.ru/oidc/.well-known/openid-configuration

или получить его HTTP-запросом:

curl https://oidc.authoriza.ru/oidc/.well-known/openid-configuration

В ответе найдите как минимум issuer, authorization_endpoint, token_endpoint и jwks_uri. Сравните issuer из JSON с тем, который задан в приложении. Discovery содержит публичную конфигурацию, но это не делает client secret и токены публичными.

Как discovery использует библиотека

При создании OIDC-клиента библиотека обычно выполняет такую последовательность:

1. получает issuer из конфигурации;
2. строит discovery URL;
3. загружает JSON и проверяет поле issuer;
4. берёт из него authorization и token endpoint;
5. при проверке JWT использует jwks_uri;
6. кэширует конфигурацию на разумный срок;
7. обновляет её при необходимости, например после ротации ключей.

SDK Authoriza выполняет discovery самостоятельно. При ручной интеграции проверьте, что выбранная библиотека умеет discovery, проверку issuer и обновление JWKS.

Что делать при ошибке discovery

Проверьте:

• issuer не содержит лишний завершающий slash или неправильный path;
• discovery URL доступен из среды, где выполняется код;
• сертификат и HTTPS корректны в production;
• JSON возвращается без HTML-страницы ошибки;
• issuer внутри документа совпадает с настройкой;
• reverse proxy не изменяет схему или host.

Ошибка discovery на старте означает, что клиент ещё не знает, куда отправлять пользователя и где получать токены. Не заменяйте endpoint случайными URL из другого окружения.

ID Token не является Access Token

Оба токена могут быть JWT и содержать похожие claims, но назначение различается. ID Token читается OIDC-клиентом как результат входа. Access Token предъявляется resource server. Если API принимает любой JWT без проверки назначения, один токен можно случайно использовать не в том месте.

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

• использовать OAuth-библиотеку без включения scope openid и ожидать ID Token;
• доверять email как постоянному идентификатору вместо sub;
• проверять только срок действия, но не подпись и issuer;
• вручную задавать endpoint, хотя приложение уже умеет discovery;
• смешивать данные ID Token с правами доступа к ресурсам.

Как проверить результат

После входа проверьте, что библиотека:

1. использует issuer Authoriza;
2. запрашивает openid;
3. получает и проверяет ID Token;
4. проверяет iss, aud, exp и подпись;
5. сохраняет локального пользователя по sub;
6. отправляет Access Token, а не ID Token, в API.

Основные роли OIDC-клиента

Приложение, которое использует Authoriza для входа, является relying party. Оно доверяет issuer только после проверки его конфигурации и ключей. Authoriza выполняет роль provider: принимает вход, формирует OIDC-ответ и подписывает ID Token. Ваш API может быть отдельным resource server и не обязан быть частью OIDC provider.

Такое разделение помогает определить, где происходит каждая проверка:

Что проверяет OIDC-клиент

Минимальный набор зависит от библиотеки, но обычно включает:

• подпись допустимым алгоритмом;
• iss ожидаемого issuer;
• aud нужного client ID;
• срок действия exp;
• nonce, если он был отправлен в authorization request;
• состояние flow и соответствие callback.

OIDC против собственного протокола

Собственная схема вроде «перенаправить на login, получить email и положить его в cookie» не описывает защиту от подмены callback, повторного использования ответа, ротации ключей и срока жизни токена. OIDC-библиотека или SDK уже решают эти низкоуровневые задачи и уменьшают количество кода, который нужно проверять самостоятельно.

Когда читать UserInfo

Не добавляйте UserInfo-запрос только потому, что он существует в стандарте. Сначала проверьте discovery и фактический контракт issuer. Если необходимые claims уже находятся в проверенном ID Token, дополнительный запрос не нужен.

Как это связано с Authoriza

Authoriza предоставляет OIDC-интерфейс, который можно подключить SDK или библиотекой своего стека. Issuer Authoriza:

https://oidc.authoriza.ru/oidc

Стандартный discovery endpoint:

https://oidc.authoriza.ru/oidc/.well-known/openid-configuration

Для OIDC-сценария используется scope openid. Дополнительные scopes описаны в статье Scopes.

Чем Authoriza может быть полезна

Если разобранная модель подходит вашему приложению, Authoriza позволяет использовать стандартный OIDC-интерфейс вместо собственной реализации. Следующий практический шаг — проверить настройки подключения.