Microsoft Graph 中的 OneDrive 授权和登录

若要通过 Microsoft Graph 使用 OneDrive API,需要拥有访问令牌,以便向应用授予一组特定的用户权限。 此部分将介绍如何:

  1. 注册应用以获取应用 ID。
  2. 使用令牌流或代码流通过指定的作用域让用户登录。
  3. 注销用户(可选)。

OneDrive API 使用标准 OAuth 2.0 授权框架对应用进行授权,并生成访问令牌。 必须使用 HTTP 头为每个已验证的 API 调用提供访问令牌:

Authorization: bearer {token}

注意: 建议使用 Azure AD v2.0 终结点作为授权框架。 不过,一些企业方案可能要求使用原始 Azure AD 终结点。 有关详细信息,请参阅 Microsoft Graph 的应用身份验证

注册应用

第一步是向 Microsoft 注册应用,并提供应用的一些详细信息。可以通过 Azure 应用注册页面注册应用并获取新的应用 ID。

若要详细了解如何注册应用,请参阅注册应用以使用 OneDrive API

让用户登录

应用必须通过指定的作用域与 Azure Active Directory 授权终结点进行通信,从而启动登录流程。 登录流程遵循标准 OAuth 2.0 授权流,并要求从 Web 浏览器或 Web 浏览器控件进行调用。 授权流结果中会返回访问令牌,并视需要返回应用可用于访问此 API 的其他令牌。

身份验证作用域

作用域决定了在用户登录时应用获得的访问权限类型。 所有作用域都支持网站单一登录。也就是说,如果用户已登录 OneDrive,可以跳过身份验证流,直接转到授权流。

作用域名称 说明
offline_access 允许应用脱机运行,即使用户处于非活动状态,也不例外。 需要使用代码流。
files.read 授予对用户的所有 OneDrive 文件的只读权限。
files.read.all 授予对用户的所有 OneDrive 文件(包括与用户共享的文件)的只读权限。
files.readwrite 授予对用户的所有 OneDrive 文件的读取和写入权限。
files.readwrite.all 授予对用户的所有 OneDrive 文件(包括与用户共享的文件)的读取和写入权限。

例如,典型应用可能会请求获取以下作用域:

files.readwrite offline_access

支持的身份验证流

尽管 Azure Active Directory 支持多个授权流,但下面列出的两个最为常见:

令牌流

最简单的授权流是令牌流。 此流可用于快速获取访问令牌,以交互方式使用 OneDrive API。 因为此流不提供刷新令牌,所以不适用于长期访问资源。

令牌流关系图

若要使用令牌流启动登录流程,请使用 Web 浏览器或 Web 浏览器控件加载 URL 请求。

GET https://login.microsoftonline.com/common/oauth2/v2.0/authorize?client_id={client_id}&scope={scope}
    &response_type=token&redirect_uri={redirect_uri}

必需的查询字符串参数

参数名 说明
client_id string 为应用创建的客户端 ID 值。
redirect_uri string 身份验证完成时浏览器重定向到的 URL。
response_type string 授权流应生成的响应类型。 对于授权流,此值必须为 token
scope string 应用所需的作用域列表(用空格分隔)。

响应

成功验证和授权应用后,Web 浏览器会重定向到添加了其他参数的重定向 URL。

https://myapp.com/auth-redirect#access_token=EwC...EB
  &authentication_token=eyJ...3EM&token_type=bearer&expires_in=3600
  &scope=onedrive.readwrite&user_id=3626...1d

在上的示例中,access_tokenauthentication_tokenuser_id 的值已被截断。 access_tokenauthentication_token 的值相当长。

可以使用 access_token 的值向 Microsoft Graph 发出请求。

代码流

身份验证代码流流程包含三步,通过单独运行调用来验证和授权应用,并生成使用 OneDrive API 所需的访问令牌。 这样,应用还会收到刷新令牌,以便可以在某些情况下长期使用 API,允许未使用应用的用户进行访问。

授权代码流关系图

步骤 1。获取授权代码

若要使用代码流启动登录流程,请使用 Web 浏览器或 Web 浏览器控件加载此 URL 请求。

GET https://login.microsoftonline.com/common/oauth2/v2.0/authorize?client_id={client_id}&scope={scope}
  &response_type=code&redirect_uri={redirect_uri}

必需的查询字符串参数

参数名 说明
client_id string 为应用创建的客户端 ID。
scope string 应用所需的作用域列表(用空格分隔)。
redirect_uri string 身份验证完成时浏览器重定向到的 URL。
response_type string 授权流应生成的响应类型。 对于授权流,此值必须为 code

响应

成功验证和授权应用后,Web 浏览器会重定向到添加了其他参数的重定向 URL。

https://myapp.com/auth-redirect?code=df6aa589-1080-b241-b410-c4dff65dbf7c

第 2 步: 兑换代码以获取访问令牌

