OneDrive 身份验证和登录
使用 Microsoft Graph
本主题介绍了如何使用适用于 OneDrive 个人版的 Microsoft 帐户授权应用。 不过，已不再推荐使用这种方法。 应使用 Microsoft Graph 开发新应用，并遵循 Microsoft Graph 中的 OneDrive 授权和登录中的授权流程。
入门
若要使用 OneDrive API，需要拥有访问令牌，以便验证应用是否拥有一组特定的用户权限。 此部分将介绍如何：
- 注册应用以获取客户端 ID 和客户端密码。
- 使用令牌流或代码流通过指定的作用域让用户登录 OneDrive。
- 注销用户（可选）。
OneDrive API 使用标准 OAuth 2.0 身份验证方案对用户进行身份验证，并生成访问令牌。 必须通过以下方式之一为每个 API 调用提供访问令牌。
- HTTP 头：
Authorization: bearer {token}
注册应用
必须向 Microsoft 注册应用，并提供应用的一些详细信息，才能验证应用。
注册应用的具体步骤
若要详细了解如何注册应用，请参阅注册应用以使用 OneDrive API。
让用户登录
应用必须使用特定作用域与 Microsoft 帐户授权 Web 服务进行通信，从而启动登录流程，并获取访问令牌。 登录流程遵循标准 OAuth 2.0 身份验证流，并要求从 Web 浏览器或 Web 浏览器控件进行调用。
身份验证作用域
作用域决定了在用户登录时应用获得的访问权限类型。 所有作用域都支持网站单一登录。也就是说，如果用户已登录 OneDrive，可以跳过身份验证流，直接转到授权流。
| 作用域名称 | 说明 | 必需 |
|---|---|---|
| offline_access | 允许应用脱机运行，即使用户处于非活动状态，也不例外。 这为应用提供了 refresh_token，可用于在必要时生成其他访问令牌。 此作用域不适用于令牌流。 | 否 |
| onedrive.readonly | 授予对用户的所有 OneDrive 文件（包括与用户共享的文件）的只读权限。 | 是 |
| onedrive.readwrite | 授予对用户的所有 OneDrive 文件（包括与用户共享的文件）的读取和写入权限。 必须有此作用域，才能创建共享链接。 | 是 |
| onedrive.appfolder | 授予对应用的特定文件夹的读取和写入权限。 | 是 |
例如，典型应用可能会请求获取以下作用域：
onedrive.readwrite offline_access
支持的身份验证流
可以选择下列两种支持的身份验证流：
令牌流
最简单的身份验证流是令牌流。 此流可用于快速获取访问令牌，以交互方式使用 OneDrive API。 由于此流不提供刷新令牌，因此不能用于长期访问 OneDrive API。
若要使用令牌流启动登录流程，请使用 Web 浏览器或 Web 浏览器控件加载 URL 请求。
GET https://login.live.com/oauth20_authorize.srf?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 | 应用所需的作用域列表（用空格分隔）。 |
将此重定向 URL 用于移动和桌面应用 https://login.live.com/oauth20_desktop.srf。
响应
成功验证和授权应用后，Web 浏览器会重定向到添加了其他参数的重定向 URL。
https://login.live.com/oauth20_authorize.srf#access_token=EwC...EB
&authentication_token=eyJ...3EM&token_type=bearer&expires_in=3600
&scope=onedrive.readwrite&user_id=3626...1d
在上面的示例中，access_token、authentication_token 和 user_id 的值已被截断。 access_token 和 authentication_token 的值相当长。
可以使用 access_token 的值向 OneDrive API 发出请求。
代码流
身份验证代码流流程包含三步，通过单独运行调用来验证和授权应用，并生成使用 OneDrive API 所需的访问令牌。 这样，应用还会收到刷新令牌，以便可以在某些情况下长期使用 API，允许未使用应用的用户进行访问。
第 1 步： 获取授权代码
若要使用代码流启动登录流程，请使用 Web 浏览器或 Web 浏览器控件加载此 URL 请求。
GET https://login.live.com/oauth20_authorize.srf?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://login.live.com/oauth20_authorize.srf?code=df6aa589-1080-b241-b410-c4dff65dbf7c
第 2 步： 兑换代码以获取访问令牌
收到 code 值后，可以兑换此代码以获取一组令牌，从而进行 OneDrive API 身份验证。 若要兑换代码，请发出以下请求：
POST https://login.live.com/oauth20_token.srf
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_token、token_type 和 refresh_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 向 OneDrive API 发出已验证的请求。
重要说明：请安全处理此响应中的 access_token 和 refresh_token 值，就像处理用户密码一样。
访问令牌仅在 expires_in 属性中指定的秒数内有效。 可以使用刷新令牌（若有）或从头开始重复执行身份验证请求流，请求获取新的访问令牌。
第 3 步： 获取新的访问令牌或刷新令牌
如果应用已请求访问 wl.offline_access，这一步将返回 refresh_token，可用于在初始令牌到期后生成其他访问令牌。
若要兑换刷新令牌以获取新的访问令牌，请发出以下请求：
POST https://login.live.com/oauth20_token.srf
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 的域部分必须与在 Live SDK 应用管理站点中指定的重定向 URI 的域部分匹配。
响应
如果调用成功，POST 请求响应中的 JSON 字符串将包含多个属性，包括 access_token、authentication_token 和 refresh_token（如果请求获取 wl.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 向 OneDrive API 发出已验证的请求。
重要说明：请安全处理此响应中的 access_token 和 refresh_token 值，就像处理用户密码一样。
访问令牌仅在 expires_in 属性中指定的秒数内有效。 可以使用刷新令牌（若有）或从头开始重复执行身份验证请求流，请求获取新的访问令牌。
注销用户
若要注销用户，请按照下列步骤操作：
- 删除之前从 OAuth 流收到的任何已缓存
access_token或refresh_token值。 - 在应用中执行任意注销操作（例如，清除本地状态、删除所有缓存项等）。
- 使用以下 URL 调用授权 Web 服务：
GET https://login.live.com/oauth20_logout.srf?client_id={client_id}&redirect_uri={redirect_uri}
此调用将删除所有启用单一登录的 Cookie，并确保在应用下一次启动登录流程时，用户必须输入用户名和密码，才能继续操作。
必需的查询字符串参数
| 参数名 | 值 | 说明 |
|---|---|---|
| client_id | string | 为应用创建的客户端 ID 值。 |
| redirect_uri | string | 身份验证完成时浏览器重定向到的 URL。 这必须与获取令牌请求中使用的 redirect_uri 值完全一致。 |
删除 Cookie 后，浏览器将重定向到所提供的重定向 URL。 当浏览器加载重定向页时，不会设置任何身份验证查询字符串参数，可以推断用户已注销。
撤消访问权限
用户可以访问 Microsoft 帐户管理许可页，撤消应用对自己帐户的访问权限。
撤消应用许可后，之前向应用提供的所有刷新令牌都会失效。 需要重复执行身份验证流，从头开始请求获取新的访问令牌和刷新令牌。
错误
如果身份验证出错，Web 浏览器会重定向到报错网页。 虽然报错网页始终都会显示最终用户易懂消息，但也可以参考报错网页 URL 包含的其他信息，此类信息有助于调试所遇到的错误。 这种信息并非总是显示在浏览器内的报错网页内容中。
https://login.live.com/err.srf?lc=1033#error={error_code}&error_description={message}
URL 中包含查询参数，可用来分析错误并采取相应的措施。 这些参数（# 字符后）始终可以添加为书签。 报错网页内容始终都会显示用户易懂的一般错误消息。
如果用户选择不许可应用，流会重定向到 redirect_uri，URL 中也包含相同的错误参数。
错误参数
| 参数名称 | 值 | 说明 |
|---|---|---|
| error | string | 标识所发生的错误的错误代码。 |
| error_description | string | 错误说明。 |
相关主题
下列主题简要概述了 OneDrive API 的其他概念。