Получение доступа без пользователя
Чтобы вызвать Microsoft Graph, приложение должно получить маркер доступа из платформа удостоверений Майкрософт. Этот маркер доступа содержит сведения о том, авторизовано ли приложение для доступа к Microsoft Graph от имени пользователя, выполнившего вход, или с собственным удостоверением. В этой статье содержатся рекомендации по доступу приложения к Microsoft Graph с помощью собственного удостоверения, также называемого доступом только для приложений.
В этой статье описываются необработанные HTTP-запросы, связанные с тем, чтобы приложение вызывало Microsoft Graph с собственным удостоверением с помощью популярного потока, называемого потоком предоставления учетных данных клиента OAuth 2.0. Кроме того, можно избежать написания необработанных HTTP-запросов и использовать созданную или поддерживаемую корпорацией Майкрософт библиотеку проверки подлинности, которая обрабатывает многие из этих сведений и помогает получить маркеры доступа и вызвать Microsoft Graph. Дополнительные сведения см. в статье Использование библиотеки проверки подлинности Майкрософт (MSAL).
Предварительные требования
Прежде чем перейти к действиям, описанным в этой статье:
- Основные понятия проверки подлинности и авторизации в платформа удостоверений Майкрософт. Дополнительные сведения см. в статье Основы проверки подлинности и авторизации.
- Зарегистрируйте приложение с помощью Microsoft Entra ID. Дополнительные сведения см. в разделе Регистрация приложения с помощью платформа удостоверений Майкрософт.
Этапы аутентификации и авторизации
Чтобы приложение авторизации и доступа к Microsoft Graph с помощью потока учетных данных клиента, необходимо выполнить следующие пять действий:
- Зарегистрируйте приложение с помощью Microsoft Entra ID.
- Настройка разрешений приложения Microsoft Graph для приложения.
- Запрос согласия администратора.
- Запрос маркера доступа.
- Вызовите Microsoft Graph с помощью маркера доступа.
1. Регистрация приложения
Прежде чем приложение сможет использовать конечную точку платформа удостоверений Майкрософт или вызвать Microsoft Graph, оно должно быть правильно зарегистрировано. Выполните действия, чтобы зарегистрировать приложение на Центр администрирования Microsoft Entra.
В регистрации приложения сохраните следующие значения:
- Идентификатор приложения (называемый идентификатором объекта на Центр администрирования Microsoft Entra), назначенный порталом регистрации приложений.
- Секрет клиента (пароль приложения), сертификат или учетные данные федеративного удостоверения.
- Универсальный код ресурса (URI) перенаправления для приложения для получения ответов маркера от Microsoft Entra ID.
- URI перенаправления для службы, чтобы получать ответы согласия администратора, если приложение реализует функцию запроса согласия администратора.
2. Настройка разрешений для Microsoft Graph
Microsoft Graph предоставляет разрешения приложений для приложений, которые вызывают Microsoft Graph по собственному удостоверению. Для этих разрешений всегда требуется согласие администратора.
Необходимо предварительно настроить разрешения приложения, необходимые приложению при регистрации приложения. Администратор может согласиться на эти разрешения либо с помощью Центр администрирования Microsoft Entra при установке приложения в своей организации, либо предоставить возможность регистрации в приложении, с помощью которой администраторы могут согласиться на настроенные вами разрешения. После того как Microsoft Entra ID записывает согласие администратора, приложение может запрашивать маркеры без необходимости повторно запрашивать согласие.
Чтобы настроить разрешения приложения для приложения на портале регистрации приложений Azure, выполните следующие действия.
- На странице разрешений API приложения выберите Добавить разрешение.
- Выберите Microsoft Graph.
- Выберите Разрешения приложения.
- В диалоговом окне Выбор разрешений выберите разрешения для настройки приложения.
На приведенном ниже снимке экрана показано диалоговое окно Выбор разрешений с разрешениями приложения в Microsoft Graph.
Важно!
Всегда настраивайте наименее привилегированный набор разрешений, необходимых приложению. Дополнительные сведения см. в статье Рекомендации по использованию разрешений Microsoft Graph.
3. Запрос согласия администратора
Администраторы могут предоставить необходимые приложению разрешения на Центр администрирования 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. |
4. Запрос маркера доступа
В потоке предоставления учетных данных клиента 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=qWgdYAmab0YSkuL1qKv5bPX
&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 |
5. Вызов 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": "Adams@Contoso.com",
"mobilePhone": null,
"officeLocation": null,
"preferredLanguage": null,
"surname": null,
"userPrincipalName": "Adams@Contoso.com",
"id": "8afc02cb-4d62-4dba-b536-9f6d73e9be26"
},
{
"businessPhones": [
"+1 425 555 0109"
],
"displayName": "Adele Vance",
"givenName": "Adele",
"jobTitle": "Retail Manager",
"mail": "AdeleV@Contoso.com",
"mobilePhone": null,
"officeLocation": "18/2111",
"preferredLanguage": null,
"surname": "Vance",
"userPrincipalName": "AdeleV@Contoso.com",
"id": "59bb3898-0621-4414-ac61-74f9d7201355"
}
]
}
Поддерживаемые сценарии приложений и ресурсы
Приложения, вызывающие Microsoft Graph от своего имени, делятся на две категории:
- Фоновые службы (управляющие программы), которые работают на сервере без выполнившего вход пользователя.
- Приложения, которые имеют пользователя, выполнившего вход, но также вызывают Microsoft Graph с собственным удостоверением. Например, чтобы использовать функции, требующие более высоких привилегий, чем у пользователя.
В этой статье приложение использовало секрет клиента в качестве учетных данных. При необходимости можно настроить сертификат или учетные данные федеративного удостоверения.
Дополнительные сведения о приложениях, которые вызывают Microsoft Graph по собственному удостоверению и используют поток учетных данных клиента, см . в статье Потоки проверки подлинности и сценарии приложений: управляющее приложение, которое вызывает веб-API в имени управляющей программы.
Использование библиотеки проверки подлинности Майкрософт (MSAL)
В этой статье описаны сведения о низкоуровневом протоколе, обычно необходимые только при создании и выдаче необработанных HTTP-запросов для выполнения потока учетных данных клиента. В рабочих приложениях используйте встроенную или поддерживаемую корпорацией Майкрософт библиотеку проверки подлинности, например библиотеку проверки подлинности Майкрософт (MSAL), чтобы получать маркеры безопасности и вызывать защищенные веб-API, такие как Microsoft Graph.
MSAL и другие поддерживаемые библиотеки проверки подлинности упрощают процесс, обрабатывая такие сведения, как проверка, обработка файлов cookie, кэширование маркеров и безопасные подключения, что позволяет сосредоточиться на функциональных возможностях приложения.
Корпорация Майкрософт создала и поддерживает широкий выбор примеров кода, демонстрирующих использование поддерживаемых библиотек проверки подлинности с платформа удостоверений Майкрософт. Чтобы получить доступ к этим примерам кода, см. платформа удостоверений Майкрософт примеры кода.
Связанные материалы
- Выберите один из примеров кода, которые создаются и обслуживаются корпорацией Майкрософт для запуска пользовательских приложений, использующих поддерживаемые библиотеки проверки подлинности, пользователей для входа и вызова Microsoft Graph. Ознакомьтесь с руководствами по Microsoft Graph.
Обратная связь
Ожидается в ближайшее время: в течение 2024 года мы постепенно откажемся от GitHub Issues как механизма обратной связи для контента и заменим его новой системой обратной связи. Дополнительные сведения см. в разделе https://aka.ms/ContentUserFeedback.
Отправить и просмотреть отзыв по