В современном цифровом мире аутентификация стала центральным компонентом обеспечения безопасности веб-сайтов и приложений. OpenID Connect (OIDC), слой аутентификации, построенный на основе протокола OAuth 2.0, предлагает стандартизированный и понятный способ аутентификации личностей. Однако, правильная интеграция OIDC может быть сложной задачей, особенно для новичков. Хорошей отправной точкой часто является файл конфигурации OIDC, который обычно находится по адресу `{authServerUrl}/.well-known/openid-configuration` и содержит все необходимые детали для реализации OIDC-сервисов. Это руководство направлено на то, чтобы прояснить ключевые поля в этой конфигурации, помогая разработчикам понять их значение и практическое применение, чтобы лучше интегрировать OIDC в свои проекты. ## Анализ полей конфигурации OIDC Конфигурация OIDC представляет собой JSON-файл, подобный следующему: ```json { "authorization_endpoint": "", "claims_parameter_supported": false, "claims_supported": [ "sub", "name", "profile", "email", "email_verified", "phone_number", "phone_number_verified" ], "code_challenge_methods_supported": ["S256"], "grant_types_supported": [ "implicit", "authorization_code", "refresh_token", "client_credentials" ], "issuer": "", "jwks_uri": "", "response_modes_supported": ["form_post", "fragment", "query"], "response_types_supported": ["code id_token", "code", "id_token", "none"], "scopes_supported": ["openid", "offline_access", "profile", "email", "phone"], "subject_types_supported": ["public"], "token_endpoint_auth_methods_supported": [ "client_secret_basic", "client_secret_jwt", "client_secret_post" ], "token_endpoint_auth_signing_alg_values_supported": ["HS256"], "token_endpoint": "", "userinfo_endpoint": "" } ``` Далее мы углубимся в некоторые из ключевых полей. ### authorization_endpoint При интеграции OIDC-сервисов первый этап обычно включает в себя обработку запросов на вход пользователя в приложении. В этот процесс входит перенаправление пользователей на `authorization_endpoint` сервера авторизации. Этот конечный адрес сервера предназначен для отправки запросов на авторизацию и перенаправления пользователей на страницу входа для аутентификации. При выполнении запроса на `authorization_endpoint`, он должен быть настроен с дополнительными параметрами запроса для каждой авторизации: - `response_type`: Указывает тип возвращаемой авторизации. Это обычно включает "code" (для использования кода авторизации), "token" (для использования implicit flow) и "id_token token" или "code id_token" (для гибридного потока), которые можно найти в поле `response_types_supported` конфигурации OIDC. - `client_id`: Уникальный идентификатор, присвоенный приложению сервером авторизации при регистрации приложения. Этот ID используется сервером авторизации для распознавания клиентского приложения, инициирующего запрос. - `scope`: Определяет запрашиваемый доступ, указывая ресурсы или информацию о пользователе, к которым можно получить доступ. Общие области включают "openid" (обязательное), "profile" и "email" и другие. Вы можете найти поддерживаемые области в поле `scopes_supported` конфигурации OIDC; разные области должны быть разделены пробелами. - `redirect_uri`: После завершения входа или авторизации сервер авторизации перенаправляет пользователя на URI, предоставленный приложением. Этот URI должен строго соответствовать URI, указанному при регистрации приложения. - `state`: Случайная строка, используемая для защиты клиента от атак CSRF. Необходимо сохранять согласованность состояния между запросом на авторизацию и обратным вызовом для обеспечения безопасности. Эти параметры позволяют разработчикам точно контролировать поведение запросов авторизации OIDC, гарантируя их безопасность и соответствие потребностям приложения. ```js // Создание URL запроса на авторизацию function createAuthRequestURL(clientId, redirectUri, scope, responseType, state) { const url = new URL(config.authorization_endpoint); url.searchParams.append('response_type', responseType); url.searchParams.append('client_id', clientId); // URI для перенаправления пользователя после входа url.searchParams.append('redirect_uri', redirectUri); // Запрашиваемые права доступа, такие как "openid email profile" url.searchParams.append('scope', scope); // Случайное значение состояния для предотвращения атак CSRF url.searchParams.append('state', state); return url.toString(); } ``` После завершения запроса на `authorization_endpoint` и прохождения аутентификации, пользователи перенаправляются на указанный `redirect_uri`, который будет содержать очень важный параметр запроса — `code`. Этот код авторизации предоставляется сервером авторизации и является результатом того, что пользователь аутентифицировался и дал приложению разрешение на доступ к информации о себе на сервере авторизации. ### token_endpoint `token_endpoint` — это конечная точка сервера, используемая сервером авторизации для обмена указанного выше кода авторизации на токены доступа и обновления. В authorization code flow OAuth 2.0 этот шаг является критическим, так как он включает преобразование полученного кода авторизации в реальные токены доступа, которые могут быть использованы приложением для доступа к защищенным ресурсам пользователя. Вот как реализуется обмен кода авторизации на токены доступа (обратите внимание, что в этом примере используется метод аутентификации `client_secret_post`. Для других поддерживаемых методов аутентификации, см. последующий анализ поля `token_endpoint_auth_methods_supported`): ```js // Обмен кода авторизации на токены доступа async function fetchTokens(code, redirectUri, clientId, clientSecret) { const response = await fetch(config.token_endpoint, { method: 'POST', headers: { 'Content-Type': 'application/x-www-form-urlencoded', }, body: `code=${code}&redirect_uri=${redirectUri}&client_id=${clientId}&client_secret=${clientSecret}&grant_type=authorization_code`, }); return await response.json(); } ``` В этом коде мы сначала отправляем запрос на `token_endpoint` с использованием метода `POST`. Тип содержимого установлен на `application/x-www-form-urlencoded`, что требуется большинству серверов авторизации. Тело запроса включает следующие параметры: - code: Код авторизации, полученный от сервера авторизации, который возвращается через `redirectUri` после завершения авторизации пользователя. - redirect_uri: Тот же URI перенаправления, который был использован для получения кода авторизации, используется для проверки подлинности запроса. - client_id: Идентификатор клиента приложения, используется для идентификации приложения, выполняющего запрос. - client_secret: Секрет клиента приложения, используется для проверки подлинности приложения. - grant_type: Указывает тип авторизации, здесь используется `"authorization_code"`, что означает, что токен доступа получается через код авторизации. Эта функция выполнена асинхронно и возвращает JSON-объект, содержащий токен доступа, который приложение может использовать для запроса данных пользователя или выполнения других операций. ### userinfo_endpoint `userinfo_endpoint` — это конечная точка сервера, используемая сервером авторизации для получения детальной информации о аутентифицированных пользователях. После успешной авторизации пользователей и получения токенов доступа через `token_endpoint`, приложение может запросить эту конечную точку для получения информации профиля пользователя, такой как имя пользователя и адрес электронной почты. Конкретная получаемая информация зависит от `scope`, указанного пользователем в запросе на аутентификацию. ```js // Получение информации о пользователе async function fetchUserInfo(accessToken, tokenType) { const response = await fetch(config.userinfo_endpoint, { method: 'GET', // Вызов userinfo_endpoint с использованием метода GET headers: { /** * Использование типа токена и токена доступа. * Тип токена, возвращаемый вместе с токеном доступа, через конечную точку token */ Authorization: `${tokenType} ${accessToken}`, }, }); if (!response.ok) { throw new Error('Не удалось получить информацию о пользователе.'); } return await response.json(); // Разбор и возврат информации о пользователе в формате JSON } ``` В этой функции мы сначала используем метод `GET` для запроса `userinfo_endpoint`, включая поле `Authorization` в заголовок запроса, состоящее из значений `token_type` и `accessToken`. Это стандартная операция, согласно спецификации OAuth 2.0, обеспечивающая безопасное получение информации о пользователе. Кроме того, объем информации о пользователе, доступной через токен доступа, полностью зависит от значений параметра `scope`, выбранных пользователем на этапе инициирования авторизации. Например, если используется область `email`, в ответе должен быть указан адрес электронной почты пользователя. ### issuer & jwks_uri Игрок идентифицирует URL сервера авторизации, в то время как `jwks_uri` предоставляет URI для набора JSON Web Key Set (JWKS), который представляет собой набор открытых ключей, используемых для проверки подписей JWT. Проверка `issuer` и подписи JWT является основным шагом в обеспечении безопасности токенов, однако на практике процесс проверки обычно включает также проверку сроков действия токена, аудитории, области разрешений и других важных полей. Следующий код в основном демонстрирует, как использовать `issuer` и `jwks_uri` вместе для проверки JWT: ```js import { jwtVerify } from 'jose'; // Предположим, вы получили конфигурацию OIDC const config = { issuer: '', jwks_uri: '', }; // Получение JWKS async function fetchJWKS() { const response = await fetch(config.jwks_uri); const { keys } = await response.json(); return keys; } // Проверка токена async function validateToken(token, audience) { try { const jwks = await fetchJWKS(); const { payload } = await jwtVerify(token, jwks, { issuer: config.issuer, audience, }); console.log('Токен успешно проверен:', payload); return true; } catch (error) { console.error('Не удалось проверить токен:', error); return false; } } ``` ### scopes_supported & claims_supported Поля `claims_supported` и `scopes_supported` объявляют поддерживаемые сервером авторизации атрибуты пользователей (claims) и области доступа (scopes). Они помогают клиентам понять, какие атрибуты пользователей и области доступа поддерживаются сервером авторизации, что позволяет клиентам эффективно формировать запросы на авторизацию и разбирать ответы. При создании запроса на авторизацию клиенты могут указать необходимую `scope` в соответствии с потребностями приложения. `Scope` определяет ресурсы и операции, которые клиент запрашивает для доступа, такие как `openid`, `email`, `profile` и другие. Важно отметить, что конкретные доступные claims для каждого запроса на авторизацию варьируются в зависимости от значений областей действия, указанных при запуске запроса на аутентификацию. Например, область email предоставляет доступ к адресу электронной почты пользователя, в то время как область phone предоставляет доступ к номеру телефона. Поэтому клиенты должны тщательно выбирать соответствующую область действия, чтобы соответствовать потребностям приложения при составлении запроса на авторизацию, чтобы они могли получить необходимые атрибуты пользователя: ```js // Создание URL запроса на авторизацию function createAuthRequestURL(clientId, redirectUri, scope, responseType) { const url = new URL(config.authorization_endpoint); url.searchParams.append('response_type', responseType); url.searchParams.append('client_id', clientId); url.searchParams.append('redirect_uri', redirectUri); // Указание необходимой области в запросе на авторизацию url.searchParams.append('scope', scope); return url.toString(); } ``` ### token_endpoint_auth_methods_supported Поле `token_endpoint_auth_methods_supported` указывает методы аутентификации, поддерживаемые конечной точкой token. Эти методы используются клиентом для аутентификации на сервере авторизации при обмене кода авторизации на токены доступа. При аутентификации с использованием конечной точки token, общие методы аутентификации включают `client_secret_post`, `client_secret_basic` и `client_secret_jwt`. - `client_secret_post`: Клиент использует свой идентификатор клиента и клиентский секрет для составления формы закодированного тела, которое отправляется как часть тела запроса. Мы уже видели пример этого метода в разделе `token_endpoint` выше. - `client_secret_basic`: Клиент использует свой идентификатор клиента и клиентский секрет для составления базового заголовка аутентификации, который добавляется в заголовок запроса. ```js // Использование метода аутентификации client_secret_basic const headersBasic = new Headers(); headersBasic.append( 'Authorization', `Basic ${Buffer.from(`${clientId}:${clientSecret}`).toString('base64')}` ); // Затем отправьте запрос с заголовком базовой аутентификации для получения токена доступа // ... ``` - `client_secret_jwt`: Клиент использует JWT (JSON Web Token) в качестве утверждения клиента для аутентификации. Этот JWT содержит идентификатор клиента и некоторую дополнительную метаинформацию и подписывается с использованием клиентского секрета. После получения запроса сервер авторизации проверяет подлинность клиента, проверяя подпись JWT. ```js // Использование метода аутентификации client_secret_jwt const clientSecretJwt = await new SignJWT({ iss: clientId, sub: clientId, aud: tokenEndpoint, jti: randomString(), exp: Math.floor(Date.now() / 1000) + 600, // Время истечения составляет 10 минут iat: Math.floor(Date.now() / 1000), }) .setProtectedHeader({ alg: 'HS256', }) .sign(Buffer.from(clientSecret)); // Добавление утверждения клиента в тело запроса const params = new URLSearchParams(); params.append('grant_type', 'authorization_code'); params.append('code', authorizationCode); // Добавление параметров утверждения клиента params.append('client_assertion_type', 'urn:ietf:params:oauth:client-assertion-type:jwt-bearer'); params.append('client_assertion', clientSecretJwt); // Отправка запроса и получение токена доступа const tokenResponse = await fetch(tokenEndpoint, { method: 'POST', headers: { 'Content-Type': 'application/x-www-form-urlencoded', }, body: params, }); ``` В практических приложениях клиентам необходимо выбирать подходящий метод аутентификации на основе методов, поддерживаемых сервером авторизации, и убедиться, что информация для аутентификации правильно добавлена в запрос, чтобы безопасно обменять код авторизации на токены доступа. ## Резюме Теперь мы рассмотрели ключевые поля в конфигурации OIDC, сосредоточив внимание на их назначении и применении. Понимание этих деталей улучшит ваше представление о OpenID Connect, позволяя вам более эффективно интегрировать и использовать его в своих проектах. Вооруженные этими знаниями, вы лучше подготовлены к использованию полного потенциала OIDC для более безопасных и эффективных решений аутентификации пользователей. Logto — это сервис аутентификации, построенный на основе OIDC, который предлагает полный набор SDK на различных языках, а также многочисленные учебные пособия по интеграции, что позволяет вам бесшовно интегрировать логины OAuth / OIDC в свои приложения за считанные минуты. Если вы ищете надежный и простой в использовании сервис OIDC, попробуйте Logto уже сегодня! Попробуйте Logto уже сегодня!