为了调用 Microsoft Graph,应用必须从 Microsoft 标识平台获取访问令牌。该访问令牌包含应用相关信息以及它对可通过 Microsoft Graph 使用的资源和 API 所具有的权限。若要获取访问令牌,应用必须向 Microsoft 标识平台注册,并且获得用户或管理员的授权,可访问其所需的 Microsoft Graph 资源。
本文概述了 Microsoft 标识平台、访问令牌,以及应用可获取访问令牌的方式。 有关 Microsoft 标识平台的详细信息,请参阅 什么是 Microsoft 标识平台?。 如果你已知道如何将应用与 Microsoft 标识平台集成来获取令牌,请参阅 后续步骤 部分中的信息和特定于 Microsoft Graph 的示例。
向 Microsoft 标识平台注册应用
必须在 Azure 门户中注册应用,然后它才能从 Microsoft 标识平台获取令牌。 注册会将应用与 Microsoft 标识平台相集成,并建立用于获取令牌的信息,其中包括:
- 应用程序 ID:Microsoft 标识平台分配的唯一标识符。
- 重定向 URI/URL:应用将从 Microsoft 标识平台接收响应的一个或多个终结点。(对于本机和移动应用,URI 由 Microsoft 标识平台分配。)
- 客户端密码:应用用于通过 Microsoft 标识平台进行身份验证的密码或公钥/私钥对。(本机或移动应用不需要。)
注册期间配置的属性在请求中使用。例如,在以下令牌请求中: client_id 是 应用程序 ID, redirect_uri 是应用的注册 重定向 URI 之一, client_secret 是 客户端密码。
// Line breaks for legibility only
POST /common/oauth2/v2.0/token HTTP/1.1
Host: https://login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded
client_id=6731de76-14a6-49ae-97bc-6eba6914391e
&scope=user.read%20mail.read
&code=OAAABAAAAiL9Kn2Z27UubvWFPbm0gLWQJVzCTE9UkP3pSx1aXxUjq3n8b2JRLk4OxVXr...
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&grant_type=authorization_code
&client_secret=JqQX2PNo9bpM0uEihUPzyrh // NOTE: Only required for web apps
Microsoft Graph 权限
Microsoft Graph公开精细的权限,这些权限控制应用对资源(如用户、组和邮件)的访问权限。作为开发人员,你决定要请求应用的Microsoft Graph权限。当用户登录到你的应用时,或者在某些情况下,管理员有机会同意这些权限。如果用户同意,则向应用授予对其请求的资源和 API 的访问权限。对于在没有登录用户的情况下访问资源和 API 的应用,安装应用时,管理员可以预先同意这些权限。
请求权限的最佳做法
Note: 作为最佳实践,请求你的应用所需的最低特权权限,以便访问数据并正常工作。 请求超过必要特权的权限是不良的安全行为,可能会导致用户不同意,并影响你的应用的使用。
委派权限和应用程序权限
Microsoft Graph 具有两种权限类型:
-
委派权限 由存在已登录用户的应用使用。对于这些应用,用户或管理员会同意应用请求的权限,且应用在调用 Microsoft Graph 时可以充当已登录用户。一些委派权限可以由非管理用户同意,但一些特权较高的权限需要 管理员同意。
-
应用程序权限 由无需具有登录用户即可运行的应用使用;例如,作为后台服务或守护程序运行的应用。应用程序权限只能 由管理员同意。
有效权限
有效权限 是应用在向 Microsoft Graph 发出请求时具有的权限。 有效权限由你向应用授予的Microsoft Graph权限的组合决定,and 已登录用户或调用应用的权限。 在组织中,一个或多个角色中的策略或成员身份决定已登录用户或应用的权限。 调用Microsoft Graph时,请务必了解应用具有的委派权限和应用程序权限与其有效权限之间的差异。
委派权限与仅限应用程序权限方案中的有效权限
-
对于委派权限,有效权限是应用已授予的委派权限(经同意)和当前登录用户的特权的最小交集。你的应用的权限永远不能超过已登录用户。
假设已向应用授予 User.ReadWrite.All 委派权限,并调用 Update 用户 API。 此权限名义上授予应用读取和更新组织中每位用户个人资料的权限。 但是,由于有效权限,以下限制适用于已登录用户的权限:
- 如果已登录的用户是全局管理员,则应用可以更新组织中每个用户的配置文件。
- 如果已登录用户不是管理员角色,则应用 只能 已登录用户的配置文件更新。 而不会更新组织中其他用户的配置文件,因为已登录用户不具有这些特权。
-
对于应用程序权限,应用有效权限是权限隐含的完整级别权限。例如,具有 User.ReadWrite.All 应用程序权限的应用可以更新组织中每个用户的配置文件。
委派权限和应用程序权限的比较
| Item | 委派权限 | 应用程序权限 |
|---|---|---|
| 应用类型方案 | Web/移动/单页应用 (SPA) | Web/守护程序 |
| 访问上下文 | 代表用户获取访问权限 | 以服务的形式获取访问权限 |
| 谁可以同意 | <li> 用户可以同意其数据 <li> 管理员可以同意所有用户 | 只有管理员才能同意 |
| 其他名称 | <li> scopes <li>OAuth2 权限 | <li> 应用角色 <li>仅应用权限 <li>直接访问权限 |
| 同意结果 | oAuth2PermissionGrants | appRoleAssignments |
有关 Microsoft Graph 委派权限和应用程序权限的完整列表,以及哪些权限需要管理员同意,请参阅 权限参考。
访问令牌
Microsoft 标识平台发布的访问令牌包含受 Microsoft 标识平台保护的 Web API (如 Microsoft Graph,用于验证调用方和确保调用方具有适当的权限来执行其请求的操作)的信息(声明)。 调用方应将访问令牌视为不透明字符串,因为令牌的内容仅适用于 API。 调用Microsoft Graph时,始终通过使用传输层安全性 (TLS) 的安全通道传输访问令牌来保护访问令牌。
下面是一个 Microsoft 标识平台访问令牌示例:
EwAoA8l6BAAU7p9QDpi/D7xJLwsTgCg3TskyTaQAAXu71AU9f4aS4rOK5xoO/SU5HZKSXtCsDe0Pj7uSc5Ug008qTI+a9M1tBeKoTs7tHzhJNSKgk7pm5e8d3oGWXX5shyOG3cKSqgfwuNDnmmPDNDivwmi9kmKqWIC9OQRf8InpYXH7NdUYNwN+jljffvNTewdZz42VPrvqoMH7hSxiG7A1h8leOv4F3Ek/XbrnbEErTDLWrV6Lc3JHQMs0bYUyTBg5dThwCiuZ1evaT6BlMMLuSCVxdBGzXTBcvGwihFzZbyNoX+52DS5x+RbIEvd6KWOpQ6Ni+1GAawHDdNUiQTQFXRxLSHfc9fh7hE4qcD7PqHGsykYj7A0XqHCjbKKgWSkcAg==
若要调用 Microsoft Graph,请将访问令牌作为持有者令牌附加到 HTTP 请求中的授权标头。例如以下调用,它返回已登录用户的个人资料信息(为了可读性,已将访问令牌缩短):
GET https://graph.microsoft.com/v1.0/me/ HTTP/1.1
Host: graph.microsoft.com
Authorization: Bearer EwAoA8l6BAAU ... 7PqHGsykYj7A0XqHCjbKKgWSkcAg==
访问令牌是 Microsoft 标识平台提供的一种 安全令牌。 它们生存期较短,但具有可变的默认生存期。 有关访问令牌以及客户端如何使用访问令牌的详细信息,请参阅 访问令牌。
获取访问令牌
与大多数开发人员一样,你可能会使用身份验证库来管理令牌与 Microsoft 标识平台的交互。身份验证库从开发人员处提取许多协议详细信息,例如验证、Cookie 处理、令牌缓存和维护安全连接,并让你专注于应用功能的开发。Microsoft 发布开源客户端库和服务器中间件。
对于 Microsoft 标识平台终结点:
- Microsoft 身份验证库 (MSAL) 客户端库适用于 .NET、JavaScript、Android 和 Objective-C。所有平台都处于生产支持的预览下,而且,一旦引入重大更改,Microsoft 会保证升级的路径。
- 来自 Microsoft 的服务器中间件可用于 .NET core 和 ASP.NET(OWIN OpenID Connect 和 OAuth),还可用于 Node.js (Microsoft 标识平台 Passport.js)。
- Microsoft 标识平台与许多第三方身份验证库兼容。
要在完整列表中查看 Microsoft 客户端库、Microsoft 服务器中间件和兼容的第三方库,请参阅 Microsoft 标识平台身份验证库。
无需使用身份验证库即可获取访问令牌。 要了解如何在不使用身份验证库的情况下直接使用 Microsoft 标识平台终结点,请查看 Microsoft 标识平台身份验证。
后续步骤
- 要开始使用身份验证并授权应用访问资源,请参阅 开始使用:选择应用程序方案。
- 若要查看你可以在 Microsoft Graph 中使用的权限,请参阅权限。
- 如果你是 Microsoft 云解决方案提供商并且对通过 Microsoft Graph 访问合作伙伴托管的客户数据感兴趣,请参阅管理应用访问 (CSPs)。
如果已准备好跳到代码,可使用下述资源,它们可帮助你在应用中向 Microsoft 标识平台进行身份验证并获取授权。
Microsoft Graph 培训和示例
为帮助你快速入门,我们创建了一系列的培训模块和其他资源来展示如何在各类平台上进行身份验证和使用 API。
- 通过使用入门页面查找你喜爱的平台所适用的库、示例、培训内容和其他资源。
- 要通过平台预配置的示例快速运行,请参阅 Microsoft Graph 快速入门。
- 请参阅 GitHub 上的 Microsoft Graph 示例。
Microsoft 标识平台示例和文档
Microsoft 标识平台文档中有一些文章和示例,它们专门介绍如何向 Microsoft 标识平台进行身份验证以及如何获得它的授权。
- 请访问Microsoft 标识平台终结点文档了解如何向 Microsoft 标识平台注册应用程序。
- 最简单的起点在 Microsoft 标识平台终结点文档 中。本文包含概述、协议文档以及不同平台入门文章的链接,这些文章全部按你正在开发的应用类型进行整理。
- 有关使用 Microsoft 标识平台保护不同应用程序类型的示例,请查看 Microsoft 标识平台代码示例(v2.0 终结点)。
- 要了解客户端或服务器身份验证库列出的示例,请参阅 Microsoft 标识平台身份验证库。
- 在 Azure 代码库中按平台查看 Microsoft 标识平台示例。
另请参阅
历史资料。此文对应 2023-02-03 的中文文档快照,适用产品版本和命令行为以原文为准。
来源与署名:Microsoft 和文档贡献者(原始作者元数据 jackson-woods)。固定版本原文。文档采用 CC BY 4.0,示例代码采用 MIT 授权。本站将 Markdown 转为 HTML,规范化链接,移除外部媒体和导航标记。
