代表用户获取访问权限
若要使用 Microsoft Graph 代表用户读取和写入资源，你的应用必须从Microsoft 标识平台获取访问令牌，并将令牌附加到它发送到 Microsoft Graph 的请求。 用于获取访问令牌的确切身份验证流将取决于正在开发的应用类型以及是否要使用 OpenID Connect 将用户登录到应用。 本机和移动应用以及某些 Web 应用使用的一个常见流是 OAuth 2.0 授权代码授予流。 本文逐步讲解使用此流的示例。
身份验证和授权步骤
需要执行下述基本步骤来使用 OAuth 2.0 授权代码授予流从 Microsoft 标识平台终结点获取访问令牌：
- 使用 Azure AD 注册应用。
- 获取授权。
- 获取访问令牌。
- 使用访问令牌调用 Microsoft Graph。
- 使用刷新令牌获取新的访问令牌。
1.注册你的应用程序
若要使用 Microsoft 标识平台 终结点，必须使用 Azure 应用注册门户注册应用。 可以使用 Microsoft 帐户或工作或学校帐户来注册应用。
若要配置应用以使用 OAuth 2.0 授权代码授予流程，请在注册应用时保存下列值：
- 应用注册门户分配的应用程序（客户端）ID。
- 客户端（应用程序）密码，它是一个密码或是一个公钥/私钥对（证书）。 本机应用不需要客户端密码。
- 可让应用接收来自 Azure AD 的响应的重定向 URL（或回复 URL）。
要分步了解如何在 Azure 门户中配置应用，请参阅注册应用。
2. 获取授权
为许多 OpenID Connect (OIDC) 和 OAuth 2.0 流获取访问令牌的第一步是将用户重定向到Microsoft 标识平台/authorize终结点。 Azure AD 会将用户登录并请求其同意应用请求的权限。 在授权代码授予流中，获得同意后，Azure AD 将向你的应用返回一个授权代码，它可在 Microsoft 标识平台 /token 终结点处兑换访问令牌。
授权请求
以下示例显示了对 /authorize 终结点的请求示例。
借助 Microsoft 标识平台终结点，通过 scope 参数请求权限。 在此示例中，请求的 Microsoft Graph 权限为 User.Read 和 Mail.Read，这将允许应用读取已登录用户的配置文件和邮件。 offline_access权限是请求的标准 OIDC 范围，以便应用可以获取刷新令牌。 当当前令牌过期时，应用可以使用刷新令牌来获取新的访问令牌。
// Line breaks for legibility only
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
| 参数 | 必需 | 说明 |
|---|---|---|
| 租户 | 必需 | 请求路径中的 {tenant} 值可用于控制登录应用程序的用户。 允许的值适用于 common Microsoft 帐户和工作或学校帐户， organizations 仅适用于工作或学校帐户， consumers 仅适用于 Microsoft 帐户，以及租户标识符（例如租户 ID 或域名）。 有关详细信息，请参阅协议基础。 |
| client_id | 必需 | 注册门户分配给应用的应用程序 ID。 |
| response_type | 必需 | 必须包括授权代码流的 code。 |
| redirect_uri | 建议 | 应用的redirect_uri，应用可在其中发送和接收身份验证响应。 它必须与在应用注册门户中注册的redirect_uris之一完全匹配，除非它必须经过 URL 编码。 对于本机应用和移动应用，应使用默认值 https://login.microsoftonline.com/common/oauth2/nativeclient。 |
| 范围 | 必需 | 由空格分隔的希望用户同意的 Microsoft Graph 权限列表。 不要对空格进行百分比编码。 这些权限可能包括资源权限，如 User.Read、Mail.Read 和 OIDC 作用域（如 offline_access），这表示你的应用需要刷新令牌才能长期访问资源。 |
| response_mode | 建议 | 指定用于将生成的令牌发送回应用的方法。 可以是 query 或 form_post。 |
| 状态 | 建议 | 请求中包含的一个值，该值也将在令牌响应中返回。 它可以是所需的任何内容的字符串。 随机生成的唯一值通常用于 防止跨站点请求伪造攻击。 状态还用于在身份验证请求发生前对应用中有关用户状态的信息进行编码，例如用户所访问的页面或视图。 |
注意
Microsoft Graph 公开两种类型的权限：应用程序和委派权限。 对于使用已登录用户运行的应用，可以在 参数中 scope 请求委派权限。 这些权限将已登录用户的权限委托给你的应用，允许它在调用 Microsoft Graph 时充当已登录用户。 有关通过 Microsoft Graph 提供的权限的更多详细信息，请参阅 权限参考。
Microsoft Graph 还会公开以下定义明确的 OIDC 作用域： openid、 email、 profile和 offline_access。 不支持address和phone OIDC 作用域。 有关每个 OIDC 作用域的更多信息，请参阅许可和同意。
同意体验
发送授权请求后，系统会要求用户输入其凭据以向 Microsoft 进行身份验证。 Microsoft 标识平台 v2.0 终结点还将确保用户已同意 scope 查询参数中指示的权限。 如果用户未同意其中任何权限，并且管理员之前未代表组织中的所有用户同意，则会要求他们同意所需的权限。 有关 Azure AD 同意体验的详细信息，请参阅 应用程序同意体验。
下面是为 Microsoft 帐户用户呈现的同意对话框屏幕截图。
尝试 如果你有 Microsoft 帐户或 Azure AD 工作或学校帐户，可以通过单击以下链接自行尝试。 登录后，浏览器应重定向到
https://localhost/myapp/地址栏中的 。codehttps://login.microsoftonline.com/common/oauth2/v2.0/authorize...
授权响应
如果用户同意应用请求的权限，则响应将在 参数中包含 code 授权代码。 下面是对上一个请求的成功响应的示例。 response_mode由于请求中的 参数设置为 query，因此响应在重定向 URL 的查询字符串中返回。
GET https://localhost/myapp/?
code=M0ab92efe-b6fd-df08-87dc-2c6500a7f84d
&state=12345
| 参数 | 说明 |
|---|---|
| code | 应用请求的authorization_code。 应用可以使用授权代码请求目标资源的访问令牌。 Authorization_codes生存期较短，通常在大约 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=jXoM3iz... // NOTE: Only required for web apps
| 参数 | 必需 | 说明 |
|---|---|---|
| 租户 | 必需 | 请求路径中的 {tenant} 值可用于控制登录应用程序的用户。 允许的值是：commonorganizationsconsumers有关详细信息，请参阅协议基础。 |
| client_id | 必需 | 注册门户分配给应用的应用程序 ID。 |
| grant_type | 必需 | 对于授权代码流必须为 authorization_code。 |
| 范围 | 必需 | 以空格分隔的范围列表。 不要对空格进行百分比编码。 你的应用在此回合中请求的范围必须等效或它在第一个 (授权) 请求的范围子集。 如果此请求中指定的范围跨越多个资源服务器，则 v2.0 终结点将返回第一个范围中指定的资源的令牌。 |
| code | 必需 | 你在流程的第一个图例中获得的 authorization_code。 |
| redirect_uri | 必需 | 用于获取 authorization_code 的相同的 redirect_uri 值。 |
| client_secret | Web 应用需要 | 在应用注册门户中为应用创建的客户端密码。 它不应在本机应用中使用，因为client_secrets无法可靠地存储在设备上。 Web 应用和 Web API 需要它，它们能够安全地将client_secret存储在服务器端。 |
令牌响应
尽管访问令牌对应用是不透明的，但是响应包含了权限列表，访问令牌对 scope 参数中的这些权限有益。
{
"token_type": "Bearer",
"scope": "user.read%20Fmail.read",
"expires_in": 3600,
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...",
"refresh_token": "AwABAAAAvPM1KaPlrEqdFSBzjqfTGAMxZGUTdM0t4B4..."
}
| 参数 | 说明 |
|---|---|
| token_type | 指示令牌类型值。 Azure AD 支持的唯一类型是 Bearer。 |
| 范围 | 此 access_token 适用的空格分隔的 Microsoft Graph 权限列表。 |
| expires_in | 访问令牌的有效期是多久（以秒为单位）。 |
| access_token | 请求的访问令牌。 你的应用可以使用此令牌来调用 Microsoft Graph。 |
| refresh_token | OAuth 2.0 刷新令牌。 在当前访问令牌到期后，应用程序可以使用此令牌获取其他访问令牌。 刷新令牌有效期较长，可用于长时间保留对资源的访问权限。 仅当 offline_access 作为参数包含 scope 时，才会返回刷新令牌。 有关详细信息，请参阅 v2.0 令牌参考。 |
4. 使用访问令牌调用 Microsoft Graph
拥有访问令牌后，可以通过将访问令牌包含在请求标头中 Authorization 来使用它来调用 Microsoft Graph。 以下请求获取已登录用户的配置文件。
GET https://graph.microsoft.com/v1.0/me
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",
"id":"12345678-73a6-4952-a53a-e9916737ff7f",
"businessPhones":[
"+1 555555555"
],
"displayName":"Chris Green",
"givenName":"Chris",
"jobTitle":"Software Engineer",
"mail":null,
"mobilePhone":"+1 5555555555",
"officeLocation":"Seattle Office",
"preferredLanguage":null,
"surname":"Green",
"userPrincipalName":"ChrisG@contoso.onmicrosoft.com"
}
5.使用此刷新令牌获取新的访问令牌。
访问令牌生存期较短，必须在令牌过期后对其进行刷新才能继续访问资源。 为此，可以向终结点提交另一个 POST 请求 /token ，这次提供 refresh_token 而不是 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
| 参数 | 必需 | 说明 |
|---|---|---|
| client_id | 必需 | 注册门户分配给应用的应用程序 ID。 |
| grant_type | 必需 | 必须是 refresh_token。 |
| 范围 | 可选 | 以空格分隔的权限列表 (范围) 。 不要对空格进行百分比编码。 应用请求的权限必须等效于原始authorization_code请求中请求的权限的子集。 |
| refresh_token | 必需 | 令牌请求期间获得的 refresh_token。 |
| client_secret | Web 应用需要 | 在应用注册门户中为应用创建的客户端密码。 请勿在本机应用中使用该机密，因为client_secrets无法可靠地存储在设备上。 Web 应用和 Web API 需要它，它们能够安全地将client_secret存储在服务器端。 |
响应
成功的令牌响将与下列内容类似。
{
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...",
"token_type": "Bearer",
"expires_in": 3599,
"scope": "user.read%20mail.read",
"refresh_token": "AwABAAAAvPM1KaPlrEqdFSBzjqfTGAMxZGUTdM0t4B4...",
}
| 参数 | 说明 |
|---|---|
| access_token | 请求的访问令牌。 应用可以在调用 Microsoft Graph 时使用此令牌。 |
| token_type | 指示令牌类型值。 Azure AD 支持的唯一类型是 Bearer |
| expires_in | 访问令牌的有效期是多久（以秒为单位）。 |
| 范围 | access_token 适用的权限（范围）。 |
| refresh_token | 新的 OAuth 2.0 刷新令牌。 将旧的刷新令牌替换为此新获取的刷新令牌，以确保刷新令牌在尽可能长的时间内保持有效。 |
受支持的应用场景和其他资源
你可以代表用户从以下类型的应用中调用 Microsoft Graph:
- 本机/移动应用
- Web 应用
- 单页应用 (SPA)
- 后端 Web API：例如，在本机应用等客户端应用在 Web API 后端实现功能的情况下。 使用 Microsoft 标识平台 终结点时，客户端应用和后端 Web API 必须具有相同的应用程序 ID。
要详细了解 Microsoft 标识平台终结点支持的应用方案，请参阅应用方案和身份验证流程。
请注意：Microsoft 标识平台终结点当前不支持通过独立的 Web API 调用 Microsoft Graph。 在此情况下，需要使用 Azure AD 终结点。
若要详细了解如何代表用户从 Microsoft标识平台终结点获取访问 Microsoft Graph 的权限：
- 有关指向不同类型应用的协议文档和入门文章的链接，请参阅 Microsoft 标识平台终结点文档。
- 要详细了解受支持的应用程序类型和身份验证流程，请参阅 v2.0 应用类型。
- 要详细了解为 Microsoft 标识平台推荐的身份验证库及服务器中间件，请参阅 Azure Active Directory v2.0 身份验证库。
终结点注意事项
Microsoft 继续支持 Azure AD 终结点。 在使用 Microsoft 标识平台终结点和使用 Azure AD 终结点之间存在诸多区别。 使用 Azure AD 终结点时：
- 应用将需要为每个平台提供不同的应用程序 ID（客户端 ID）。
- 如果应用为多租户应用，则必须在 Azure 门户中通过显式方式将其配置为多租户。
- 应用必需的所有权限都必须由开发人员进行配置。 Azure AD 终结点不支持动态 (增量) 同意。
- Azure AD 终结点在
resource授权和令牌请求中使用参数来指定需要其权限的资源，例如 Microsoft Graph。 终结点不支持scope参数。
有关代表用户获取对 Microsoft Graph 访问的详细信息，请参阅以下资源。
- 要了解如何将 Microsoft 标识平台与不同类型的应用结合使用，请参阅 Microsoft 标识平台文档中的开始使用链接。
- 要了解可与 Microsoft 标识平台终结点结合使用的 Microsoft 身份验证库 (MSAL) 和服务器中间件，请参阅 Microsoft 身份验证库。
另请参阅
- 了解如何创建代表用户调用 Microsoft Graph 的 Web 应用。
- 有关使用 Microsoft 标识平台保护不同应用程序类型的示例，请查看 Microsoft 标识平台代码示例（v2.0 终结点）。
- MSAL.js 交互式请求中的提示行为