使用英语阅读

通过


身份验证和授权基础知识

Microsoft Graph 是一个受保护的 Web API,用于访问 Microsoft 云服务(如 Microsoft Entra ID 和 Microsoft 365)中的数据。 它受 Microsoft 标识平台保护,该Microsoft 标识平台使用 OAuth 访问令牌来验证应用是否有权调用 Microsoft Graph。

本文概述了 Microsoft 标识平台、访问令牌,以及应用可获取访问令牌的方式。 有关 Microsoft 标识平台的详细信息,请参阅 什么是 Microsoft 标识平台?。 如果你知道如何将应用与Microsoft 标识平台集成以获取令牌,请参阅Microsoft 标识平台代码示例,了解特定于 Microsoft Graph 的信息和示例。

注册应用程序

应用必须先在Microsoft Entra 管理中心中注册,然后应用才能从Microsoft 标识平台获取访问令牌。 注册会将应用与 Microsoft 标识平台相集成,并建立用于获取令牌的信息,其中包括:

  • 应用程序 ID:Microsoft 标识平台分配的唯一标识符。
  • 重定向 URI/URL:应用从Microsoft 标识平台接收响应的一个或多个终结点。 (对于本机应用和移动应用,URI 由 Microsoft 标识平台.)
  • 客户端密码:应用用于向Microsoft 标识平台进行身份验证的密码。 可以选择使用证书或联合标识凭据。 本机、移动和单页应用程序等公共客户端不需要此属性。

有关详细信息,请参阅使用 Microsoft 标识平台注册应用程序

访问方案

应用用于向Microsoft 标识平台进行身份验证的方法取决于你希望应用访问数据的方式。 此访问可以采用以下两种方式之一,如下图所示。

  • 委托访问,代表已登录用户的应用。
  • 仅限应用的访问权限,即使用自己的标识执行操作的应用。

Microsoft 标识平台中的委派访问方案和仅限应用访问方案的插图。