收到 code 值后,可以兑换此代码以获取一组令牌,从而进行 OneDrive API 身份验证。 若要兑换代码,请发出以下请求:

POST https://login.microsoftonline.com/common/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded

client_id={client_id}&redirect_uri={redirect_uri}&client_secret={client_secret}
&code={code}&grant_type=authorization_code

必需的请求正文参数

请求正文是经过正确编码的 URL 字符串,其中包含一些必需参数。

参数名称 说明
client_id string 为应用创建的客户端 ID 值。
redirect_uri string 身份验证完成时浏览器重定向到的 URL。这应与第一个请求中的 redirect_uri 一致。
client_secret string 为应用创建的客户端密码。
code string 在第一个身份验证请求中收到的授权代码。

注意:对于 Web 应用,重定向 URI 的域部分必须与在 Microsoft 开发者中心内指定的重定向 URI 的域部分一致。

响应

如果调用成功,POST 请求响应中的 JSON 字符串将包含多个属性,包括 access_tokentoken_typerefresh_token(如果请求获取 wl.offline_access 作用域的话)。

{
  "token_type":"bearer",
  "expires_in": 3600,
  "scope":"wl.basic onedrive.readwrite",
  "access_token":"EwCo...AA==",
  "refresh_token":"eyJh...9323"
}

现在,可以存储并使用所提供的 access_token 向 Microsoft Graph 发出已验证的请求。

重要说明: 请安全处理此响应中的 access_tokenrefresh_token 值,就像处理用户密码一样。

访问令牌仅在 expires_in 属性中指定的秒数内有效。 可以使用刷新令牌(若有)或从头开始重复执行身份验证请求流,请求获取新的访问令牌。

步骤 3。获取新的访问令牌或刷新令牌

如果应用已请求获取 offline_access 作用域,这一步将返回 refresh_token,可用于在初始令牌到期后生成其他访问令牌。

若要兑换刷新令牌以获取新的访问令牌,请发出以下请求:

POST https://login.microsoftonline.com/common/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded

client_id={client_id}&redirect_uri={redirect_uri}&client_secret={client_secret}
&refresh_token={refresh_token}&grant_type=refresh_token

必需的请求正文参数

请求正文是经过正确编码的 URL 字符串,其中包含一些必需参数。

参数名称 说明
client_id string 为应用程序创建的客户端 ID。
redirect_uri string 身份验证完成时浏览器发送到的重定向 URL。这应与第一个请求中使用的 redirect_uri 值匹配。
client_secret string 为应用创建的客户端密码。
refresh_token string 之前收到的刷新令牌。

注意:对于 Web 应用,重定向 URI 的域部分必须与在 Microsoft 开发者中心内指定的重定向 URI 的域部分一致。

响应

如果调用成功,POST 请求响应中的 JSON 字符串将包含多个属性,包括 access_tokenauthentication_tokenrefresh_token(如果请求获取 offline_access 作用域的话)。

{
  "token_type":"bearer",
  "expires_in": 3600,
  "scope": "wl.basic onedrive.readwrite wl.offline_access",
  "access_token":"EwCo...AA==",
  "refresh_token":"eyJh...9323"
}

现在,可以存储并使用 access_token 向 Microsoft Graph 发出已验证的请求。

重要说明: 请安全处理此响应中的 access_tokenrefresh_token 值,就像处理用户密码一样。

访问令牌仅在 expires_in 属性中指定的秒数内有效。 可以使用刷新令牌(若有)或从头开始重复执行身份验证请求流,请求获取新的访问令牌。

注销用户

若要注销用户,请按照下列步骤操作:

  1. 删除之前从 OAuth 流收到的任何已缓存 access_tokenrefresh_token 值。
  2. 在应用中执行任意注销操作(例如,清除本地状态、删除所有缓存项等)。
  3. 使用以下 URL 调用授权 Web 服务:
GET https://login.microsoftonline.com/common/oauth2/v2.0/logout?post_logout_redirect_uri={redirect-uri}

此调用将删除所有启用单一登录的 Cookie,并确保在应用下一次启动授权流时,用户必须重新登录。 使用此注销流不会撤消之前授予应用的任何内容。

必需的查询字符串参数

参数名 说明
redirect_uri string 身份验证完成时浏览器重定向到的 URL。这必须与获取令牌请求中使用的 redirect_uri 值完全一致。

删除 Cookie 后,浏览器将重定向到所提供的重定向 URL。 当浏览器加载重定向页时,不会设置任何身份验证查询字符串参数,可以推断用户已注销。

撤消访问权限

Microsoft 帐户用户可以访问 Microsoft 帐户管理许可页,撤消应用对自己帐户的访问权限。

撤消应用许可后,之前向应用提供的所有刷新令牌都会失效。 需要重复执行身份验证流,从头开始请求获取新的访问令牌和刷新令牌。

下列主题简要概述了 OneDrive API 的其他概念。