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

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

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

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

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

Swim-lane diagram showing the OpenID Connect protocol's sign-in flow.

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

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

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

  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-адрес центра также зависит от облачного экземпляра.

значение Описание
common Пользователи с личной учетной записью Майкрософт и рабочей или учебной учетной записью из идентификатора Microsoft Entra могут войти в приложение.
organizations Только пользователи с рабочими или учебными учетными записями из идентификатора Microsoft Entra могут войти в приложение.
consumers Вход в приложение могут выполнять только пользователи с личной учетной записью Майкрософт.
8eaef023-2b34-4da1-9baa-8bc8c9d6a490 или contoso.onmicrosoft.com Только пользователи из определенного клиента Microsoft Entra (участники каталога с рабочей или учебной учетной записью или гостями каталога с личной учетной записью Майкрософт) могут войти в приложение.

Это значение может быть доменным именем клиента Microsoft Entra или идентификатором клиента в формате GUID. Можно также использовать GUID арендатора-потребителя 9188040d-6c67-4c5b-b112-36a304b66dad (вместо consumers).

Совет

Обратите внимание, что при использовании common или consumers центра для личных учетных записей Майкрософт необходимо настроить приложение ресурсов для поддержки такого типа учетных записей в соответствии с signInAudience.

Чтобы найти документ конфигурации 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

Совет

Попробовать! Чтобы просмотреть документ конфигурации OpenID для центра common приложения, перейдите по адресу https://login.microsoftonline.com/common/v2.0/.well-known/openid-configuration.

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

Метаданные конфигурации возвращаются в формате 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=535fb089-9ff3-47b6-9bfb-4f1264799865
&response_type=id_token
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&response_mode=form_post
&scope=openid
&state=12345
&nonce=678910
Параметр Условие Description
tenant Обязательное поле Значение {tenant} в пути запроса можно использовать для того, чтобы контролировать вход пользователей в приложение. Допустимые значения: common, organizations, consumers, а также идентификаторы клиента. Чтобы узнать больше, ознакомьтесь с основами протокола. В гостевых сценариях, в которых пользователь из одного клиента выполняет вход в другой, необходимо предоставить идентификатор клиента, чтобы вход выполнялся правильно.
client_id Обязательное поле Идентификатор приложения (клиента), который центр администрирования Microsoft Entra — Регистрация приложений, назначенный приложению.
response_type Обязательное поле Должен включать id_token для входа в OpenID Connect.
redirect_uri Рекомендуемая конфигурация Универсальный код ресурса (URI) перенаправления приложения, на который можно отправлять ответы аутентификации для их получения приложением. Он должен в точности соответствовать одному из универсальных кодов ресурса (URI) перенаправления, зарегистрированных на портале, но иметь форму URL-адреса. Если он отсутствует, конечная точка будет случайным образом выбирать один зарегистрированный redirect_uri, чтобы отправить обратно пользователю.
scope Обязательное поле Список областей с разделителями-пробелами. При использовании протокола OpenID Connect он должен содержать область openid, что преобразуется в разрешение Вход в пользовательском интерфейсе предоставления согласия. Для предоставления согласия этот запрос может также включать в себя другие области.
nonce Обязательное поле Значение, созданное и отправленное приложением в запросе на маркер идентификатора. То же значение nonce включается в маркер идентификатора, возвращенный приложению платформа удостоверений Майкрософт. Чтобы устранить атаки с повторением маркеров, приложение должно проверить, что значение nonce в маркере идентификатора совпадает со значением, которое оно отправляет при запросе маркера. Значение обычно является уникальной случайной строкой.
response_mode Рекомендуемая конфигурация Указывает метод, с помощью которого следует отправлять полученный код авторизации приложению. Может иметь значение form_post или fragment. Для веб-приложений рекомендуется использовать response_mode=form_post, чтобы обеспечить наиболее безопасную передачу маркеров в приложение.
state Рекомендуемая конфигурация Значение, включенное в запрос, которое также возвращается в ответе маркера. Это может быть строка любого содержания. Как правило, с целью предотвращения подделки межсайтовых запросов используется генерируемое случайным образом уникальное значение. Параметр state используется также для кодирования сведений о состоянии пользователя в приложении перед созданием запроса на аутентификацию, например сведений об открытой на тот момент странице или представлении.
prompt Необязательно Указывает требуемый тип взаимодействия с пользователем. На текущий момент единственные допустимые значения — login, none, consent и select_account. Утверждение prompt=login требует от пользователя ввести учетные данные по запросу. Единый вход не сработает. Параметр prompt=none имеет противоположный смысл и должен быть связан с login_hint, чтобы указать, какой пользователь должен войти в систему. Эти параметры гарантируют, что для пользователя не будут выводиться никакие интерактивные запросы. Если запрос не удается выполнить автоматически с помощью единого входа, платформа удостоверений Майкрософт возвращает ошибку. Причины включают отсутствие вошедшего пользователя, указанный пользователь не вошел в систему, или вошло несколько пользователей, но не было предоставлено указаний. Утверждение prompt=consent активирует диалоговое окно предоставления согласия OAuth после входа пользователя в систему. В нем у пользователя запрашиваются разрешения для приложения. Наконец, select_account показывает пользователю селектор учетных записей, что делает автоматический единый вход невозможным, но позволяет пользователю выбрать учетную запись, с которой он предполагает выполнить вход, без необходимости ввода учетных данных. Вы на можете использовать одновременно login_hint и select_account.
login_hint Необязательно Этот параметр можно применять для предварительного заполнения полей имени пользователя и электронного адреса на странице входа пользователя (если имя пользователя известно заранее). Этот параметр обычно используется в приложениях при повторной проверке подлинности после извлечения необязательного утвержденияlogin_hint из предыдущего сеанса входа.
domain_hint Необязательно Область пользователя в федеративном каталоге. Если используется этот параметр, процесс обнаружения на основе электронной почты, который проходит пользователь на странице входа, пропускается, что немного оптимизирует работу. Для клиентов, объединяемых в федерацию на основе локального каталога, например AD FS, это часто позволяет автоматически входить в систему благодаря наличию текущего сеанса.