代表用户) 委派访问 (访问

在此访问方案中,用户已登录到客户端应用程序,并且客户端应用程序代表该用户调用 Microsoft Graph。 客户端和用户都必须获得发出请求的授权

委派访问需要 委派的权限,也称为 范围。 作用域是由给定资源公开的权限,它们表示应用可以代表用户执行的操作。

由于应用和用户都必须获得发出请求的授权,因此资源向客户端应用授予委托的权限,以便客户端应用代表指定用户访问数据。 对于用户来说,他们可以对资源执行的操作依赖于他们有权访问资源。 例如,用户可能是资源的所有者,或者他们可能通过基于角色的访问控制系统 (RBAC) (如 Microsoft Entra RBAC)分配特定角色。

备注

具有别名的 /me 终结点和 API 仅适用于已登录用户,因此在委派访问方案中调用。

仅应用访问 (在没有用户) 的情况下访问

在此访问方案中,应用程序可以自行与数据交互,而无需登录用户。 仅应用 访问用于自动化和备份等方案,并且主要由作为后台服务或守护程序运行的应用使用。 当不希望有用户登录,或者所需数据的范围不能限定为单个用户时,它适用。

应用通过以下方式之一获取使用自己的标识调用 Microsoft Graph 的权限:

  • 为应用分配应用程序权限(也称为应用角色)
  • 为应用分配要管理的资源的所有权时

备注

应用还可以通过基于角色的访问控制系统(如 Microsoft Entra RBAC)授予的权限获取特权。

Microsoft Graph 权限

Microsoft Graph 公开精细权限,用于控制应用对 Microsoft Graph 资源(如用户、组和邮件)的访问权限。 作为开发人员,你可以根据访问方案和要执行的操作来决定为应用请求哪些 Microsoft Graph 权限。

Microsoft Graph 为受支持的 访问方案公开了两种类型的权限:

  • 委托的权限:也称为 范围,允许应用程序代表已登录用户进行操作。
  • 应用程序权限:也称为 应用角色,允许应用在没有登录用户的情况下自行访问数据。

当用户登录到应用时,应用必须指定需要包含在访问令牌中的权限。 这些权限:

  • 可由管理员对应用程序进行预授权。
  • 可以直接由用户同意。
  • 如果未进行预授权,可能需要管理员权限才能授予同意。 例如,对于具有较大潜在安全影响的权限。

有关权限和同意的详细信息,请参阅 权限和同意简介

备注

作为最佳实践,请求你的应用所需的最低特权权限,以便访问数据并正常工作。 请求超过必要特权的权限是不良的安全行为,可能会导致用户不同意,并影响你的应用的使用。

有关 Microsoft Graph 权限及其使用方法的详细信息,请参阅 Microsoft Graph 权限概述

访问令牌

应用程序向Microsoft 标识平台发出身份验证请求,以获取用于调用 API(如 Microsoft Graph)的访问令牌。 Microsoft 标识平台颁发的访问令牌包含声明,这些声明是有关应用程序的详细信息,在委派访问方案中,是用户。 受Microsoft 标识平台保护的 Web API(如 Microsoft Graph)使用声明来验证调用方并确保调用方具有执行其请求的操作的适当权限。 调用方应将访问令牌视为不透明字符串,因为令牌的内容仅适用于 API。 调用Microsoft Graph时,始终通过使用传输层安全性 (TLS) 的安全通道传输访问令牌来保护访问令牌。

下面是一个 Microsoft 标识平台访问令牌示例:

eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6Imk2bEdrM0ZaenhSY1ViMkMzbkVRN3N5SEpsWSJ9.eyJhdWQiOiI2ZTc0MTcyYi1iZTU2LTQ4NDMtOWZmNC1lNjZhMzliYjEyZTMiLCJpc3MiOiJodHRwczovL2xvZ2luLm1pY3Jvc29mdG9ubGluZS5jb20vNzJmOTg4YmYtODZmMS00MWFmLTkxYWItMmQ3Y2QwMTFkYjQ3L3YyLjAiLCJpYXQiOjE1MzcyMzEwNDgsIm5iZiI6MTUzNzIzMTA0OCwiZXhwIjoxNTM3MjM0OTQ4LCJhaW8iOiJBWFFBaS84SUFBQUF0QWFaTG8zQ2hNaWY2S09udHRSQjdlQnE0L0RjY1F6amNKR3hQWXkvQzNqRGFOR3hYZDZ3TklJVkdSZ2hOUm53SjFsT2NBbk5aY2p2a295ckZ4Q3R0djMzMTQwUmlvT0ZKNGJDQ0dWdW9DYWcxdU9UVDIyMjIyZ0h3TFBZUS91Zjc5UVgrMEtJaWpkcm1wNjlSY3R6bVE9PSIsImF6cCI6IjZlNzQxNzJiLWJlNTYtNDg0My05ZmY0LWU2NmEzOWJiMTJlMyIsImF6cGFjciI6IjAiLCJuYW1lIjoiQWJlIExpbmNvbG4iLCJvaWQiOiI2OTAyMjJiZS1mZjFhLTRkNTYtYWJkMS03ZTRmN2QzOGU0NzQiLCJwcmVmZXJyZWRfdXNlcm5hbWUiOiJhYmVsaUBtaWNyb3NvZnQuY29tIiwicmgiOiJJIiwic2NwIjoiYWNjZXNzX2FzX3VzZXIiLCJzdWIiOiJIS1pwZmFIeVdhZGVPb3VZbGl0anJJLUtmZlRtMjIyWDVyclYzeERxZktRIiwidGlkIjoiNzJmOTg4YmYtODZmMS00MWFmLTkxYWItMmQ3Y2QwMTFkYjQ3IiwidXRpIjoiZnFpQnFYTFBqMGVRYTgyUy1JWUZBQSIsInZlciI6IjIuMCJ9.pj4N-w_3Us9DrBLfpCt

访问令牌是Microsoft 标识平台提供的一种安全令牌。 它们生存期较短,但默认生存期可变。

若要调用 Microsoft Graph,应用通过将访问令牌作为 持有者 令牌附加到 HTTP 请求中的 Authorization 标头来发出 授权 请求。 例如,下述调用会返回已登录用户的个人资料信息(已缩短访问令牌以便于阅读):

GET https://graph.microsoft.com/v1.0/me/ HTTP/1.1
Host: graph.microsoft.com
Authorization: Bearer EwAoA8l6BAAU ... 7PqHGsykYj7A0XqHCjbKKgWSkcAg==

获取访问令牌

建议使用身份验证库来管理与Microsoft 标识平台的令牌交互。 身份验证库提取了许多协议详细信息,例如验证、Cookie 处理、令牌缓存和维护安全连接,使你能够将开发重点放在应用的功能上。 Microsoft 发布开源客户端库和服务器中间件。

对于 Microsoft 标识平台终结点:

  • Microsoft 身份验证库 (MSAL) 客户端库可用于各种框架,包括 .NET、JavaScript、Android 和 iOS。 所有平台都处于生产支持的预览版中,如果引入了中断性变更,Microsoft 将保证提供升级路径。
  • Microsoft 的服务器中间件可用于 .NET core 和 ASP.NET (OWIN OpenID Connect 和 OAuth) 以及 Node.js (Microsoft 标识平台 Passport.js) 。
  • Microsoft 标识平台还与许多第三方身份验证库兼容。

有关 Microsoft 客户端库、Microsoft 服务器中间件和兼容的第三方库的完整列表,请参阅Microsoft 标识平台文档

无需使用身份验证库即可获取访问令牌。 若要了解如何在没有身份验证库帮助的情况下直接使用 Microsoft 标识平台 终结点,请参阅以下文章: