Получение доступа от имени пользователя
Чтобы вызвать Microsoft Graph, приложение должно получить маркер доступа из платформа удостоверений Майкрософт. Этот маркер доступа содержит сведения о том, авторизовано ли приложение для доступа к Microsoft Graph от имени пользователя, выполнившего вход, или с собственным удостоверением. В этой статье содержатся рекомендации по тому, как приложение может получить доступ к Microsoft Graph от имени пользователя, который также называется делегированным доступом.
В этой статье описаны необработанные HTTP-запросы, связанные с приложением для получения доступа от имени пользователя с помощью популярного потока, называемого потоком предоставления кода авторизации OAuth 2.0. Кроме того, можно избежать написания необработанных HTTP-запросов и использовать созданную или поддерживаемую корпорацией Майкрософт библиотеку проверки подлинности, которая обрабатывает многие из этих сведений и помогает получить маркеры доступа и вызвать Microsoft Graph. Дополнительные сведения см. в статье Использование библиотеки проверки подлинности Майкрософт (MSAL).
Предварительные требования
Прежде чем перейти к действиям, описанным в этой статье:
- Основные понятия проверки подлинности и авторизации в платформа удостоверений Майкрософт. Дополнительные сведения см. в статье Основы проверки подлинности и авторизации.
- Зарегистрируйте приложение с помощью Microsoft Entra ID. Дополнительные сведения см. в разделе Регистрация приложения с помощью платформа удостоверений Майкрософт.
Этапы аутентификации и авторизации
Чтобы приложение авторизации и доступ к Microsoft Graph с помощью потока кода авторизации, выполните следующие пять действий:
- Зарегистрируйте приложение с помощью Microsoft Entra ID.
- Запрос авторизации.
- Запрос маркера доступа.
- Вызов Microsoft Graph с помощью маркера доступа.
- [Необязательно] Используйте маркер обновления для продления маркера доступа с истекшим сроком действия.
1. Регистрация приложения
Прежде чем приложение сможет вызывать конечные точки платформа удостоверений Майкрософт или Microsoft Graph, оно должно быть правильно зарегистрировано. Выполните действия, чтобы зарегистрировать приложение на Центр администрирования Microsoft Entra.
В регистрации приложения сохраните следующие значения:
- Идентификатор приложения (называемый идентификатором объекта на Центр администрирования Microsoft Entra), назначенный порталом регистрации приложений.
- URI перенаправления (или URL-адрес ответа), чтобы приложение получало ответы от Microsoft Entra ID.
- Секрет клиента (пароль приложения), сертификат или учетные данные федеративного удостоверения. Это свойство не требуется для общедоступных клиентов, таких как собственные, мобильные и одностраничные приложения.
2. Запрос авторизации
Первый шаг в потоке кода авторизации заключается в том, чтобы пользователь разрешил приложению действовать от его имени.
В потоке приложение перенаправляет пользователя в конечную точку платформа удостоверений Майкрософт/authorize. Через эту конечную точку Microsoft Entra ID входит в систему пользователя и запрашивает его согласие на разрешения, запрашиваемые приложением. После получения согласия Microsoft Entra ID вернет в приложение код авторизации. Затем приложение может активировать этот код в конечной точке платформа удостоверений Майкрософт /token для маркера доступа.
Запрос авторизации
В следующем примере показан запрос к конечной точке /authorize .
В URL-адресе запроса вызывается /authorize конечная точка и указываются обязательные и рекомендуемые свойства в качестве параметров запроса.
В следующем примере приложение запрашивает разрешения User.Read и Mail.Read Microsoft Graph, которые позволяют приложению читать профиль и почту пользователя, выполнившего вход, соответственно. Разрешение offline_access — это стандартная область OIDC, запрашиваемая для получения приложения маркера обновления. Приложение может использовать маркер обновления для получения нового маркера доступа по истечении срока действия текущего маркера.
// Line breaks for legibility only
GET https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize?
client_id=11111111-1111-1111-1111-111111111111
&response_type=code
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&response_mode=query
&scope=offline_access%20user.read%20mail.read
&state=12345 HTTP/1.1
Параметры
| Параметр | Обязательный | Описание |
|---|---|---|
| tenant | Обязательный | С помощью значения {tenant} в пути запроса можно указывать, кто может входить в приложение. Возможные значения:common — как для учетных записей Майкрософт, так и для рабочих или учебных рабочих записей.organizations — только для рабочих и учебных учетных записейconsumers — только для учетных записей МайкрософтДополнительные сведения см. в статье Основные сведения о протоколе. |
| client_id | Обязательный | Идентификатор приложения (клиента), которому портал регистрации назначил приложение. Также называется appId в объекте приложения Microsoft Graph и субъекта-службы. |
| response_type | Обязательный | Должен включать code для потока кода авторизации OAuth 2.0. |
| redirect_uri | Рекомендовано | URI перенаправления приложения, куда отправляются и получаются ответы проверки подлинности. Он должен точно соответствовать одному из URI перенаправления, зарегистрированных на портале регистрации приложений, за исключением того, что он должен быть закодирован URL-адресом. Для собственных и мобильных приложений следует использовать значение https://login.microsoftonline.com/common/oauth2/nativeclientпо умолчанию . |
| область | Обязательный | Разделенный пробелами список разрешений Microsoft Graph, на предоставление которых должен согласиться пользователь. Эти разрешения могут включать разрешения ресурсов, такие как User.Read и Mail.Read, а также области OIDC, такие как offline_access, что указывает, что приложению требуется маркер обновления для долгосрочного доступа к ресурсам. |
| response_mode | Рекомендовано | Указывает метод, который следует использовать для отправки полученного маркера обратно в приложение. Допустимые значения: query и form_post. |
| state | Рекомендуемый | Значение, включенное в запрос, которое также возвращается в ответе маркера. Это может быть строка любого содержимого, которое вы хотите. Случайно созданное уникальное значение обычно используется для предотвращения атак с подделкой межсайтовых запросов. Это свойство также используется для кодирования сведений о состоянии пользователя в приложении до выполнения запроса проверки подлинности, например страницы или представления, на которые они находились. |
Взаимодействие с согласием пользователя
После отправки приложением запроса на авторизацию пользователю предлагается ввести свои учетные данные для проверки подлинности в корпорации Майкрософт. Конечная точка платформа удостоверений Майкрософт версии 2.0 гарантирует, что пользователь согласился на разрешения, указанные в параметре scope запроса. Если есть какие-либо разрешения, на которые пользователь или администратор не дал согласия, им будет предложено предоставить согласие на необходимые разрешения. Дополнительные сведения о взаимодействии с Microsoft Entra согласия см. в разделах Взаимодействие с согласием приложений и Введение в разрешения и согласие.
На следующем снимке экрана показан пример диалогового окна согласия для учетной записи Майкрософт.
Отклик на авторизацию
Если пользователь соглашается с разрешениями, запрошенными приложением, ответ содержит код авторизации в параметре code . Ниже приведен пример успешного ответа на предыдущий запрос. response_mode Так как параметру в запросе присвоено значение query, ответ возвращается в строке запроса URL-адреса перенаправления.
HTTP/1.1 200 OK
https://localhost/myapp/?code=M0ab92efe-b6fd-df08-87dc-2c6500a7f84d&state=12345&session_state=fe1540c3-a69a-469a-9fa3-8a2470936421#
Параметры запроса
| Параметр | Описание |
|---|---|
| code | Код авторизации, запрошенный приложением. Приложение использует код авторизации для запроса маркера доступа для целевого ресурса. Коды авторизации недолговечены, как правило, срок их действия истекает примерно через 10 минут. |
| state | Если параметр состояния включен в запрос, то в ответе должно появиться то же значение. Приложение должно убедиться, что значения состояния в запросе и ответе идентичны. Это проверка помогает обнаруживать атаки CSRF на клиент. |
| session_state | Уникальное значение, определяющее текущий сеанс пользователя. Это значение — GUID, но его следует обрабатывать как непрозрачное значение, переданное без проверки. |
3. Запрос маркера доступа
Приложение использует авторизацию code , полученную на предыдущем шаге, для запроса маркера доступа путем отправки POST запроса в конечную точку /token .
Запрос на получение маркера
// Line breaks for legibility only
POST /{tenant}/oauth2/v2.0/token HTTP/1.1
Host: https://login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded
client_id=11111111-1111-1111-1111-111111111111
&scope=user.read%20mail.read
&code=OAAABAAAAiL9Kn2Z27UubvWFPbm0gLWQJVzCTE9UkP3pSx1aXxUjq3n8b2JRLk4OxVXr...
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&grant_type=authorization_code
&client_secret=HF8Q~Krjqh4r... // NOTE: Only required for web apps
Параметры
| Параметр | Обязательный | Описание |
|---|---|---|
| tenant | Обязательный | С помощью значения {tenant} в пути запроса можно указывать, кто может входить в приложение. Возможные значения:common — как для учетных записей Майкрософт, так и для рабочих или учебных рабочих записей.organizations — только для рабочих и учебных учетных записейconsumers — только для учетных записей МайкрософтДополнительные сведения см. в статье Основные сведения о протоколе. |
| client_id | Обязательный | Идентификатор приложения (клиента), которому портал регистрации назначил приложение. Также называется appId в объекте приложения Microsoft Graph и субъекта-службы. |
| grant_type | Обязательный | Должно быть задано значение authorization_code для потока кода авторизации. |
| scope | Обязательный | Разделенный пробелами список областей. Области, запрашиваемые приложением на этом этапе, должны быть эквивалентны или подмножество областей, запрошенных на этапе авторизации на шаге 2. Если области, указанные в этом запросе, охватывают несколько серверов ресурсов, конечная точка версии 2.0 возвращает маркер для ресурса, указанного в первом область. |
| code | Обязательный | Код авторизации, полученный на этапе авторизации на шаге 2. |
| redirect_uri | Обязательный | То же значение URI перенаправления, которое использовалось для получения кода авторизации на шаге 2. |
| client_secret | Требуется для веб-приложений | Секрет клиента, созданный на портале регистрации приложений для приложения. Его не следует использовать в собственном приложении, так как секреты клиента не могут надежно храниться на устройствах. Он необходим для веб-приложений и веб-API, которые могут безопасно хранить client_secret на стороне сервера. |
Ответ с маркером
Маркер доступа содержит список разрешений, для которые подходит маркер доступа в параметре scope . Ответ аналогичен приведенному ниже примеру.
HTTP/1.1 200 OK
Content-type: application/json
{
"token_type": "Bearer",
"scope": "Mail.Read User.Read",
"expires_in": 3736,
"ext_expires_in": 3736,
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...",
"refresh_token": "AwABAAAAvPM1KaPlrEqdFSBzjqfTGAMxZGUTdM0t4B4..."
}
Свойства текста ответа
| Параметр | Описание |
|---|---|
| token_type | Указывает значение типа маркера. Единственный тип, который Microsoft Entra ID поддерживает, — .Bearer |
| область | Разделенный пробелом список разрешений Microsoft Graph, для которые действителен маркер доступа. |
| expires_in | Срок действия маркера доступа (в секундах). |
| ext_expires_in | Указывает продолжительное время существования маркера доступа (в секундах) и используется для поддержки устойчивости, когда служба выдачи маркеров не отвечает. |
| access_token | Запрошенный маркер доступа. Приложение может использовать этот маркер для вызова Microsoft Graph. |
| refresh_token | Маркер обновления OAuth 2.0. Приложение может использовать этот маркер для получения дополнительных маркеров доступа по истечении срока действия текущего маркера доступа. Маркеры обновления имеют большие сроки действия, и с их помощью можно сохранять доступ к ресурсам в течение длительного времени. Маркер обновления будет возвращен только в том случае, если offline_access он был включен в scope качестве параметра. Дополнительные сведения см. в справочнике по маркерам версии 2.0. |
4. Вызов Microsoft Graph с помощью маркера доступа
После получения маркера доступа приложение использует его для вызова Microsoft Graph, вложив маркер доступа в качестве маркера носителя в заголовок Authorization в HTTP-запросе. Следующий запрос получает профиль пользователя, выполнившего вход.
Запрос
GET https://graph.microsoft.com/v1.0/me 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
Duration: 727.0022
Date: Thu, 20 Apr 2017 05:21:18 GMT
Content-Length: 407
{
"@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users/$entity",
"businessPhones": [
"425-555-0100"
],
"displayName": "MOD Administrator",
"givenName": "MOD",
"jobTitle": null,
"mail": "admin@contoso.com",
"mobilePhone": "425-555-0101",
"officeLocation": null,
"preferredLanguage": "en-US",
"surname": "Administrator",
"userPrincipalName": "admin@contoso.com",
"id": "10a08e2e-3ea2-4ce0-80cb-d5fdd4b05ea6"
}
5. Используйте маркер обновления для продления маркера доступа с истекшим сроком действия.
Маркеры доступа являются краткосрочными, и приложение должно обновить их по истечении срока действия, чтобы продолжить доступ к ресурсам. Приложение делает это, отправляя другой POST запрос к конечной точке /token , на этот раз:
refresh_tokenПредоставление вместо кода в тексте запроса- Указание
refresh_tokenв качестве grant_type вместоauthorization_code.
Запрос
// Line breaks for legibility only
POST /{tenant}/oauth2/v2.0/token HTTP/1.1
Host: https://login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded
client_id=11111111-1111-1111-1111-111111111111
&scope=user.read%20mail.read
&refresh_token=OAAABAAAAiL9Kn2Z27UubvWFPbm0gLWQJVzCTE9UkP3pSx1aXxUjq...
&grant_type=refresh_token
&client_secret=jXoM3iz... // NOTE: Only required for web apps
Параметры
| Параметр | Обязательный | Описание |
|---|---|---|
| tenant | Обязательный | С помощью значения {tenant} в пути запроса можно указывать, кто может входить в приложение. Возможные значения:common — как для учетных записей Майкрософт, так и для рабочих или учебных рабочих записей.organizations — только для рабочих и учебных учетных записейconsumers — только для учетных записей МайкрософтДополнительные сведения см. в статье Основные сведения о протоколе. |
| client_id | Обязательный | Идентификатор приложения (клиента), назначенный порталом регистрации приложению. Также называется appId в объекте приложения Microsoft Graph и субъекта-службы. |
| grant_type | Обязательный | Должно быть задано значение refresh_token. |
| scope | Необязательный | Разделенный пробелами список разрешений (областей). Разрешения, запрашиваемые приложением, должны быть эквивалентны или подмножество разрешений, запрошенных в исходном запросе кода авторизации на шаге 2. |
| refresh_token | Обязательный | Refresh_token, полученное приложением во время запроса маркера на шаге 3. |
| client_secret | Требуется для веб-приложений | Секрет клиента, созданный на портале регистрации приложений для приложения. Не используйте секрет в собственном приложении, так как client_secrets не могут надежно храниться на устройствах. Он необходим для веб-приложений и веб-API, которые могут безопасно хранить client_secret на стороне сервера. |
Отклик
Успешный ответ маркера выглядит следующим образом.
HTTP/1.1 200 OK
Content-type: application/json
{
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...",
"token_type": "Bearer",
"expires_in": 3599,
"scope": "Mail.Read User.Read",
"refresh_token": "AwABAAAAvPM1KaPlrEqdFSBzjqfTGAMxZGUTdM0t4B4...",
}
Параметры текста ответа
| Параметр | Описание |
|---|---|
| access_token | Запрошенный маркер доступа. Приложение может использовать этот маркер в вызовах Microsoft Graph. |
| token_type | Указывает значение типа маркера. Единственный тип, который Microsoft Entra ID поддерживает, — .Bearer |
| expires_in | Срок действия маркера доступа (в секундах). |
| scope | Разрешения (области), для которых действителен маркер доступа. |
| refresh_token | Новый маркер обновления OAuth 2.0. Замените старый маркер обновления этим новым маркером обновления, чтобы маркеры обновления оставались действительными как можно дольше. |
Использование библиотеки проверки подлинности Майкрософт (MSAL)
В этой статье описаны сведения о низкоуровневом протоколе, обычно необходимые только при создании и выдаче необработанных HTTP-запросов для выполнения потока кода авторизации. В рабочих приложениях используйте встроенную или поддерживаемую корпорацией Майкрософт библиотеку проверки подлинности, например библиотеку проверки подлинности Майкрософт (MSAL), чтобы получать маркеры безопасности и вызывать защищенные веб-API, такие как Microsoft Graph.
MSAL и другие поддерживаемые библиотеки проверки подлинности упрощают процесс, обрабатывая такие сведения, как проверка, обработка файлов cookie, кэширование маркеров и безопасные подключения, что позволяет сосредоточиться на функциональных возможностях приложения.
Корпорация Майкрософт создала и поддерживает широкий выбор примеров кода, демонстрирующих использование поддерживаемых библиотек проверки подлинности с платформа удостоверений Майкрософт. Чтобы получить доступ к этим примерам кода, см. платформа удостоверений Майкрософт примеры кода.
Связанные материалы
- Вы можете вызывать Microsoft Graph от имени пользователя из различных типов приложений, таких как одностраничные, веб-приложения и мобильные приложения. Дополнительные сведения см. в разделе Сценарии и поддерживаемые потоки проверки подлинности.
- Выберите один из примеров кода, которые создаются и обслуживаются корпорацией Майкрософт для запуска пользовательских приложений, использующих поддерживаемые библиотеки проверки подлинности, пользователей для входа и вызова Microsoft Graph. Ознакомьтесь с руководствами по Microsoft Graph.
Обратная связь
Ожидается в ближайшее время: в течение 2024 года мы постепенно откажемся от GitHub Issues как механизма обратной связи для контента и заменим его новой системой обратной связи. Дополнительные сведения см. в разделе https://aka.ms/ContentUserFeedback.
Отправить и просмотреть отзыв по