На текущем этапе пользователю предлагается ввести учетные данные и завершить аутентификацию. Платформа удостоверений Майкрософт проверяет, согласился ли пользователь предоставить разрешения, указанные в параметре запроса 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
Параметр Описание
id_token Маркер идентификации, запрошенный приложением. Вы можете использовать параметр id_token для проверки личности пользователя и запуска сеанса пользователя. Дополнительные сведения о маркерах идентификатора и их содержимом см. в справочнике по маркерам идентификатора.
state Если запрос содержит параметр state, то в ответе должно отображаться то же значение. Приложение должно убедиться, что значения параметра state в запросе и отклике идентичны.

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

Сообщения об ошибках также можно отправлять на универсальный код ресурса (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 Строка кода ошибки, которую можно использовать для классификации типов возникших ошибок и реагирования на них.
error_description Конкретное сообщение об ошибке, с помощью которого можно определить первопричину возникновения ошибки аутентификации.

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

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

Код ошибки Description Действие клиента
invalid_request Ошибка протокола, например отсутствует обязательный параметр. Исправьте запрос и отправьте его повторно. Эту ошибку разработки следует выявить во время тестирования приложения.
unauthorized_client Клиентское приложение не может запрашивать код авторизации. Эта ошибка может возникать, если клиентское приложение не зарегистрировано в идентификаторе Microsoft Entra или не добавляется в клиент Microsoft Entra пользователя. Приложение может предложить пользователю инструкции по установке приложения и добавить его в идентификатор Microsoft Entra.
access_denied Владелец ресурса не дал согласия. Клиентское приложение может уведомить пользователя, что для продолжения работы необходимо согласие пользователя.
unsupported_response_type Сервер авторизации не поддерживает тип ответа в запросе. Исправьте запрос и отправьте его повторно. Эту ошибку разработки следует выявить во время тестирования приложения.
server_error Сервер обнаружил непредвиденную ошибку. Повторите запрос. Эти ошибки могут возникать в связи с временными условиями. Из клиентского приложения может поступить сообщение о том, что его ответ задерживается из-за временной ошибки.
temporarily_unavailable Сервер временно занят и не может обработать запрос. Повторите запрос. Из клиентского приложения может поступить сообщение о том, что его ответ задерживается из-за временного состояния.
invalid_resource Целевой ресурс недопустим, так как он не существует, идентификатор Microsoft Entra ID не может найти его или неправильно настроен. Это означает, что ресурс не существует или не настроен в арендаторе. Приложение может предложить пользователю инструкции по установке приложения и его добавлению в идентификатор Microsoft Entra.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

OpenID Connect protocol: Token acquisition

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

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

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

// Line breaks are for legibility only.

GET https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize?
client_id=535fb089-9ff3-47b6-9bfb-4f1264799865        // 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

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

Параметр Описание
access_token Маркер, который будет использоваться для вызова конечной точки UserInfo.
token_type Всегда имеет значение Bearer.
expires_in Время до истечения срока действия маркера доступа (в секундах).
scope Разрешения, предоставленные для маркера доступа. Так как конечная точка UserInfo размещена в Microsoft Graph, scope может содержать другие ранее предоставленные разрешения для приложения (например, User.Read).
id_token Маркер идентификации, запрошенный приложением. Вы можете использовать маркер идентификации для проверки личности пользователя и запуска сеанса пользователя. Дополнительные сведения о маркерах идентификатора и их содержимом см. в справочнике по маркерам идентификатора.
state Если запрос содержит параметр "state", в ответе должно отображаться то же значение. Приложение должно убедиться, что значения параметра state в запросе и отклике идентичны.

Предупреждение

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

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

Сообщения об ошибках также можно отправлять на универсальный код ресурса (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 Строка кода ошибки, которую можно использовать для классификации типов возникших ошибок и реагирования на них.
error_description Конкретное сообщение об ошибке, с помощью которого можно определить первопричину возникновения ошибки аутентификации.

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

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

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

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

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

Выполните обе эти операции для выхода пользователя:

  • Перенаправление пользовательского агента пользователя на URI выхода платформы удостоверений Майкрософт.
  • Очистка файлов 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
Параметр Условие Description
post_logout_redirect_uri Рекомендуется URL-адрес, на который пользователя следует перенаправить после успешного выхода. Если параметр не включен, пользователь увидит общее сообщение, созданное платформой удостоверений Майкрософт. URL-адрес должен в точности соответствовать одному из универсальных кодов ресурсов (URI) перенаправления, зарегистрированных для приложения на портале регистрации приложений.
logout_hint Необязательно Включает выход без запроса на выбор учетной записи пользователя. Чтобы использовать logout_hint, включите login_hintнеобязательное утверждение в клиентском приложении и используйте значение login_hint необязательного утверждения в качестве logout_hint параметра. Не используйте имена участников-пользователей или номера телефонов в качестве значения параметра logout_hint.

Примечание.

После успешного выхода активные сеансы будут заданы как неактивные. Если для пользователя, выполнившего вход, существует действительный первичный маркер обновления (PRT), и выполняется новый вход, единый вход будет прерван, и пользователь увидит запрос с помощью средства выбора учетной записи. Если выбран параметр подключенной учетной записи, которая ссылается на PRT, вход будет выполняться автоматически без необходимости вставки новых учетных данных.

Единый выход

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

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