使用 Azure Active Directory 登录 - OneDrive API - OneDrive dev center

项目
04/08/2023

使用 Microsoft Graph

本主题介绍了如何使用适用于 OneDrive 个人版的 Microsoft 帐户授权应用。不过，已不再推荐使用这种方法。应使用 Microsoft Graph 开发新应用，并遵循 Microsoft Graph 中的 OneDrive 授权和登录中的授权流程。

使用 Azure Active Directory 进行身份验证

若要对 OneDrive for Business 使用 OneDrive API，需要拥有访问令牌，以便验证应用是否拥有一组特定的用户权限。

将应用配置为有权访问 OneDrive for Business 极具挑战性。我们正在努力简化此流程，请耐心等待。

此部分将介绍如何：

使用 Azure Active Directory 应用注册。
登录 OneDrive for Business

OneDrive API 使用标准 OAuth 2.0 身份验证方案对用户进行身份验证，并生成访问令牌。对于每个 API 调用，访问令牌通过 HTTP 头提供：

Authorization: bearer {token}

通过向特定终结点 URL 发送 HTTP 请求来访问 API。根 URL 是以用作 REST 终结点的服务器的主机名为依据。可以使用发现 API 查找 Office 365 服务的终结点。有关详细信息，请参阅使用发现服务 API 的常见终结点发现任务。根 URL 出现在下一示例中，其中 {tenant} 来自发现的终结点 URL：

https://{tenant}-my.sharepoint.com/_api/v2.0/

向 Azure Active Directory 注册应用

必须先向 Azure Active Directory 注册应用，并设置应用所需的权限，然后才能登录。有关详细信息，请参阅注册 SharePoint Server 2016 或 OneDrive for Business 相关应用。

登录 OneDrive for Business

首次登录 OneDrive for Business 时，应用需要以下值：

向 Azure Active Directory (AAD) 注册的客户端 ID 和密钥（客户端密码）
从 OAuth 2 授权代码流收到的授权代码
OneDrive for Business API 终结点 URL
OneDrive for Business 资源的访问令牌
在当前令牌到期时生成其他访问令牌的刷新令牌。

下面将逐步介绍如何请求获取所有这些值。

登录流程遵循标准 OAuth 2.0 身份验证流，并要求从 Web 浏览器或 Web 浏览器控件进行调用。有关 Office 365 身份验证的常规信息，请参阅了解 Office 365 应用身份验证概念。不过，获取使用 OneDrive for Business API 所需的全部值还需要执行其他几步操作。

身份验证代码流流程包含三步，通过单独运行调用来验证和授权应用，并生成使用 OneDrive API 所需的访问令牌。此流程还会创建刷新令牌，并将其发送给应用。使用刷新令牌，可以在用户未使用应用的情况下长期使用 API。

授权代码流关系图

Azure Active Directory 生成的每个访问令牌仅适用于单个资源。若要发现并调用 OneDrive for Business API 终结点，必须有两个访问令牌，每个 API 终结点（资源）一个。

使用一个刷新令牌，即可为应用已被授权访问的所有终结点生成访问令牌。

第 1 步：登录并获取授权代码

首先，应用会在 Web 浏览器中加载常见的 Azure Active Directory OAuth 2 终结点，以提示用户使用自己的凭据进行登录。此 URL 使用常见租户终结点，对任何应用都有效。

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

必需的查询字符串参数

参数名	值	说明
client_id	string	为应用创建的客户端 ID。
response_type	string	Specifies the requested response type. In an authorization code grant request, the value must be code.
redirect_uri	string	身份验证完成时浏览器重定向到的 URL。

注意：重定向 URI 必须与在 Azure 管理门户中指定的一个重定向 URI 一致。

响应

成功验证用户和授权应用后，Web 浏览器会重定向到添加了其他参数的重定向 URL，如下一示例所示。

https://myapp.contoso.com/myapp/callback?code=AwABAAAAvPM...

code 查询字符串值是下一步所需的授权代码。

第 2 步：兑换授权代码以获取令牌

收到 code 值后，可以兑换此代码以获取一组令牌，从而进行各种 Office 365 API 身份验证。若要兑换代码，请向 Azure Active Directory 令牌终结点发出请求，如以下示例所示：

POST https://login.microsoftonline.com/common/oauth2/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&resource={resource_id}

此请求的正文是经过 URL 编码的字符串，其中包含以下必需参数：

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

在大多数情况下，OneDrive for Business API 终结点 URL 都不是已知的。若要发现终结点 URL，必须调用 Office 365 发现 API。若要进行发现 API 身份验证，必须请求获取资源 https://api.office.com/discovery/ 的访问令牌。请务必添加尾随的 / 字符，否则应用对发现 API 的访问将遭拒。

响应

如果调用成功，响应正文中的 JSON 字符串将包含 access_token、expires_in 和 refresh_token 属性。

{
  "expires_in": 3600,
  "access_token":"EwCo...AA==",
  "refresh_token":"eyJh...9323"
}

注意：响应中可能还包含其他属性。这些都不是使用 API 的必需属性。

重要说明：请安全处理此响应中的 access_token 和 refresh_token 值，就像处理用户密码一样。

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

第 3 步：发现 OneDrive for Business 资源 URI

由于不同的用户和租户使用不同的 URL 来提供 API 访问权限，因此应用需要发现登录用户的 OneDrive for Business 资源 URL。为此，应用可以使用 Office 365 发现 API，请求获取应用和登录用户可以使用的服务和 API 终结点列表。

