Получение доступа от имени пользователя

Чтобы вызвать Microsoft Graph, приложение должно получить маркер доступа из платформа удостоверений Майкрософт. Этот маркер доступа содержит сведения о том, авторизовано ли приложение для доступа к Microsoft Graph от имени пользователя, выполнившего вход, или с собственным удостоверением. В этой статье содержатся рекомендации по тому, как приложение может получить доступ к Microsoft Graph от имени пользователя, который также называется делегированным доступом.

В этой статье описаны необработанные HTTP-запросы, связанные с приложением для получения доступа от имени пользователя с помощью популярного потока, называемого потоком предоставления кода авторизации OAuth 2.0. Кроме того, можно избежать написания необработанных HTTP-запросов и использовать созданную или поддерживаемую корпорацией Майкрософт библиотеку проверки подлинности, которая обрабатывает многие из этих сведений и помогает получить маркеры доступа и вызвать Microsoft Graph. Дополнительные сведения см. в статье Использование библиотеки проверки подлинности Майкрософт (MSAL).

В этой статье описано, как использовать поток предоставления кода авторизации OAuth 2.0:

1. Запрос авторизации.
2. Запрос маркера доступа.
3. Вызов Microsoft Graph с помощью маркера доступа.
4. [Необязательно] Используйте маркер обновления для продления маркера доступа с истекшим сроком действия.

Предварительные условия

Прежде чем перейти к действиям, описанным в этой статье:

1. Основные понятия проверки подлинности и авторизации в платформа удостоверений Майкрософт. Дополнительные сведения см. в статье Основы проверки подлинности и авторизации.
2. Зарегистрируйте приложение с помощью 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

curl --location --request GET 'https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize?client_id=11111111-1111-1111-1111-111111111111&response_type=code&redirect_uri=https%3A%2F%2Flocalhost%2Fmyapp%2F&response_mode=query&scope=offline_access%20User.Read%20Mail.Read&state=12345'

Параметры

Взаимодействие с согласием пользователя

После отправки приложением запроса на авторизацию пользователю предлагается ввести свои учетные данные для проверки подлинности в корпорации Майкрософт. Конечная точка платформа удостоверений Майкрософт версии 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#

Параметры запроса

Шаг 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

curl --location --request POST 'https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id=11111111-1111-1111-1111-111111111111' \
--data-urlencode 'scope=User.Read Mail.Read' \
--data-urlencode 'code=M0ab92efe-b6fd-df08-87dc-2c6500a7f84d' \
--data-urlencode 'redirect_uri=https://localhost/myapp/' \
--data-urlencode 'grant_type=authorization_code' \
--data-urlencode 'client_secret=zHF8Q~Krjqh4r...''

Параметры

Ответ с маркером

Маркер доступа содержит список разрешений, для которые подходит маркер доступа в параметре 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..."
}

Свойства текста ответа

Шаг 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

curl --location --request GET 'https://graph.microsoft.com/v1.0/me' \
--header 'Authorization: Bearer eyJ0eXAiO ... 0X2tnSQLEANnSPHY0gKcgw' \
--data ''

Отклик

Успешный ответ выглядит следующим образом (некоторые заголовки ответа удалены).

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": "[email protected]",
    "mobilePhone": "425-555-0101",
    "officeLocation": null,
    "preferredLanguage": "en-US",
    "surname": "Administrator",
    "userPrincipalName": "[email protected]",
    "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

curl --location --request POST 'https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id=11111111-1111-1111-1111-111111111111' \
--data-urlencode 'scope=User.Read Mail.Read' \
--data-urlencode 'refresh_token=OAAABAAAAiL9Kn2Z27UubvWFPbm0gLWQJVzCTE9UkP3pSx1aXxUjq...' \
--data-urlencode 'grant_type=refresh_token' \
--data-urlencode 'client_secret=jXoM3iz...'

Параметры

Отклик

Успешный ответ маркера выглядит следующим образом.

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...",
}

Параметры текста ответа

Использование библиотеки проверки подлинности Майкрософт (MSAL)

В этой статье описаны сведения о низкоуровневом протоколе, которые требуются только при создании и выдаче необработанных HTTP-запросов для выполнения потока кода авторизации. В рабочих приложениях используйте встроенную или поддерживаемую корпорацией Майкрософт библиотеку проверки подлинности, например библиотеку проверки подлинности Майкрософт (MSAL), чтобы получать маркеры безопасности и вызывать защищенные веб-API, такие как Microsoft Graph.

MSAL и другие поддерживаемые библиотеки проверки подлинности упрощают процесс, обрабатывая такие сведения, как проверка, обработка файлов cookie, кэширование маркеров и безопасные подключения, что позволяет сосредоточиться на функциональных возможностях приложения.

Корпорация Майкрософт создала и поддерживает широкий выбор примеров кода, демонстрирующих использование поддерживаемых библиотек проверки подлинности с платформа удостоверений Майкрософт. Чтобы получить доступ к этим примерам кода, см. платформа удостоверений Майкрософт примеры кода.

Связанные материалы

• Вы можете вызывать Microsoft Graph от имени пользователя из различных типов приложений, таких как одностраничные, веб-приложения и мобильные приложения. Дополнительные сведения см. в разделе Сценарии и поддерживаемые потоки проверки подлинности.
• Выберите один из примеров кода, которые создаются и обслуживаются корпорацией Майкрософт для запуска пользовательских приложений, использующих поддерживаемые библиотеки проверки подлинности, пользователей для входа и вызова Microsoft Graph. Ознакомьтесь с руководствами по Microsoft Graph.