OpenID Connect на платформе удостоверений Майкрософт

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

Полная спецификация для OIDC доступна на веб-сайте OpenID Foundation в статье о спецификации OpenID Connect Core 1.0.

Поток протокола: вход

На следующей схеме показан базовый поток входа OpenID Connect. Шаги в потоке подробно описаны в последующих разделах этой статьи.

Включение маркеров идентификаторов

Маркер идентификатора, представленный OpenID Connect, выдан сервером авторизации, платформа удостоверений Майкрософт, когда клиентское приложение запрашивает один из них во время проверки подлинности пользователя. Маркер идентификатора позволяет клиентскому приложению проверить удостоверение пользователя и получить другие сведения (утверждения) о нем.

Маркеры идентификатора не выдаются по умолчанию для приложения, зарегистрированного с помощью платформы удостоверений Майкрософт. Маркеры идентификатора приложения включены с помощью одного из следующих методов:

1. Войдите в центр администрирования Microsoft Entra.
2. Перейдите к приложениям> удостоверений>Регистрация приложений<> your application>>Authentication.
3. В разделе Конфигурации платформ щелкните Добавить платформу.
4. В открывающейся области выберите соответствующую платформу для приложения. Например, выберите Веб-приложение для веб-приложения.
5. В разделе URI перенаправления добавьте URI перенаправления приложения. Например, https://localhost:8080/.
6. В разделе Неявное предоставление разрешения и гибридные потоки установите флажок Токены ИД (используются для неявных и гибридных потоков).

Или сделайте так:

1. Выберите приложения> удостоверений>Регистрация приложений>< your application>>Manifest.
2. В манифесте приложения регистрации приложения задайте для oauth2AllowIdTokenImplicitFlow значение true.

Если маркеры идентификатора не включены для приложения и запрашивается один из них, платформа удостоверений Майкрософт возвращает ошибку, аналогичную следующейunsupported_response:

The provided value for the input parameter 'response_type' isn't allowed for this client. Expected value is 'code' (Указанное значение параметра response_type запрещено для данного клиента. Ожидаемое значение: code)..

Запрос маркера идентификатора через указание response_type для id_token, описан в разделе Отправка запроса на вход далее в статье.

Получение документа конфигурации OpenID

Поставщики OpenID, такие как платформа удостоверений Майкрософт, предоставляют документ конфигурации поставщика OpenID в общедоступной конечной точке, содержащей конечные точки OIDC поставщика, поддерживаемые утверждения и другие метаданные. Клиентские приложения могут использовать метаданные для обнаружения URL-адресов, используемых для проверки подлинности и открытых ключей подписывания службы проверки подлинности.

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

Поиск универсального кода ресурса (URI) для документа конфигурации OpenID приложения

Каждая регистрация приложения в идентификаторе Microsoft Entra предоставляется общедоступная конечная точка, которая служит документом конфигурации OpenID. Чтобы определить URI конечной точки документа конфигурации для приложения, добавьте известный путь конфигурации OpenID к URL-адресу центра регистрации приложения.

• Известный путь к документу конфигурации: /.well-known/openid-configuration
• URL-адрес центра: https://login.microsoftonline.com/{tenant}/v2.0

Значение {tenant} зависит от аудитории входа приложения, как показано в следующей таблице. URL-адрес центра также зависит от облачного экземпляра.

Чтобы найти документ конфигурации OIDC в Центре администрирования Microsoft Entra, войдите в Центр администрирования Microsoft Entra, а затем:

1. Перейдите к приложениям> удостоверений>Регистрация приложений<> your application>>Endpoints.
2. Найдите URI в разделе документа метаданных OpenID Connect.

Образец запроса

Следующий запрос получает метаданные конфигурации OpenID из common конечной точки документа конфигурации OpenID центра в общедоступном облаке Azure:

GET /common/v2.0/.well-known/openid-configuration
Host: login.microsoftonline.com

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

Метаданные конфигурации возвращаются в формате JSON, как показано в следующем примере (усеченный для краткости). Метаданные, возвращаемые в ответе в формате JSON, подробно описаны в спецификации обнаружения OpenID Connect 1.0.

{
  "authorization_endpoint": "https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize",
  "token_endpoint": "https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token",
  "token_endpoint_auth_methods_supported": [
    "client_secret_post",
    "private_key_jwt"
  ],
  "jwks_uri": "https://login.microsoftonline.com/{tenant}/discovery/v2.0/keys",
  "userinfo_endpoint": "https://graph.microsoft.com/oidc/userinfo",
  "subject_types_supported": [
      "pairwise"
  ],
  ...
}

Отправка запроса на вход

Чтобы выполнить аутентификацию пользователя и запросить маркер идентификатора для использования в приложении, направьте агент пользователя в конечную точку /authorize платформы удостоверений Майкрософт. Этот запрос похож на первый этап потока кода авторизации OAuth 2.0, но с несколькими различиями, которые приведены ниже.

