[Microsoft Graph] 代表用户获取访问权限

To call Microsoft Graph, an app must obtain an access token from the Microsoft identity platform. This access token includes information about whether the app is authorized to access Microsoft Graph on behalf of a signed-in user or with its own identity. This article provides guidance on how an app can access Microsoft Graph on behalf of a user, also called delegated access.

This article details the raw HTTP requests involved for an app to get access on behalf of a user using a popular flow called the OAuth 2.0 authorization code grant flow. Alternatively, you can avoid writing raw HTTP requests and use a Microsoft-built or supported authentication library that handles many of these details for you and helps you to get access tokens and call Microsoft Graph. For more information, see Use the Microsoft Authentication Library (MSAL).

Before proceeding with the steps in this article:

1. Understand the authentication and authorization concepts in the Microsoft identity platform. For more information, see Authentication and authorization basics.
2. Register the app with Microsoft Entra ID. For more information, see Register an application with the Microsoft identity platform.

For an app to get authorization and access to Microsoft Graph using the authorization code flow, you must follow these five steps:

1. Register the app with Microsoft Entra ID.
2. Request authorization.
3. Request an access token.
4. Use the access token to call Microsoft Graph.
5. [Optional] Use the refresh token to renew an expired access token.

Before the app can call the Microsoft identity platform endpoints or Microsoft Graph, it must be properly registered. Follow the steps to register your app on the Microsoft Entra admin center.

From the app registration, save the following values:

• The application ID (referred to as Object ID on the Microsoft Entra admin center) assigned by the app registration portal.
• A redirect URI (or reply URL) for the app to receive responses from Microsoft Entra ID.
• A client secret (application password), a certificate, or a federated identity credential. This property isn't needed for public clients like native, mobile and single page applications.

The first step in the authorization code flow is for the user to authorize the app to act on their behalf.

In the flow, the app redirects the user to the Microsoft identity platform /authorize endpoint. Through this endpoint, Microsoft Entra ID signs the user in and requests their consent for the permissions that the app requests. After consent is obtained, Microsoft Entra ID will return an authorization code to the app. The app can then redeem this code at the Microsoft identity platform /token endpoint for an access token.

The following example shows a request to the /authorize endpoint.

In the request URL, you call the /authorize endpoint and specify the required and recommended properties as query parameters.

In the following example, the app requests the User.Read and Mail.Read Microsoft Graph permissions, which allow the app to read the profile and mail of the signed-in user respectively. The offline_access permission is a standard OIDC scope that's requested so that the app can get a refresh token. The app can use the refresh token to get a new access token when the current one expires.

// 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

After the app sends the authorization request, the user is asked to enter their credentials to authenticate with Microsoft. The Microsoft identity platform v2.0 endpoint ensures that the user has consented to the permissions indicated in the scope query parameter. If there is any permission that the user or administrator has not consented to, they're asked to consent to the required permissions. For more information about the Microsoft Entra consent experience, see Application consent experience and Introduction to permissions and consent.

The following screenshot is an example of the consent dialog box presented for a Microsoft account user.

If the user consents to the permissions the app requested, the response contains the authorization code in the code parameter. Here's an example of a successful response to the previous request. Because the response_mode parameter in the request was set to query, the response is returned in the query string of the redirect URL.

HTTP/1.1 200 OK

https://localhost/myapp/?code=M0ab92efe-b6fd-df08-87dc-2c6500a7f84d&state=12345&session_state=fe1540c3-a69a-469a-9fa3-8a2470936421#

The app uses the authorization code received in the previous step to request an access token by sending a POST request to the /token endpoint.

// 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

The access token contains a list of the permissions that the access token is good for in the scope parameter. The response is similar to the following sample.

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

After you have an access token, the app uses it to call Microsoft Graph by attaching the access token as a Bearer token to the Authorization header in an HTTP request. The following request gets the profile of the signed-in user.

GET https://graph.microsoft.com/v1.0/me  HTTP/1.1
Authorization: Bearer eyJ0eXAiO ... 0X2tnSQLEANnSPHY0gKcgw
Host: graph.microsoft.com

A successful response looks similar to the following (some response headers have been removed).

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

Access tokens are short lived, and the app must refresh them after they expire to continue accessing resources. The app does so by submitting another POST request to the /token endpoint, this time:

• Providing the refresh_token instead of the code in the request body
• Specifying refresh_token as the grant_type, instead of 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

A successful token response looks similar to the following.

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

In this article, you walked through the low-level protocol details usually required only when manually crafting and issuing raw HTTP requests to execute the authorization code flow. In production apps, use a Microsoft-built or supported authentication library, such as the Microsoft Authentication Library (MSAL), to get security tokens and call protected web APIs such as Microsoft Graph.

MSAL and other supported authentication libraries simplify the process for you by handling details such as validation, cookie handling, token caching, and secure connections, allowing you to focus on the functionality of your application.

Microsoft has built and maintains a wide selection of code samples that demonstrate usage of supported authentication libraries with the Microsoft identity platform. To access these code samples, see the Microsoft identity platform code samples.

• You can call Microsoft Graph on behalf of a user from different types of apps, such as single-page apps, web apps, and mobile apps. For more information, see Scenarios and supported authentication flows.
• Choose from code samples that are built and maintained by Microsoft to run custom apps that use supported authentication libraries, sign-in users, and call Microsoft Graph. See Microsoft Graph tutorials.