Получение доступа от имени пользователя
Чтобы вызвать Microsoft Graph, приложение должно получить маркер доступа из платформа удостоверений Майкрософт. Этот маркер доступа содержит сведения о том, авторизовано ли приложение для доступа к Microsoft Graph от имени пользователя, выполнившего вход, или с собственным удостоверением. В этой статье содержатся рекомендации по тому, как приложение может получить доступ к Microsoft Graph от имени пользователя, который также называется делегированным доступом.
В этой статье описаны необработанные HTTP-запросы, связанные с приложением для получения доступа от имени пользователя с помощью популярного потока, называемого потоком предоставления кода авторизации OAuth 2.0. Кроме того, можно избежать написания необработанных HTTP-запросов и использовать созданную или поддерживаемую корпорацией Майкрософт библиотеку проверки подлинности, которая обрабатывает многие из этих сведений и помогает получить маркеры доступа и вызвать Microsoft Graph. Дополнительные сведения см. в статье Использование библиотеки проверки подлинности Майкрософт (MSAL).
В этой статье описано, как использовать поток предоставления кода авторизации OAuth 2.0:
- Запрос авторизации.
- Запрос маркера доступа.
- Вызов Microsoft Graph с помощью маркера доступа.
- [Необязательно] Используйте маркер обновления для продления маркера доступа с истекшим сроком действия.
Предварительные условия
Прежде чем перейти к действиям, описанным в этой статье:
- Основные понятия проверки подлинности и авторизации в платформа удостоверений Майкрософт. Дополнительные сведения см. в статье Основы проверки подлинности и авторизации.
- Зарегистрируйте приложение с помощью Microsoft Entra ID. Дополнительные сведения см. в разделе Регистрация приложения с помощью платформа удостоверений Майкрософт. Сохраните следующие значения из регистрации приложения:
- Идентификатор приложения (в Центр администрирования Microsoft Entra называется идентификатором объекта).
- Секрет клиента (пароль приложения), сертификат или учетные данные федеративного удостоверения. Это свойство не требуется для общедоступных клиентов, таких как собственные, мобильные и одностраничные приложения.
- Универсальный код ресурса (URI) перенаправления для приложения для получения ответов маркера от Microsoft Entra ID.
Шаг 1. Запрос авторизации
Первый шаг в потоке кода авторизации заключается в том, чтобы пользователь разрешил приложению действовать от его имени.
В потоке приложение перенаправляет пользователя в конечную точку платформа удостоверений Майкрософт/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, но его следует обрабатывать как непрозрачное значение, переданное без проверки. |
Шаг 2. Запрос маркера доступа
Приложение использует авторизацию 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. |
Шаг 3. Использование маркера доступа для вызова 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"
}
Шаг 4. Обновление маркера доступа с истекшим сроком действия с помощью маркера обновления
Маркеры доступа являются краткосрочными, и приложение должно обновить их по истечении срока действия, чтобы продолжить доступ к ресурсам. Приложение делает это, отправляя другой 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.