Получение доступа без пользователя
Чтобы вызвать Microsoft Graph, приложение должно получить маркер доступа из платформа удостоверений Майкрософт. Этот маркер доступа содержит сведения о том, авторизовано ли приложение для доступа к Microsoft Graph от имени пользователя, выполнившего вход, или с собственным удостоверением. В этой статье содержатся рекомендации по доступу приложения к Microsoft Graph с помощью собственного удостоверения, также называемого доступом только для приложений.
В этой статье описываются необработанные HTTP-запросы, связанные с тем, чтобы приложение вызывало Microsoft Graph с собственным удостоверением с помощью популярного потока, называемого потоком предоставления учетных данных клиента OAuth 2.0. Кроме того, можно избежать написания необработанных HTTP-запросов и использовать созданную или поддерживаемую корпорацией Майкрософт библиотеку проверки подлинности, которая помогает получать маркеры доступа и вызывать Microsoft Graph. Дополнительные сведения см. в статье Использование библиотеки проверки подлинности Майкрософт (MSAL).
В этой статье описано, как использовать поток учетных данных клиента:
- Настройка разрешений приложения Microsoft Graph для приложения.
- Запрос согласия администратора.
- Запрос маркера доступа.
- Вызовите Microsoft Graph с помощью маркера доступа.
Предварительные условия
Прежде чем перейти к действиям, описанным в этой статье:
- Основные понятия проверки подлинности и авторизации в платформа удостоверений Майкрософт. Дополнительные сведения см. в статье Основы проверки подлинности и авторизации.
- Зарегистрируйте приложение с помощью Microsoft Entra ID. Дополнительные сведения см. в разделе Регистрация приложения с помощью платформа удостоверений Майкрософт. Сохраните следующие значения из регистрации приложения:
- Идентификатор приложения (в Центр администрирования Microsoft Entra называется идентификатором объекта).
- Секрет клиента (пароль приложения), сертификат или учетные данные федеративного удостоверения.
- Универсальный код ресурса (URI) перенаправления для приложения для получения ответов маркера от Microsoft Entra ID.
- URI перенаправления для службы, чтобы получать ответы согласия администратора, если приложение реализует функцию запроса согласия администратора.
Шаг 1. Настройка разрешений для Microsoft Graph
Microsoft Graph предоставляет разрешения приложений для приложений, которые вызывают Microsoft Graph с собственным удостоверением. Для этих разрешений всегда требуется согласие администратора.
Вы предварительно настроите разрешения приложения, необходимые приложению при регистрации приложения. Администратор может согласиться на эти разрешения либо с помощью Центр администрирования Microsoft Entra при установке приложения в своей организации, либо предоставить возможность регистрации в приложении, с помощью которой администраторы могут согласиться на настроенные вами разрешения. После того как Microsoft Entra ID записывает согласие администратора, приложение может запрашивать маркеры без необходимости повторно запрашивать согласие.
Чтобы настроить разрешения приложения в интерфейсе регистрации приложений на Центр администрирования Microsoft Entra, выполните следующие действия.
- На странице разрешений API приложения выберите Добавить разрешение.
- Выберите Microsoft Graph> , выберите Разрешения приложения.
- В диалоговом окне Выбор разрешений выберите разрешения для настройки приложения.
На приведенном ниже снимке экрана показано диалоговое окно Выбор разрешений с разрешениями приложения в Microsoft Graph.
Важно!
Всегда настраивайте наименее привилегированный набор разрешений, необходимых приложению. Дополнительные сведения см. в статье Рекомендации по использованию разрешений Microsoft Graph.
Шаг 2. Запрос согласия администратора
Администраторы могут предоставить необходимые приложению разрешения на Центр администрирования Microsoft Entra. Однако если у вас нет доступа к Центр администрирования Microsoft Entra, вы можете предоставить возможность регистрации для администраторов с помощью конечной точки платформа удостоверений Майкрософт/adminconsent.
Важно!
При изменении настроенных разрешений необходимо получить повторное согласие администратора. Изменения, внесенные на портале регистрации приложений, не отражаются до тех пор, пока авторизованный администратор, например администратор привилегированных ролей, не повторно перейдет к приложению.
Запрос
// Line breaks are for legibility only.
GET https://login.microsoftonline.com/{tenant}/adminconsent
?client_id=6731de76-14a6-49ae-97bc-6eba6914391e
&state=12345
&redirect_uri=https://localhost/myapp/permissions HTTP/1.1
| Параметр | Условие | Описание |
|---|---|---|
| tenant | Обязательный | Клиент, у которого требуется запросить разрешение. Значение может быть в формате GUID или понятном формате имени. Если вы не знаете, к какому клиенту принадлежит пользователь, и вы хотите разрешить ему войти в любой клиент, используйте .common |
| client_id | Обязательный | Идентификатор приложения, назначенный порталом Azure для регистрации приложений. |
| redirect_uri | Обязательный | URI перенаправления, куда нужно отправить ответ для обработки приложения. Он должен соответствовать одному из URI перенаправления, зарегистрированным на портале. Он должен быть закодирован URL-адресом и может содержать дополнительные сегменты пути. |
| state | Рекомендуемый | Значение, включаемое в запрос, который также возвращается в ответе маркера. Это может быть строка любого нужного содержимого. Состояние используется для кодирования сведений о состоянии пользователя в приложении до выполнения запроса проверки подлинности, например страницы или представления, на которые они находились. |
Предоставление согласия администратора
При выполнении запросов к конечной точке /adminconsent Microsoft Entra ID принудительно требует, чтобы только авторизованный администратор смог войти в систему для выполнения запроса. Администратору будет предложено утвердить все разрешения приложения, запрошенные для приложения на портале регистрации приложений.
На следующем снимке экрана показан пример диалогового окна согласия, которое Microsoft Entra ID представляет администратору:
Ответ
Если администратор утверждает разрешения для приложения, успешный ответ выглядит так:
// Line breaks are for legibility only.
https://localhost/myapp/permissions?admin_consent=True&tenant=38d49456-54d4-455d-a8d6-c383c71e0a6d&state=12345#
| Параметр | Описание |
|---|---|
| tenant | Клиент, предоставив приложению запрошенные разрешения в формате GUID. |
| state | Значение, включаемое в запрос, который также возвращается в ответе маркера. Это может быть строка любого нужного содержимого. Состояние используется для кодирования сведений о состоянии пользователя в приложении до выполнения запроса проверки подлинности, например страницы или представления, на которые они находились. |
| admin_consent | Задайте значение True. |
Шаг 3. Запрос маркера доступа
В потоке предоставления учетных данных клиента OAuth 2.0 вы используете идентификатор приложения и секрет клиента, сохраненные во время регистрации приложения, чтобы запросить маркер доступа непосредственно из конечной точки /token платформы удостоверений Майкрософт.
Предварительно настроенные разрешения указываются путем передачи https://graph.microsoft.com/.default в качестве значения параметра scope в запросе маркера.
Запрос на получение маркера
Отправьте запрос POST в конечную точку /token платформы удостоверений для получения маркера доступа. В этом запросе клиент использует секрет клиента.
// Line breaks are for legibility only.
POST https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token HTTP/1.1
Host: login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded
client_id=535fb089-9ff3-47b6-9bfb-4f1264799865
&scope=https%3A%2F%2Fgraph.microsoft.com%2F.default
&client_secret=qWgdYA....L1qKv5bPX
&grant_type=client_credentials
| Параметр | Условие | Описание |
|---|---|---|
| tenant | Обязательный | Клиент, у которого требуется запросить разрешение. Значение может быть в формате GUID или понятном формате имени. |
| client_id | Обязательный | Идентификатор приложения, назначенный порталом Azure для регистрации приложений при регистрации приложения. |
| область | Обязательный | Значение, передаваемое параметру этого запроса, должно представлять собой идентификатор (URI идентификатора приложения) нужного ресурса, дополненный суффиксом .default. Например, универсальный код ресурса приложения Microsoft Graph имеет значениеhttps://graph.microsoft.com/. Таким образом, для Microsoft Graph значением запроса является https://graph.microsoft.com/.default. Это значение сообщает конечной точке платформы удостоверений Майкрософт включить в маркер доступа все разрешения на уровне приложения, на которые дал согласие администратор. |
| client_secret | Обязательный | Секрет клиента, созданный для приложения на портале регистрации приложений. Убедитесь, что это URL-адрес закодирован. |
| grant_type | Обязательный | Должно быть задано значение client_credentials. |
Ответ с маркером
Успешный ответ выглядит так:
{
"token_type": "Bearer",
"expires_in": 3599,
"ext_expires_in":3599,
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik1uQ19WWmNBVGZNNXBP..."
}
| Параметр | Описание |
|---|---|
| access_token | Запрошенный маркер доступа. Приложение может использовать этот маркер в вызовах Microsoft Graph. |
| expires_in | Срок действия маркера доступа (в секундах). |
| ext_expires_in | Используется для указания длительного времени существования маркера доступа и для поддержки устойчивости, когда служба выдачи маркеров не отвечает. |
| token_type | Указывает значение типа маркера. Единственный тип, который Microsoft Entra ID поддерживает, — .Bearer |
Шаг 4. Вызов Microsoft Graph с помощью маркера доступа
После получения маркера доступа приложение использует его для вызова Microsoft Graph, вложив маркер доступа в качестве маркера носителя в заголовок Authorization в HTTP-запросе. Следующий запрос получает всех пользователей в клиенте. Приложение должно иметь разрешение User.Read.All для вызова этого API.
GET https://graph.microsoft.com/v1.0/users HTTP/1.1
Authorization: Bearer eyJ0eXAiO ... 0X2tnSQLEANnSPHY0gKcgw
Host: graph.microsoft.com
Успешный ответ выглядит следующим образом (некоторые заголовки ответа были удалены):
HTTP/1.1 200 OK
Content-Type: application/json;odata.metadata=minimal;odata.streaming=true;IEEE754Compatible=false;charset=utf-8
request-id: f45d08c0-6901-473a-90f5-7867287de97f
client-request-id: f45d08c0-6901-473a-90f5-7867287de97f
OData-Version: 4.0
Date: Wed, 26 Apr 2017 19:53:49 GMT
Content-Length: 407
{
"@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users",
"value": [
{
"businessPhones": [],
"displayName": "Conf Room Adams",
"givenName": null,
"jobTitle": null,
"mail": "[email protected]",
"mobilePhone": null,
"officeLocation": null,
"preferredLanguage": null,
"surname": null,
"userPrincipalName": "[email protected]",
"id": "8afc02cb-4d62-4dba-b536-9f6d73e9be26"
},
{
"businessPhones": [
"+1 425 555 0109"
],
"displayName": "Adele Vance",
"givenName": "Adele",
"jobTitle": "Retail Manager",
"mail": "[email protected]",
"mobilePhone": null,
"officeLocation": "18/2111",
"preferredLanguage": null,
"surname": "Vance",
"userPrincipalName": "[email protected]",
"id": "59bb3898-0621-4414-ac61-74f9d7201355"
}
]
}
Поддерживаемые сценарии приложений и ресурсы
Приложения, вызывающие Microsoft Graph с собственным удостоверением, делятся на одну из двух категорий:
- Фоновые службы (управляющие программы), которые работают на сервере без выполнившего вход пользователя.
- Приложения, которые имеют пользователя, выполнившего вход, но также вызывают Microsoft Graph с собственным удостоверением. Например, чтобы использовать функции, требующие более высоких привилегий, чем у пользователя.
В этой статье приложение использовало секрет клиента в качестве учетных данных. При необходимости можно настроить сертификат или учетные данные федеративного удостоверения.
Дополнительные сведения о приложениях, которые вызывают Microsoft Graph с собственным удостоверением и используют поток учетных данных клиента, см . в статье Потоки проверки подлинности и сценарии приложений: управляющая программа, которая вызывает веб-API в имени управляющей программы.
Использование библиотеки проверки подлинности Майкрософт (MSAL)
В этой статье описаны сведения о низкоуровневом протоколе, необходимые только при создании и выдаче необработанных HTTP-запросов для выполнения потока учетных данных клиента. В рабочих приложениях используйте встроенную или поддерживаемую корпорацией Майкрософт библиотеку проверки подлинности, например библиотеку проверки подлинности Майкрософт (MSAL), чтобы получать маркеры безопасности и вызывать защищенные веб-API, такие как Microsoft Graph.
MSAL и другие поддерживаемые библиотеки проверки подлинности упрощают процесс, обрабатывая такие сведения, как проверка, обработка файлов cookie, кэширование маркеров и безопасные подключения; позволяет сосредоточиться на функциональных возможностях приложения.
Ознакомьтесь с примерами кода платформа удостоверений Майкрософт, чтобы узнать, как использовать MSAL для получения маркеров доступа и вызова Microsoft Graph.
Связанные материалы
Ознакомьтесь с руководствами по Microsoft Graph , чтобы создать базовые приложения, которые получают доступ к данным в сценариях только для приложений.