• Включите область openid в параметр scope.
• Укажите id_token в параметре response_type .
• Включите параметр nonce.

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

GET https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize?
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&response_type=id_token
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&response_mode=form_post
&scope=openid
&state=12345
&nonce=678910

На текущем этапе пользователю предлагается ввести учетные данные и завершить аутентификацию. Платформа удостоверений Майкрософт проверяет, согласился ли пользователь предоставить разрешения, указанные в параметре запроса scope. Если пользователь не предоставил какие-либо из этих разрешений, платформа удостоверений Майкрософт запросит их у него. Вы можете узнать больше о разрешениях, согласии и мультитенантных приложениях.

После того как пользователь выполнит аутентификацию и предоставит разрешения, платформа удостоверений Майкрософт вернет приложению ответ на указанный универсальный код ресурса (URI) перенаправления с помощью метода, указанного в параметре response_mode.

Успешный ответ

Успешный ответ при использовании response_mode=form_post аналогичен следующему:

POST /myapp/ HTTP/1.1
Host: localhost
Content-Type: application/x-www-form-urlencoded

id_token=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik1uQ19WWmNB...&state=12345

Отклик в случае ошибки

Сообщения об ошибках также можно отправлять на универсальный код ресурса (URI) перенаправления, чтобы приложение могло их обработать, например:

POST /myapp/ HTTP/1.1
Host: localhost
Content-Type: application/x-www-form-urlencoded

error=access_denied&error_description=the+user+canceled+the+authentication

Коды ошибок конечной точки авторизации

В таблице ниже описаны коды ошибок, которые могут возвращаться в параметре error сообщения об ошибке.

Проверка маркера идентификации

Получение маркера идентификатора в приложении может быть недостаточным для полной аутентификации пользователя. Необходимо также проверить сигнатуру маркера идентификатора и сопоставить утверждения с требованиями вашего приложения. Как и все поставщики OpenID, маркеры идентификатора платформы удостоверений Майкрософт — это маркеры JSON Web Token (JWT), подписанные с помощью шифрования открытого ключа.

Веб-приложения и веб-API, использующие маркеры идентификатора для авторизации, должны проверять их, так как такие приложения получают доступ к данным. Но другие типы приложений могут не иметь преимущества от проверки маркера идентификатора. Собственные и одностраничные приложения (SPA), например, редко используют проверку маркеров идентификатора, так как любая сущность с физическим доступом к устройству или браузеру может потенциально обойти проверку.

Ниже приведены два примера обхода проверки маркера:

• Предоставление фиктивных маркеров или ключей путем изменения трафика для устройства.
• Отладка приложения и пошаговое выполнение с обходом логики проверки во время выполнения программы.

Если вы проверяете маркеры идентификатора в приложении, рекомендуем не выполнять это вручную. Вместо этого используйте библиотеку проверки маркеров, чтобы анализировать и проверять маркеры. Библиотеки проверки маркеров доступны для большинства языков разработки и платформ.

Что нужно проверить в маркере идентификатора

Помимо проверки подписи маркера идентификатора, необходимо проверить несколько его утверждений, как описано в описании проверки маркера идентификатора. См. также важную информацию о смене ключей подписывания.

Некоторые другие проверки являются общими и зависят от сценария приложения, в том числе:

• Обеспечение регистрации пользователя или организации в приложении.
• Предоставление пользователю необходимого уровня авторизации и привилегий.
• Обеспечение определенной надежности проверки подлинности, например многофакторной проверки подлинности.

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

Схема протокола: получение маркера доступа

Многим приложениям требуется не только выполнить вход пользователя, но и получить доступ к защищенному ресурсу, например к веб-API от имени пользователя. Этот сценарий объединяет OpenID Connect для получения маркера идентификатора для аутентификации пользователя и OAuth 2.0, чтобы иметь маркер доступа для защищенного ресурса.

Полный поток входа OpenID Connect и получения маркера представлен на этой схеме:

Получение маркера доступа для конечной точки UserInfo

Кроме маркера идентификатора, сведения о прошедшем аутентификацию пользователя также предоставляются в конечную точку UserInfo OIDC.

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

// Line breaks are for legibility only.

GET https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize?
client_id=00001111-aaaa-2222-bbbb-3333cccc4444        // Your app registration's Application (client) ID
&response_type=id_token%20token                       // Requests both an ID token and access token
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F       // Your application's redirect URI (URL-encoded)
&response_mode=form_post                              // 'form_post' or 'fragment'
&scope=openid+profile+email                           // 'openid' is required; 'profile' and 'email' provide information in the UserInfo endpoint as they do in an ID token. 
&state=12345                                          // Any value - provided by your app
&nonce=678910                                         // Any value - provided by your app

Чтобы получить маркер доступа для приложения, вместо response_type=token можно использовать поток кода авторизации, поток кода устройства или маркер обновления.

Успешный ответ маркера

Успешный ответ при использовании response_mode=form_post:

