Платформа удостоверений Майкрософт и поток учетных данных клиента OAuth 2.0
Поток предоставления учетных данных клиента OAuth 2.0 позволяет веб-службе (конфиденциальному клиенту) использовать собственные учетные данные вместо олицетворения пользователя для проверки подлинности при вызове другой веб-службы. Грант, указанный в RFC 6749, иногда называемый двухуровневойOAuth, можно использовать для доступа к размещенным в Интернете ресурсам с помощью удостоверения приложения. Этот тип обычно используется для взаимодействия между серверами, которые должны выполняться в фоновом режиме, без немедленного взаимодействия с пользователем, и часто называются демонами или учетными записями служб.
В потоке учетных данных клиента разрешения предоставляются непосредственно самому приложению администратором. Когда приложение представляет маркер ресурсу, ресурс принудительно применяет, что само приложение имеет авторизацию для выполнения действия, так как пользователь не участвует в проверке подлинности. В этой статье рассматриваются оба шага, необходимые для следующих действий.
В этой статье описывается, как программировать непосредственно против протокола в приложении. По возможности рекомендуется использовать поддерживаемые библиотеки проверки подлинности Майкрософт (MSAL) вместо того, чтобы получать маркеры и вызывать защищенные веб-API. Вы также можете ознакомиться с примерами приложений , использующих MSAL. Примечание: маркеры обновления никогда не будут предоставляться с этим потоком, так как client_id и client_secret (которые требуются для получения маркера обновления) можно использовать для получения маркера доступа.
Для более высокого уровня гарантии платформа удостоверений Майкрософт также позволяет вызывающей службе проходить проверку подлинности с помощью сертификата или федеративных учетных данных вместо общего секрета. Так как используются собственные учетные данные приложения, эти учетные данные должны быть защищены. никогда не публиковать эти учетные данные в исходном коде, внедрять их в веб-страницы или использовать их в широко распространяемом приложении.
Схема протокола
Весь поток учетных данных клиента выглядит примерно так, как показано на следующей схеме. Мы описываем каждый из шагов, описанных далее в этой статье.
схема 
Получение прямой авторизации
Приложение обычно получает прямую авторизацию для доступа к ресурсу одним из двух способов:
- через список управления доступом (ACL) на уровне ресурса
- С помощью назначения разрешений приложения в идентификатора Microsoft Entra
Эти два метода являются наиболее распространенными в идентификаторе Microsoft Entra, и мы рекомендуем их для клиентов и ресурсов, которые выполняют поток учетных данных клиента. Ресурс также может авторизовать своих клиентов другими способами. Каждый сервер ресурсов может выбрать метод, который лучше всего подходит для своего приложения.
Списки управления доступом
Поставщик ресурсов может применить проверку авторизации на основе списка идентификаторов приложений (клиента), которые он знает и предоставляет определенный уровень доступа. Когда ресурс получает токен от платформы идентификации Microsoft, он может декодировать токен и извлекать идентификатор приложения клиента из заявок appid и iss. Затем он сравнивает приложение с списком управления доступом (ACL), который он поддерживает. Степень детализации и метода ACL может существенно отличаться между ресурсами.
Распространенный вариант использования — использовать ACL для выполнения тестов для веб-приложения или веб-API. Веб-API может предоставить только подмножество полных разрешений конкретному клиенту. Чтобы выполнить сквозные тесты в API, можно создать тестовый клиент, который получает маркеры из платформы удостоверений Майкрософт, а затем отправляет их в API. Затем API проверяет ACL для идентификатора приложения тестового клиента для полного доступа ко всей функциональности API. Если вы используете этот тип списка контроля доступа (ACL), обязательно проверьте не только значение appid вызывающего объекта, но и убедитесь, что iss значение токена является доверенным.
Этот тип авторизации распространен для демонов и учетных записей служб, которым требуется доступ к данным, принадлежащим пользователям с персональными учетными записями Майкрософт. Для данных, принадлежащих организациям, рекомендуется получить необходимую авторизацию с помощью разрешений приложения.
Управление токенами без запроса roles
Чтобы включить этот шаблон авторизации на основе ACL, Microsoft Entra ID не требует, чтобы приложения были авторизованы для получения токенов для другого приложения. Таким образом, токены, доступные только для приложений, могут выдаваться без утверждения roles. Приложения, предоставляющие API, должны реализовать проверки разрешений для принятия токенов.
Если вы хотите запретить приложениям получать маркеры доступа только для приложения без ролей, убедитесь, что требования к назначению включены для вашего приложения. Это заблокирует пользователей и приложения без назначенных ролей от возможности получить маркер для этого приложения.
Разрешения приложения
Вместо использования списков управления доступом можно использовать API, чтобы предоставить доступ к набору разрешений приложения . Они предоставляются администратору организации и могут использоваться только для доступа к данным, принадлежащим этой организации и его сотрудникам. Например, Microsoft Graph предоставляет несколько разрешений приложения для выполнения следующих действий:
- Чтение почты во всех почтовых ящиках
- Чтение и запись почты во всех почтовых ящиках
- Отправка почты от имени любого пользователя
- Чтение данных каталога
Чтобы использовать роли приложения (разрешения приложения) с собственным API (в отличие от Microsoft Graph), необходимо сначала открыть роли приложения в административном центре Microsoft Entra для регистрации приложений API. Затем настройте требуемые роли приложений, выбрав соответствующие разрешения в разделе регистрации вашего клиентского приложения. Если вы не предоставили ролей приложений в регистрации приложения API, вы не сможете указать разрешения приложения для этого API в регистрации приложения клиента в Центре администрирования Microsoft Entra.
При проверке подлинности в качестве приложения (в отличие от пользователя), вы не можете использовать делегированные разрешения, так как для вашего приложения нет пользователя, от имени которого оно могло бы действовать. Необходимо использовать разрешения приложения, также называемые ролями приложений, которые предоставляются администратором или владельцем API.
Дополнительные сведения о разрешениях и согласии приложений см. в Разрешения иСогласие.
Рекомендуется: войдите в приложение как администратор, чтобы роли приложения были назначены
Как правило, при создании приложения, использующего разрешения приложения, приложению требуется страница или представление, на котором администратор утверждает разрешения приложения. Эта страница может быть частью потока входа приложения, части параметров приложения или выделенного подключения потока. Часто имеет смысл показывать вышеупомянутое представление подключения в приложении только после того, как пользователь войдет с помощью рабочей или учебной учетной записи Майкрософт.
При входе пользователя в приложение можно определить организацию, к которой принадлежит пользователь, прежде чем попросить пользователя утвердить разрешения приложения. Хотя это не обязательно, это поможет вам создать более интуитивно понятный интерфейс для пользователей. Чтобы авторизовать пользователя, следуйте руководствам по платформе идентификации Майкрософт протоколу.
Запрос разрешений от администратора каталога
Когда вы будете готовы запросить разрешения у администратора организации, вы можете перенаправить пользователя на конечную точку согласия администратора на платформе идентификации Microsoft .
// Line breaks are for legibility only.
GET https://login.microsoftonline.com/{tenant}/adminconsent?
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&state=12345
&redirect_uri=http://localhost/myapp/permissions
Полезный совет: Попробуйте вставить следующий запрос в браузере.
https://login.microsoftonline.com/common/adminconsent?client_id=00001111-aaaa-2222-bbbb-3333cccc4444&state=12345&redirect_uri=http://localhost/myapp/permissions
| Параметр | Состояние | Описание |
|---|---|---|
tenant |
Обязательно | Клиент каталога, из которого необходимо запросить разрешение. Это может быть в формате GUID или в формате понятного имени. Если вы не знаете, к какому тенанту принадлежит пользователь, и вы хотите разрешить ему войти в любой тенант, используйте common. |
client_id |
Обязательно | Идентификатор приложения (клиента), который центр администрирования Microsoft Entra — Регистрация приложений присвоил вашему приложению. |
redirect_uri |
Обязательно | URI перенаправления, по которому вы хотите, чтобы был отправлен ответ для обработки вашим приложением. Он должен точно соответствовать одному из URI перенаправления, зарегистрированных на портале, за исключением того, что он должен быть закодирован URL-адресом, и он может иметь дополнительные сегменты пути. |
state |
Рекомендуется | Значение, включенное в запрос и возвращаемое в ответе токена. Это может быть строка любого нужного содержимого. Состояние используется для кодирования информации о состоянии пользователя в приложении до выполнения запроса аутентификации, например, о странице или представлении, на которых они находились. |
На этом этапе Microsoft Entra ID требует, чтобы только администратор арендатора мог войти в систему для завершения запроса. Администратору будет предложено утвердить все запрошенные вами для вашего приложения разрешения на непосредственное использование в портале регистрации приложений.
Успешный ответ
Если администратор утвердит разрешения для приложения, успешный ответ выглядит следующим образом:
GET http://localhost/myapp/permissions?tenant=aaaabbbb-0000-cccc-1111-dddd2222eeee&state=state=12345&admin_consent=True
| Параметр | Описание |
|---|---|
tenant |
Тенант каталога, предоставивший вашему приложению запрошенные разрешения, в формате GUID. |
state |
Значение, которое включается в запрос и также возвращается в ответе токена. Это может быть строка любого нужного содержимого. Состояние используется для шифрования информации о состоянии пользователя в приложении перед выполнением запроса на проверку подлинности, например, о странице или представлении, на которых они находились. |
admin_consent |
Задайте значение True. |
Ответ на ошибку
Если администратор не утвердит разрешения для приложения, ответ с ошибкой выглядит следующим образом:
GET http://localhost/myapp/permissions?error=permission_denied&error_description=The+admin+canceled+the+request
| Параметр | Описание |
|---|---|
error |
Строка кода ошибки, которую можно использовать для классификации типов ошибок, и которую можно использовать для реагирования на ошибки. |
error_description |
Определенное сообщение об ошибке, которое поможет определить первопричину ошибки. |
Получив успешный ответ от конечной точки предоставления приложения, ваше приложение получило непосредственные разрешения приложения, которые оно запрашивало. Теперь вы можете запросить маркер для нужного ресурса.
Получите маркер
После получения необходимой авторизации для приложения перейдите к получению маркеров доступа для API. Чтобы получить токен с помощью клиентских учетных данных, отправьте POST-запрос на платформу идентификации Microsoft /token. Существует несколько различных случаев:
- запрос токена доступа с общим секретом
- запрос маркера доступа с помощью сертификата
- запрос токена доступа с федеративными учетными данными
Первый случай: запрос токена доступа с общим секретным ключом
POST /{tenant}/oauth2/v2.0/token HTTP/1.1 //Line breaks for clarity
Host: login.microsoftonline.com:443
Content-Type: application/x-www-form-urlencoded
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&scope=https%3A%2F%2Fgraph.microsoft.com%2F.default
&client_secret=qWgdYAmab0YSkuL1qKv5bPX
&grant_type=client_credentials
# Replace {tenant} with your tenant!
curl -X POST -H "Content-Type: application/x-www-form-urlencoded" -d 'client_id=00001111-aaaa-2222-bbbb-3333cccc4444&scope=https%3A%2F%2Fgraph.microsoft.com%2F.default&client_secret=A1bC2dE3f...&grant_type=client_credentials' 'https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token'
| Параметр | Состояние | Описание |
|---|---|---|
tenant |
Обязательно | Арендатор каталога, с которым приложение планирует взаимодействовать, в формате GUID или имени домена. |
client_id |
Обязательно | Идентификатор приложения, назначенный приложению. Эти сведения можно найти на портале, где вы зарегистрировали приложение. |
scope |
Обязательно | Значение, переданное для параметра scope в этом запросе, должно быть идентификатором ресурса (URI идентификатора приложения) ресурса, суффиксированного с .default. Все области должны относиться к одному ресурсу. Включение областей для нескольких ресурсов приведет к ошибке. В примере Microsoft Graph значение равно https://graph.microsoft.com/.default. Это значение сообщает платформе удостоверений Майкрософт, что из всех настроенных разрешений для вашего приложения, конечная точка должна выдать токен для тех, которые связаны с используемым вами ресурсом. Дополнительные сведения об области /.default см. в документации по согласию . |
client_secret |
Обязательно | Секрет клиента, созданный для приложения на портале регистрации приложений. Перед отправкой секрет клиента должен быть закодирован URL-адресом. Также поддерживается шаблон базовой проверки подлинности вместо предоставления учетных данных в заголовке авторизации согласно RFC 6749. |
grant_type |
Обязательно | Необходимо задать значение client_credentials. |
Второй случай: запрос токена доступа с сертификатом
POST /{tenant}/oauth2/v2.0/token HTTP/1.1 // Line breaks for clarity
Host: login.microsoftonline.com:443
Content-Type: application/x-www-form-urlencoded
scope=https%3A%2F%2Fgraph.microsoft.com%2F.default
&client_id=11112222-bbbb-3333-cccc-4444dddd5555
&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer
&client_assertion=eyJhbGciOiJSUzI1NiIsIng1dCI6Imd4OHRHeXN5amNScUtqRlBuZDdSRnd2d1pJMCJ9.eyJ{a lot of characters here}M8U3bSUKKJDEg
&grant_type=client_credentials
| Параметр | Состояние | Описание |
|---|---|---|
tenant |
Обязательно | Клиент каталога, с которым приложение планирует работать в формате GUID или доменного имени. |
client_id |
Обязательно | Идентификатор приложения (клиента), назначенный приложению. |
scope |
Обязательно | Значение, переданное для параметра scope в этом запросе, должно быть идентификатором ресурса (URI идентификатора приложения), к которому добавлен суффикс .default. Все области должны применяться к одному ресурсу. Включение областей для нескольких ресурсов приведет к ошибке. В примере Microsoft Graph значение равно https://graph.microsoft.com/.default. Это значение сообщает платформе управления удостоверениями Майкрософт о том, что из всех разрешений прямого доступа, которые вы настроили для своего приложения, конечная точка должна выдавать токен для тех, которые связаны с используемым вами ресурсом. Дополнительные сведения об области /.default см. в документации по согласию. |
client_assertion_type |
Обязательно | Значение должно быть установлено на urn:ietf:params:oauth:client-assertion-type:jwt-bearer. |
client_assertion |
Обязательно | Утверждение (веб-токен JSON), которое необходимо создать и подписать с помощью сертификата, зарегистрированного в качестве учетных данных для приложения. Ознакомьтесь с информацией об учетных данных сертификата, чтобы узнать, как зарегистрировать сертификат и задать формат утверждения. |
grant_type |
Обязательно | Необходимо задать значение client_credentials. |
Параметры для запроса на основе сертификатов отличаются только одним способом от общего запроса на основе секретов: параметр client_secret заменяется client_assertion_type и client_assertion параметрами.
Третий случай: запрос токена доступа с федеративными учетными данными
POST /{tenant}/oauth2/v2.0/token HTTP/1.1 // Line breaks for clarity
Host: login.microsoftonline.com:443
Content-Type: application/x-www-form-urlencoded
scope=https%3A%2F%2Fgraph.microsoft.com%2F.default
&client_id=11112222-bbbb-3333-cccc-4444dddd5555
&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer
&client_assertion=eyJhbGciOiJSUzI1NiIsIng1dCI6Imd4OHRHeXN5amNScUtqRlBuZDdSRnd2d1pJMCJ9.eyJ{a lot of characters here}M8U3bSUKKJDEg
&grant_type=client_credentials
| Параметр | Состояние | Описание |
|---|---|---|
client_assertion |
Обязательно | Утверждение (JWT или веб-токен JSON), которое приложение получает от другого поставщика удостоверений за пределами платформы удостоверений Майкрософт, например Kubernetes. Особенности этого JWT должны быть зарегистрированы в вашем приложении как учетные данные федеративного удостоверения . Ознакомьтесь с федерацией удостоверений для рабочих нагрузок, чтобы узнать, как настроить и использовать утверждения, созданные другими поставщиками удостоверений. |
Все в запросе совпадает с потоком на основе сертификатов, за исключением источника client_assertion. В этом потоке приложение не создает само утверждение JWT. Вместо этого приложение использует JWT, созданный другим поставщиком удостоверений. Это называется федерацией удостоверений рабочей нагрузки, где идентичности ваших приложений на другой платформе удостоверений используются для получения токенов внутри платформы удостоверений Майкрософт. Это лучше всего подходит для межоблачных сценариев, таких как размещение вычислительных ресурсов за пределами Azure, но доступ к API, защищенным платформой удостоверений Майкрософт. Для получения информации о требуемом формате JWT, созданных другими поставщиками удостоверений, прочитайте о формате утверждения .
Успешный ответ
Успешный ответ любого метода выглядит следующим образом:
{
"token_type": "Bearer",
"expires_in": 3599,
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik1uQ19WWmNBVGZNNXBP..."
}
| Параметр | Описание |
|---|---|
access_token |
Запрашиваемый маркер доступа. Приложение может использовать этот маркер для проверки подлинности в защищенном ресурсе, например в веб-API. |
token_type |
Указывает значение типа токена. Единственным типом, поддерживаемым платформой удостоверений Майкрософт, является bearer. |
expires_in |
Время действия токена доступа (в секундах). |
Предупреждение
Не пытайтесь проверять или читать токены для любого API, которые вам не принадлежат, включая токены в этом примере в вашем коде. Маркеры для служб Майкрософт могут использовать специальный формат, который не будет проверяться на соответствие JWT, и также могут быть зашифрованы для пользователей учетной записи Microsoft. Хотя чтение маркеров — это полезное средство отладки и обучения, не полагайтесь на это в коде и не допускайте предположений о маркерах, которые не относятся к API, которым вы управляете.
Ответ на ошибку
Ответ об ошибке (400 недопустимый запрос) выглядит следующим образом:
{
"error": "invalid_scope",
"error_description": "AADSTS70011: The provided value for the input parameter 'scope' is not valid. The scope https://foo.microsoft.com/.default is not valid.\r\nTrace ID: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: 2016-01-09 02:02:12Z",
"error_codes": [
70011
],
"timestamp": "YYYY-MM-DD HH:MM:SSZ",
"trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333",
"correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
}
| Параметр | Описание |
|---|---|
error |
Строка кода ошибки, которую можно использовать для классификации типов возникающих ошибок и реагирования на ошибки. |
error_description |
Определенное сообщение об ошибке, которое может помочь определить первопричину ошибки проверки подлинности. |
error_codes |
Список кодов ошибок, специфичных для STS, которые могут помочь при диагностике. |
timestamp |
Время возникновения ошибки. |
trace_id |
Уникальный идентификатор запроса, помогающий в диагностике. |
correlation_id |
Уникальный идентификатор запроса, помогающий в диагностике между компонентами. |
Используйте маркер
Теперь, когда вы получили токен, используйте его для выполнения запросов к ресурсу. По истечении срока действия маркера повторите запрос к конечной точке /token, чтобы получить новый маркер доступа.
GET /v1.0/users HTTP/1.1
Host: graph.microsoft.com:443
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbG...
Выполните следующую команду в терминале, чтобы заменить маркер собственным.
curl -X GET -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbG..." 'https://graph.microsoft.com/v1.0/users'
Примеры кода и другая документация
Ознакомьтесь с обзорной документацией по учетным данным клиента из библиотеки проверки подлинности Майкрософт
| Образец | Платформа | Описание |
|---|---|---|
| active-directory-dotnetcore-daemon-v2 | .NET 6.0+ | Приложение ASP.NET Core, отображающее пользователей клиента, запрашивающего Microsoft Graph, с помощью удостоверения приложения, а не от имени пользователя. В примере также показан вариант использования сертификатов для проверки подлинности. |
| active-directory-dotnet-daemon-v2 | ASP.NET MVC | Веб-приложение, которое синхронизирует данные из Microsoft Graph с помощью идентификатора приложения, а не от имени пользователя. |
| ms-identity-javascript-nodejs-console | Node.js консоль | Приложение Node.js, отображающее пользователей клиента, осуществляющее запрос к Microsoft Graph, используя идентификацию приложения. |