使用收到的适用于资源 https://api.office.com/discovery/ 的访问令牌，可以向发现 API 发出请求，以了解哪些服务可用：

GET https://api.office.com/discovery/v2.0/me/services
Authorization: Bearer {access_token}

参数名称	值	说明
access_token	string	资源 `https://api.office.com/discovery/` 的有效访问令牌

响应

如果调用成功，响应正文中的 JSON 数据将包含用户和应用可以使用的服务的相关信息。可以分析此响应，以便查找 OneDrive for Business API 终结点 URL。

{
  "@odata.context": "https:\/\/api.office.com\/discovery\/v1.0\/me\/$metadata#allServices",
  "value": [
    {
      "@odata.type": "#Microsoft.DiscoveryServices.ServiceInfo",
      "capability": "MyFiles",
      "serviceApiVersion": "v2.0",
      "serviceEndpointUri": "https:\/\/contoso-my.sharepoint.com\/_api\/v2.0",
      "serviceResourceId": "https:\/\/contoso-my.sharepoint.com\/"
    }
  ]
}

注意：其他属性将针对 ServiceInfo 对象返回。此示例被截短为密钥属性。

若要查找用户的 OneDrive for Business 终结点 URL，建议在 value 集合中查找与以下谓词匹配的 ServiceInfo 对象：

capability = "MyFiles" AND serviceApiVersion = "v2.0"

在应用针对用户的 OneDrive for Business 找到匹配的 ServiceInfo 对象时，需要存储此对象的以下两个属性的值：serviceResourceId 和 serviceEndpointUri。下一步将使用这些值，以提供新的访问令牌，并调用 OneDrive API。

第 4 步：兑换刷新令牌以获取调用 OneDrive API 所需的访问令牌

至此，应用已了解用户 OneDrive for Business 的资源和终结点 URL，可以兑换在第 2 步收到的刷新令牌，以获取可用于 OneDrive API 的访问令牌了。

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

POST https://login.microsoftonline.com/common/oauth2/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&resource={resource_id}

请求正文是经过 URL 编码的字符串，其中包含以下参数：

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

注意重定向 URI 必须与在 Azure 管理门户中指定的重定向 URI 匹配。

响应

如果调用成功，响应正文中的 JSON 字符串将包含 access_token、expires_in 和 refresh_token。

{
  "expires_in": 3600,
  "access_token":"EwCo...AA==",
  "refresh_token":"eyJh...9323"
}

注意：请将之前存储的刷新令牌值替换成后续调用令牌服务返回的值，以确保应用的刷新令牌到期日期为最新。

现在，可以使用 access_token 属性的值向 OneDrive API 发出已验证的请求。有关刷新令牌的详细信息，请参阅多个资源的刷新令牌。

重要说明：请安全处理此响应中的 access_token 和 refresh_token 值，就像处理用户密码一样。

访问令牌仅在 expires_in 属性中指定的秒数（通常为 1 小时）内有效。可以使用刷新令牌（若有）或从头开始重复执行身份验证请求流，请求获取新的访问令牌。

如果访问令牌到期，向 API 发出请求将会返回 401 Unauthorized 响应。如果是在发出已验证的请求后收到此响应，应使用存储的刷新令牌生成新的访问令牌。

第 5 步：向 OneDrive API 发出请求

现在，你的应用具有对用户的 OneDrive for Business API 终结点有效的访问令牌，它可以向 OneDrive API 发出经过身份验证的请求。
必须使用通过发现 API 检索到的 serviceEndpointUri 值和从令牌服务收到的访问令牌，才能发出请求。

例如，若要获取用户 OneDrive for Business 的详细信息，可以向 /drive API 路径发出请求：

GET {serviceEndPointUri}/drive
Authorization: Bearer {access_token}

错误

如果身份验证出错，Web 浏览器会重定向到报错网页。虽然报错网页始终都会显示最终用户易懂消息，但也可以参考报错网页 URL 包含的其他信息，此类信息有助于调试所遇到的错误。这种信息并非总是显示在浏览器内的报错网页内容中。

URL 中包含查询参数，可用来分析错误并采取相应的措施。这些参数（# 字符后）始终可以添加为书签。报错网页内容始终都会显示用户易懂的一般错误消息。

如果用户选择不许可应用，流会重定向到 redirect_uri，URL 中也包含相同的错误参数。

若要详细了解如何处理错误，请参阅 OAuth 2.0 中的错误处理。

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

OneDrive for Business 身份验证和登录

使用 Microsoft Graph

使用 Azure Active Directory 进行身份验证

向 Azure Active Directory 注册应用

登录 OneDrive for Business

第 1 步： 登录并获取授权代码

必需的查询字符串参数

响应

第 2 步： 兑换授权代码以获取令牌

响应

第 3 步： 发现 OneDrive for Business 资源 URI

响应

第 4 步： 兑换刷新令牌以获取调用 OneDrive API 所需的访问令牌

响应

第 5 步： 向 OneDrive API 发出请求

错误

相关主题

其他资源

第 1 步：登录并获取授权代码

第 2 步：兑换授权代码以获取令牌

第 3 步：发现 OneDrive for Business 资源 URI

第 4 步：兑换刷新令牌以获取调用 OneDrive API 所需的访问令牌

第 5 步：向 OneDrive API 发出请求