POST /myapp/ HTTP/1.1
Host: localhost
Content-Type: application/x-www-form-urlencoded
 access_token=eyJ0eXAiOiJKV1QiLCJub25jZSI6I....
 &token_type=Bearer
 &expires_in=3598
 &scope=email+openid+profile
 &id_token=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI....
 &state=12345

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

Отклик в случае ошибки

Сообщения об ошибках также можно отправлять на универсальный код ресурса (URI) перенаправления, чтобы приложение могло их правильно обработать.

POST /myapp/ HTTP/1.1
Host: localhost
Content-Type: application/x-www-form-urlencoded

error=access_denied&error_description=the+user+canceled+the+authentication

Описание возможных кодов ошибок и рекомендуемые ответы клиента см. в разделе Коды ошибок конечной точки авторизации.

После получения кода авторизации и маркера идентификации можно выполнить вход пользователя в систему и получить маркеры доступа от его имени. Чтобы войти в систему, необходимо проверить маркер идентификатора, как описано в маркерах проверки. Для получения маркеров доступа следует выполнить действия, описанные в документации по потоку кода OAuth.

Вызов конечной точки UserInfo

Просмотрите документацию по UserInfo, чтобы узнать, как вызвать конечную точку UserInfo с помощью этого маркера.

Отправка запроса на выход

Чтобы выйти из пользователя, выполните обе следующие операции:

1. Перенаправьте ПОЛЬЗОВАТЕЛЬСКИЙ агент пользователя в URI выхода платформа удостоверений Майкрософт.
2. Снимите файлы cookie приложения или завершите сеанс пользователя в приложении.

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

Перенаправьте агент пользователя в end_session_endpoint, как показано в документе конфигурации OpenID Connect. end_session_endpoint поддерживает HTTP-запросы GET и POST.

GET https://login.microsoftonline.com/common/oauth2/v2.0/logout?
post_logout_redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F

Единый выход

При перенаправлении пользователя end_session_endpoint в приложение платформа удостоверений Майкрософт завершает сеанс пользователя для этого приложения. Однако пользователь может войти в другие приложения, использующие те же учетные записи Майкрософт для проверки подлинности.

Когда пользователь вошел в несколько веб-приложений или SPA, зарегистрированных в этом каталоге (также известном как клиент), этот пользователь может мгновенно выйти из всех приложений, выполнив вход в одном из приложений.

Чтобы включить единый выход для приложения Entra, следует использовать функцию выхода внешнего канала OpenID Connect. Эта функция позволяет приложению уведомлять другие приложения о том, что пользователь вышел из системы. Когда пользователь выходит из одного приложения, платформа удостоверений Майкрософт отправляет HTTP-запрос GET на URL-адрес выхода внешнего канала каждого приложения, в которое в настоящее время входит пользователь.

Эти приложения должны отвечать на этот запрос, выполнив следующие два действия, чтобы единый выход был успешным:

1. Снимите любой сеанс, который идентифицирует пользователя.
2. Приложения должны ответить на него, удалив любой сеанс, который идентифицирует пользователя, и возвратив ответ 200.

Что такое URL-адрес выхода внешнего канала?

URL-адрес выхода внешнего канала — это место, в котором веб-приложение или spa получает запрос на выход с сервера проверки подлинности Entra и выполняет функции единого выхода. У каждого приложения есть один URL-адрес выхода внешнего канала.

Когда следует задать URL-адрес выхода внешнего канала?

Если для приложения требуется единый выход или разработчик, необходимо задать URL-адрес выхода переднего канала для регистрации приложения. После установки URL-адреса выхода из внешнего канала для регистрации приложения платформа удостоверений Майкрософт отправляет HTTP-запрос GET на URL-адрес выхода из этого приложения, когда пользователь вошел в систему из другого приложения.

Настройка единого выхода с помощью функции выхода внешнего канала

Чтобы использовать функцию выхода переднего канала для набора приложений, необходимо выполнить следующие две задачи:

• Задайте URL-адрес выхода переднего канала в Центре администрирования Microsoft Entra для всех приложений, которые должны быть выходить одновременно. Каждое приложение обычно имеет собственный URL-адрес выхода внешнего канала.
• Измените код приложений таким образом, чтобы они прослушивали HTTP-запрос GET, отправленный платформа удостоверений Майкрософт в URL-адрес выхода внешнего канала, и отвечайте на этот запрос, очищая любой сеанс, который идентифицирует пользователя и возвращает ответ 200.

Выбор URL-адреса выхода внешнего канала

URL-адрес выхода переднего канала должен быть URL-адресом, который может получать и отвечать на HTTP-запросы GET и должен иметь возможность очистить любой сеанс, который идентифицирует пользователя. Примеры URL-адреса выхода внешнего канала могут быть, но не ограничены следующими:

• https://example.com/frontchannel_loout
• https://example.com/signout
• https://example.com/logout

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

• Просмотрите документацию по конечной точке UserInfo.
• Настройка утверждений в маркере с помощью данных из локальных систем.
• Включение собственных утверждений в маркеры.