OneNote 身份验证和权限

项目
11/18/2015

适用于：OneDrive 上的消费者笔记本 | Office 365 上的企业级笔记本

OneNote 使用 Microsoft 帐户（以前称为 Live Connect）和 Azure Active Directory 来提供对 OneNote 笔记本的安全访问。在访问笔记本之前，首先需要使用 Microsoft 帐户或 Azure AD 进行身份验证并获取访问令牌。

Microsoft 帐户用于访问 OneDrive 上的消费者笔记本，而 Azure AD 用于访问 Office 365 上的企业笔记本。

这两个授权服务都执行了 OAuth 2.0 协议，提供与 OneNote 进行交互所需的访问令牌。向 OneNote API 发送的所有请求都必须在 Authorization 标头中包含一个有效的访问令牌。

本文介绍了你负责的与身份验证相关的流程：注册应用以获取客户端 ID、指定所需的权限以及调用授权服务，从而让用户登录并获取访问令牌。

你或许可以使用 SDK 简化身份验证流程，具体取决于你的平台。

备注

OneNote 最终将支持 v2.0 应用程序模型提供的该单一认证模式和应用注册。请留意 OneNote 开发人员博客的相关更新内容。

尝试 API

按照本文中的步骤，使用所喜欢的网络工具（如 Fiddler）获取访问令牌。

注册你的应用程序并获取客户端 ID 和机密（消费者应用）

首先，你需要向 Microsoft 注册一个应用程序。此过程会创建你从应用链接到的服务主体，并生成发送给授权服务的客户端 ID 和密码。

如果你的应用仅访问消费者笔记本电脑，或者对消费者笔记本电脑和企业笔记本电脑均进行访问，请执行此操作。

使用你的 Microsoft 帐户登录到 Microsoft 帐户开发人员中心。（如果你正在开发 Windows 应用商店应用，则请执行此操作。）

如果没有 Microsoft 帐户，则需要创建一个帐户。你应该使用自己常用的电子邮件地址。为了在我们的特色应用页面上突出显示你的应用程序，或者如果我们发现意外的网络流量来自你的应用程序，我们可能会尝试联系你。我们不会向你发送垃圾邮件或出售你的个人信息。
选择“创建应用程序”****。
输入你希望用户在系统提示其为你的应用授予权限时看到的名称，然后为你的应用选择主要语言。
如果你接受使用条款以及隐私和 Cookie 策略，则选择我接受继续注册。
在“API设置”页面上，选择你的应用类型并提供应用的相关信息：

Web 应用程序 （服务器端应用）

a. 对于** 移动或桌面客户端应用**，选择** 否**。

b. 对于目标域，输入服务 URL。

c. 输入你希望用户通过身份验证并向你的应用授予访问权限后使用的重定向 URL。

原生应用 （安装在设备上）

a. 对于** 移动或桌面客户端应用**，选择** 是**。

b. （可选）对于目标域，请输入移动服务 URL。

c. （可选）对于重定向 URL，请输入有效的 URL。这将用作你的应用标识符，且不必是物理端点。*
保存“应用设置”页面上显示的客户端 ID 和机密以及重定向网址（如果你提供有）。

Windows 应用商店应用

如果你正在创建 Windows 应用程序，你将在 Windows 开发人员中心注册你的应用程序。这将为你提供软件包标识（软件包 SID），你将使用这一标识而不是客户端 ID。

使用你的 Microsoft 帐户登录到 Windows 开发人员中心。
在仪表板上，选择创建新应用程序，然后输入你的应用程序名称。
在 Visual Studio 中，右键单击你的 Windows 应用商店应用项目，然后选择商店 > 将应用与商店关联。
在“将你的应用程序与 Windows 应用商店关联”窗口中，使用你的 Microsoft 帐户登录，选择你的应用，然后选择下一步 > 关联。这会将所需的 Windows 应用商店注册信息添加到应用程序清单。
对于通用 Windows 应用，请为 Windows Phone 项目重复执行前两个步骤。

选择 OneNote 权限范围（消费者应用程序）

权限范围表示对 OneNote 内容的访问级别。你请求应用程序所需的权限，并且用户在登录应用程序时授予或拒绝访问权限。用户只能授予其拥有的权限。

选择应用程序完成其工作所需的最低级别的权限。你可以请求多个范围。

范围（消费者）	说明
office.onenote_create	可以查看用户的 OneNote 笔记本列表并创建新页面，但无法查看或编辑现有页面。可以枚举用户的笔记本层次结构，并在任何位置创建页面。
office.onenote_update_by_app	可创建、查看和修改应用程序所创建的所有页面。
office.onenote_update	可创建、查看和修改用户的 OneNote 笔记本和页面中的任何内容。
office.onenote	可查看 OneNote 笔记本和页面，但不能对其进行修改。
wl.signin	Microsoft 帐户权限范围。允许你的应用程序利用单点登录功能。
wl.offline_access	Microsoft 帐户权限范围。允许应用程序接收刷新令牌，以便即使用户不活动时也可以脱机工作。此范围不适用于令牌流。

有关用以访问 Office 365 笔记本的权限，请参阅选择 OneNote 权限（企业应用程序）。

让用户登录签并获取访问令牌（消费者应用程序）

你的应用程序通过联系授权服务来启动登录过程。如果用户尚未登录或尚未同意，则该服务会提示他们提供凭据并同意你的应用所请求的权限。如果身份验证和授权成功，你将收到一个访问令牌，其中包含你对 OneNote API 的请求。

重要

如同对待用户密码一样，确保访问令牌和刷新令牌的安全。

备注

你或许可以使用 SDK 简化身份验证流程，具体取决于你的平台。

选择你的身份验证流程。两者都是标准 OAuth 2.0 流。

流	说明
令牌流	在一次调用中获取访问令牌。快速访问时很有用，但不提供长期访问的刷新令牌。也称为隐式流。
代码流	在第一次调用中获取授权码，并在第二次调用中交换代码以获取访问令牌。与 wl.offline-access 权限范围一起使用时，你的应用程序会收到一个可实现长期访问的刷新令牌。也称为授权代码流。

流

说明

令牌流

在一次调用中获取访问令牌。快速访问时很有用，但不提供长期访问的刷新令牌。

也称为隐式流。

代码流

在第一次调用中获取授权码，并在第二次调用中交换代码以获取访问令牌。与 wl.offline-access 权限范围一起使用时，你的应用程序会收到一个可实现长期访问的刷新令牌。

也称为授权代码流。

使用令牌流让用户登录

在 Web 浏览器或 Web 浏览器控件中加载以下 URL 请求。

GET https://login.live.com/oauth20_authorize.srf
  ?response_type=token
  &client_id={client_id}
  &redirect_uri={redirect_uri}
  &scope={scope}

所需的查询字符串参数	说明
response_type	你正在使用的身份验证流程的类型。在本例中为 token。
client_id	为应用程序创建的客户端 ID。
redirect_uri	为你的应用程序注册的重定向 URL。没有指定该参数的移动和桌面应用可以使用： `https://login.live.com/oauth20_desktop.srf`
scope	应用程序所要求的范围。例如：office.onenote%20wl.sign-in

成功验证和授权后，Web 浏览器会重定向到你的重定向 URL，并将访问参数附加到该 URL。参数包括 access_token 和 token_type，如下例所示。访问令牌在 expires_in 属性中指定的秒数内有效。

https://your-redirect-url
  #access_token=EwB4Aq...%3d
  &token_type=bearer
  &expires_in=3600
  &scope=office.onenote wl.signin
  &user_id=c519ea026ece84de362cfa77dc0f2348

使用“代码”流让用户登录

获取访问令牌是代码流的两个步骤：

让用户登录并获取授权代码。
用代码交换访问令牌。

第 1 步： 让用户登录并获取授权代码。要开始登录过程，请在 Web 浏览器或 Web 浏览器控件中加载以下 URL 请求。

https://login.live.com/oauth20_authorize.srf
  ?response_type=code
  &client_id={client-id}
  &redirect_uri={redirect-uri}
  &scope={scope}

所需的查询字符串参数	说明
response_type	你正在使用的身份验证流程的类型。在本例中为 code。
client_id	为应用程序创建的客户端 ID。
redirect_uri	为你的应用程序注册的重定向 URL。没有指定该参数的移动和桌面应用可以使用： `https://login.live.com/oauth20_desktop.srf`
scope	应用程序所要求的范围。例如： office.onenote wl.signin wl.offline_access

成功验证和授权后，网页浏览器将重定向到你的重定向 URL（code 参数已附加到 URL），如以下示例所示。复制 code 值，以在第 2 步中使用。此代码的有效期为几分钟。

https://your-redirect-uri
  ?code=M57010781-9e8c-e31e-ca0d-46bc104236c4

第 2 步： 使用授权代码交换访问令牌并刷新令牌。发送在消息正文中具有正确编码 URL 字符串的以下 HTTP 请求。

POST https://login.live.com/oauth20_token.srf
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&client_id={client-id}
&client_secret={client-secret}
&code={code}
&redirect_uri={redirect-uri}

所需的正文参数	说明
grant_type	请求的授权类型。在本例中为 authorization_code。
client_id	为应用程序创建的客户端 ID。
client_secret	为应用创建的客户端机密。
code	你在上一步作为 URL 参数收到的代码。
redirect_uri	应用程序的重定向 URL。这必须与第一个请求中的 redirect_uri 匹配。

如果成功，该响应将包含一个 JSON 字符串，其中包含 access_token_ ，如果你 之前请求了** wl.offline_ access** 范围，则还包含** refresh_ token**，如下例所示。访问令牌在 expires_in 属性中指定的秒数内有效。

{
  "token_type":"bearer",
  "expires_in":3600,
  "scope":"office.onenote wl.sign-in wl.offline-access",
  "access_token":"EwCAAq...wE=",
  "refresh_token":"MCvePE...$$",
  "user_id":"c519ea026ece84de362cfa77dc0f2348"
}

将访问令牌包含在对 OneNote API 的请求中

向 OneNote API 发送的所有请求都必须通过 Authorization 标头将访问令牌作为持有者令牌发送。例如，以下请求可获取五个笔记本，它们按名称字母顺序排序：

GET https://www.onenote.com/api/v1.0/me/notes/notebooks?top=5
Authorization: Bearer {access-token}

访问令牌只有一个小时的有效期，因此到期时你必须获取新令牌。你应该在使用前检查令牌的到期时间，并在必要时获取新的访问令牌。用户可以保持登录状态，他们不必再次同意权限，除非他们注销或撤销权限。

到期后获取新的访问令牌

你可以使用刷新令牌或从头开始重复执行身份验证流程，请求获取新的访问令牌。

如果访问令牌到期，向 API 发出的请求将会返回 401 Unauthorized 响应。应用程序应该处理这一响应，并在发送请求之前检查令牌到期时间。

发送在消息正文中具有正确编码 URL 字符串的以下 HTTP 请求。

如果你请求 wl.offline_access 权限并使用代码流，你将会收到一个刷新令牌。

POST https://login.live.com/oauth20_token.srf
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
&client_id={client-id}
&client_secret={client-secret}
&redirect_uri={redirect-uri}
&refresh_token={refresh-token}

所需的正文参数	说明
grant_type	请求的授权类型。在本例中为 refresh_token。
client_id	为应用程序创建的客户端 ID。
client_secret	为应用创建的客户端机密。
redirect_uri	应用程序的重定向 URL。这必须与之前用于获取令牌的 redirect_uri 匹配。
refresh_token	以前收到的刷新令牌。

如果成功，POST 请求的响应包含一个含有 access_token 和 refresh_token 的 JSON 字符串，如下例所示。

{
  "token_type":"bearer",
  "expires_in": 3600,
  "scope":"office.onenote wl.sign-in wl.offline-access",
  "access_token":"EwB4Aq...wE=",
  "refresh_token":"MCVw8k...$$",
  "user_id":"c519ea026ece84de362cfa77dc0f2348"
}

更新你所储存的令牌，以确保你的应用程序拥有最长使用寿命的令牌。

注销用户（消费者应用程序）

若要注销用户，请按照下列步骤操作：

删除任何缓存的访问令牌，或刷新你收到或存储的令牌。
在应用程序中执行任意注销操作（例如，清除本地状态、删除所有缓存项等）。
使用以下 URL 调用授权服务：

https://login.live.com/oauth20_logout.srf
  ?client_id={client_id}
  &redirect_uri={redirect_uri}

此调用将删除启用单点登录的所有 Cookie，并确保提示用户登录。

所需的查询字符串参数	说明
client_id	为应用创建的客户端 ID 值。
redirect_uri	应用程序的重定向 URL。这必须与之前用于获取令牌的 redirect_uri 匹配。

删除 Cookie 后，浏览器将重定向到你的重定向 URL。加载重定向页面时不指定任何验证查询字符串选项，这意味着用户已注销。

撤销访问权限

用户可通过访问 Microsoft 帐户管理页面来撤消应用程序对其帐户的访问权限。

撤消应用程序许可后，之前向应用程序提供的所有刷新令牌都会失效。如果尝试刷新令牌，则会收到以下响应：

{
  "error":"invalid_grant",
  "error_description":"The request was denied because one or more scopes requested are unauthorized or expired. The user must first sign in and grant the client application access to the requested scope."
}

需要从头开始重复授权流程，以便请求新的访问令牌和刷新令牌。

使用 Azure AD 进行身份验证（企业应用程序）

如果你的应用程序使用应用程序权限（而不是委托权限），请参阅 OneNote 身份验证和 Azure AD 应用程序权限。

注册你的应用程序并获取客户端 ID 和机密
选择 OneNote 权限
让用户登录并获取访问令牌
到期后获取新的访问令牌

注册你的应用程序并获取客户端 ID 和机密（企业应用程序）

首先，你需要向 Microsoft 注册一个应用程序。此过程会创建你从应用链接到的服务主体，并生成发送给授权服务的客户端 ID 和密码。

如果你的应用程序仅访问消费者笔记本电脑，或者对消费者笔记本电脑和企业笔记本电脑均进行访问，请执行此操作。

要在与 Office 365 订阅相关联的 Azure AD 租户上注册应用程序，需要：

获取对 Office 365 租户具有全局管理员权限的 Office 365 帐户

你可以试用或购买 Office 365 开发人员订阅，或订阅合格计划。
为租户配置 OneDrive for Business

这使得 OneNote 应用程序可用，因此你可以指定 OneNote 权限。要检查 OneDrive for Business 是否已提供，请使用你的 Office 365 证书（工作或学校帐户，如 someone@example.com 或 someone@example.onmicrosoft.com）登录 OneNote Online。

如果看到你的笔记本，则表明一切就绪。如果看到“对不起，我们似乎无法找到你的笔记本......”，请选择转至我的账户 > 下一步。当你的 OneDrive for Business 页面加载时，请返回并刷新 OneNote Online 以完成配置。

备注

必须先配置用户的个人网站，然后才能访问其笔记本。如果需要，OneNote API 将尝试自动配置其网站。
将你的 Office 365 订阅与 Azure 订阅相关联

这可让你在 Azure AD 中注册和管理你的应用程序。（了解更多）

如果你没有 Azure 订阅，请在下一节中执行选项 1。否则执行选项 2。

重要

你和用户的 Office 365 帐户必须具有有效的 Office 365 许可证。没有有效许可证的用户帐户将无法在 OneNote Online 上看到任何笔记本，并且对其笔记本的 API 调用将失败。 Office 365 管理员可以检查状态并分配未分配的许可证。

备注

MSDN 订阅者：可能有资格获得免费的 Office 365 开发人员订阅，并且可以在激活 Azure 权益时节省更多。在 MSDN 订阅页面检查你的权益。

将你的 Azure 订阅与 Office 365 订阅相关联

选项 1： 使用 Office 365 订阅的管理员凭据注册 Azure 订阅。如果没有 Azure 订阅，请执行此操作。该过程与订阅关联。

使用 Office 365 管理员凭据（工作或学校帐户，如 someone@example.com 或 someone@example.onmicrosoft.com）登录 Azure 管理门户。
在“找不到订阅”页面上，选择注册 Microsoft Azure。注册页面将加载，显示 Office 365 订阅中的一些信息。此帐户将成为新 Azure 订阅的服务管理员。

注册体验取决于你拥有试用还是付费的 Office 365 订阅：

如果你有试用订阅，在免费试用页面输入你的付款信息。除非你决定更改为付费订阅，否则不会被收费。

如果您同意订阅协议、优惠详情和隐私声明，请选中该复选框并选择购买。新的 Azure 帐户的“订阅”页面将打开。试用订阅将获得 200 美元的信用额度，可在 30 天内使用。你可以随时在此页面取消订阅。
如果您有付费订阅，填写你的联系信息，然后选择注册。订阅完成后，选择开始管理我的服务打开 Azure 管理门户。

选项 2： 将现有的 Azure 订阅与 Office 365 订阅相关联。如果你拥有的 Microsoft 帐户是 Azure 订阅的服务管理员或协管理员，则执行此操作。此过程使 Microsoft 帐户成为 Office 365 租户的全局管理员。

使用您的 Microsoft 帐户凭据（如 [ someone@live.com]）登录到 aad-portal Azure 管理门户someone@live.com 。
在页面底部的抽屉中，选择新建 > 应用服务 > Active Directory > 目录 > 自定义创建。
在“添加目录”窗口，选择对目录使用现有目录。
选择我准备好现在退出，然后单击复选标记。您即从门户网站中注销。
使用要关联的 Office 365 租户的全局管理员凭据（工作或学校帐户，例如 someone@example.com或 someone@example.onmicrosoft.com）重新登录。
在询问是否将目录与 Azure 一起使用时，请选择继续 > 立即注销。
关闭浏览器，然后重新打开 Azure 管理门户。
再次使用您的 Microsoft 帐户凭据登录，然后在导航窗格中选择 Active Directory。您的 Office 365 目录应列出于“目录”选项卡上。

将应用注册到 Azure 管理门户

登录到 Azure 管理门户。为您的 Azure 订阅使用管理员凭据。
在导航窗格中，选择 Active Directory。
选择想要注册应用程序的目录，然后打开“应用程序”选项卡。
在页面底部的抽屉中，选择 添加>添加我的组织正在开发的应用程序。
输入应用程序的友好名称并选择应用程序类型：

Web 应用程序或 Web API （基于浏览器或服务器的应用程序）

a. 选择 Web 应用程序和/或 Web API。

b. 对于登录 URL，请输入用户登录并使用应用的网址。

c. 对于应用程序 ID URI，输入应用程序的唯一标识符。它必须位于已验证的自定义域中。

d. 对于回复 URL，输入要重定向到的 URL 以响应 OAuth 2.0 请求。它不一定是物理端点，但必须是有效的 URI。

e. 要使该应用可供外部 Azure 租户使用，请对于** 应用程序是多租户选择是**。

本机客户端应用程序 （安装在设备上的应用程序）

a. 选择本机客户端应用程序。

b. 输入响应 OAuth 2.0 请求时的重定向 URI。它不一定是物理端点，但必须是有效的 URI。

对于 Web 应用程序，Azure 会同时生成客户端 ID 和应用程序密钥（或密码）。对于本机应用，Azure 会生成客户端 ID。保存这些值。

请参阅 Office 365 文档中有关注册应用程序的详细说明。

选择 OneNote 权限范围（企业应用）

权限范围表示对 OneNote 内容的访问级别。你请求应用程序所需的权限，并且用户在登录应用程序时授予或拒绝访问权限。用户只能授予其拥有的权限。

在 Azure 管理门户中对其他应用程序的权限的应用配置页面部分，选择添加应用程序。
选择 OneNote 应用程序，然后单击右下角的复选标记。如果 OneNote 没有列出，请确保已经为你的租户配置了 OneDrive for Business。
选择应用程序执行工作所需的最低级别权限，然后保存更改。你可以请求多个范围。

当前用户拥有的个人笔记本的范围

如果你只在 OneDrive for Business 上使用个人笔记本，请从以下范围中进行选择。

范围（企业）	在 Azure 门户中的权限	说明
Notes.Create	在 OneNote 笔记本中创建页面	可以查看您的笔记本和分区；在任意位置创建新的页面。无法查看或编辑现有页面。
Notes.ReadWrite.CreatedByApp	仅限应用程序的 OneNote 笔记本访问	可以查看您的笔记本和分区的标题；创建新的页面；重命名分区；查看和修改所创建的应用程序页。无法查看或修改其他应用程序或密码保护的分区中创建的页面。
Notes.Read	查看 OneNote 笔记本	可以查看您的笔记本和分区的内容。不能创建新页面、修改现有页面或访问密码保护的分区。
Notes.ReadWrite	查看和修改 OneNote 笔记本	可以查看你的笔记本和分区的标题；查看和修改所有页面；创建新的页面；重命名分区。无法访问受密码保护的分区。

当前用户可以访问的站点和组笔记本的范围

如果你正在使用 SharePoint 站点笔记本或 Office 365 组笔记本，请从以下范围中进行选择。这些权限也适用于当前用户的个人笔记本，但不适用于其他用户共享的个人笔记本。目前不支持访问共享的个人内容。

范围（企业）	在 Azure 门户中的权限	说明
Notes.Read.All	查看组织中的 OneNote 笔记本	可以查看已登录的用户有权访问的所有笔记本中的笔记本和分区的内容。不能创建新页面、修改现有页面或访问密码保护的分区。
Notes.ReadWrite.All	查看和修改组织中的 OneNote 笔记本	可以查看的笔记本和分区的标题；查看和修改所有页面；例如：重命名的所有分区；在登录用户有权访问的所有笔记本中创建新的页面。无法访问受密码保护的分区。

范围（企业）

在 Azure 门户中的权限

说明

Notes.Read.All

查看组织中的 OneNote 笔记本

可以查看已登录的用户有权访问的所有笔记本中的笔记本和分区的内容。

不能创建新页面、修改现有页面或访问密码保护的分区。

Notes.ReadWrite.All

查看和修改组织中的 OneNote 笔记本

可以查看的笔记本和分区的标题；查看和修改所有页面；例如：重命名的所有分区；在登录用户有权访问的所有笔记本中创建新的页面。

无法访问受密码保护的分区。

有关用于访问 OneDrive 上个人笔记本的权限，请参阅选择 OneNote 权限（消费者应用程序）。

让用户登录并获取访问令牌（消费者应用程序）

重要

如同对待用户密码一样，确保访问令牌和刷新令牌的安全。

备注

你或许可以使用 SDK 简化身份验证流程，具体取决于你的平台。

获取访问令牌是两步流程：

让用户登录并获取授权代码。
用代码交换访问令牌。

这个过程代表了授权代码许可流程。如果要使用隐式流，需要编辑清单文件。参见* 注册基于浏览器的网络应用程序*中的配置您的应用以允许 OAuth 2.0 隐式授权流程。

第 1 步： 让用户登录并获取授权代码。要开始登录过程，请在 Web 浏览器或 Web 浏览器控件中加载以下 URL 请求。

下面的 URL 使用共同的租户端点，它适用于任何应用程序。

https://login.microsoftonline.com/common/oauth2/authorize
  ?response_type=code
  &client_id={client-id}
  &redirect_uri={redirect-uri}
  &resource=https://onenote.com/

所需的查询字符串参数	说明
response_type	你正在使用的身份验证流程的类型。在本例中为 code。
client_id	为应用程序创建的客户端 ID。
redirect_uri	应用程序的重定向 URL。
资源	你需要访问的资源。在这种情况下， https://onenote.com/

https://your-redirect-uri/
  ?code=AAABAA...AA
  &session_state=d56e3523-614e-4fbe-bf89-3ba0f065954b

第 2 步： 使用授权代码交换访问令牌并刷新令牌。发送在消息正文中具有正确编码 URL 字符串的以下 HTTP 请求。

POST https://login.microsoftonline.com/common/oauth2/token
Content-Type: application/x-www-form-urlencoded
grant_type=authorization_code
&client_id={client-id}
&client_secret={client-secret}
&redirect_uri={redirect-uri}
&code={code}
&resource=https://onenote.com/

所需的正文参数	说明
grant_type	请求的授权类型。在本例中为 authorization_code。
client_id	为应用程序创建的客户端 ID。
client_secret	仅限 Web 应用程序和 Web API。为应用创建的客户端机密。
code	你在上一步作为 URL 参数收到的代码。
redirect_uri	应用程序的重定向 URL。这必须与第一个请求中的 redirect_uri 匹配。
资源	你需要访问的资源。在这种情况下， https://onenote.com/

如果成功，该响应包含一个 JSON 字符串，其中包含 access_token 和 refresh_token，如以下示例所示。访问令牌在 expires_in 属性中指定的秒数内有效。

{
  "token_type":"Bearer",
  "expires_in":"3600",
  "scope":"Notes.ReadWrite",
  "expires_on":"1446588136",
  "not_before":"1446584236",
  "resource":"https://onenote.com/",
  "access_token":"eyJ0eX...2-w",
  "refresh_token":"AAABAAA...IAA",
  "id_token":"eyJ0eX...fQ."
}

请参阅授权码授予流程，了解更多有关在 Azure AD 中实施代码授权流程的信息，包括你可以在请求中使用的其他参数。

将访问令牌包含在对 OneNote API 的请求中

GET https://www.onenote.com/api/v1.0/me/notes/notebooks?top=5
Authorization: Bearer {access-token}

到期后获取新的访问令牌（企业应用）

你可以使用刷新令牌或从头开始重复执行身份验证流程，请求获取新的访问令牌。

如果访问令牌到期，向 API 发出的请求将会返回 401 Unauthorized 响应。应用程序应该处理这一响应，并在发送请求之前检查令牌到期时间。

发送在消息正文中具有正确编码 URL 字符串的以下 HTTP 请求。

以下示例中的 URL 使用常用租户端点，它适用于任何应用程序。

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

grant_type=refresh_token
&client_id={client-id}
&client_secret={client-secret}
&redirect_uri={redirect-uri}
&refresh_token={refresh-token}
&resource={resource-id}

所需的正文参数	说明
grant_type	请求的授权类型。在本例中为 refresh_token。
client_id	为应用程序创建的客户端 ID。
client_secret	仅限 Web 应用程序和 Web API。为应用创建的客户端机密。
redirect_uri	应用程序的重定向 URL。
refresh_token	以前收到的刷新令牌。
资源	你需要访问的资源。在这种情况下， https://onenote.com/

如果成功，该响应包含一个含有 JSON 字符串的 POST 请求，该字符串中含有 access_token 和 refresh_token，如以下示例所示。

{
  "token_type":"Bearer",
  "expires_in":"3600",
  "scope":"Group.Read.All Notes.ReadWrite",
  "expires_on":"1447656020",
  "not_before":"1447652120",
  "resource":"https://onenote.com/",
  "access_token":"eyJ0eX...Jww",
  "refresh_token":"AAABAAA...IAA"
}

更新你所储存的令牌，以确保你的应用拥有最长使用寿命的令牌。

适用于 OneNote 开发的 SDK

OneNote 应用程序可以使用 OneDrive API SDK 获取对 OneNote API 的所有请求所需的访问令牌。 SDK 使你可以更轻松地进行身份验证。只需提供身份信息并集成一些调用，SDK 即可处理登录和同意、获取、存储以及刷新令牌的所有方面。然后，可以对 OneNote API 进行 REST 调用。我们的 iOS 教程显示如何在 OneNote 应用程序中使用 SDK。

所有版本的 SDK 都支持 Microsoft 帐户身份验证（适用于消费者笔记本），还有一些版本还支持 Azure Active Directory（适用于企业笔记本）。参见 OneDrive 文档，了解当前支持的平台列表。

备注

OneDrive API SDK 取代了 Live SDK。 Live SDK 已弃用，但将继续支持使用它的现有 OneNote 应用程序。对于新开发，请使用 OneDrive API SDK。

在某些时候，我们可能会提供既处理身份验证又支持对 OneNote API 的本地调用的库，但目前请使用 OneDrive API SDK。

或者，企业应用程序可以使用 Active Directory 身份验证库 (ADAL) 访问 Office 365 和 SharePoint 托管的笔记本。如果平台没有可用的 SDK，或者希望加强对身份验证过程的控制，则可以考虑直接使用 ADAL。我们的 ASP.NET MVC 教程显示如何在 OneNote 应用程序中使用 ADAL。

重要

要与 OneNote 内容和资源进行交互，应始终使用 OneNote API。不要使用 OneDrive API。

错误

如果身份验证出错，Web 浏览器会重定向到报错网页。错误页面提供了终端用户友好消息，但此页面的 URL 包含可帮助你找出所发生错误的其他参数。这些 URL 参数包含一个书签，例如： #error={error_code}&error_description={message}

如果用户选择不为你的应用程序提供权限，则将转至重定向 URL 并包含错误参数。

有关处理错误的详细信息，请参阅 OAuth 2.0 中的错误处理。

通过

OneNote 身份验证和权限

尝试 API

使用 Microsoft 帐户（消费者应用）进行身份验证

注册你的应用程序并获取客户端 ID 和机密（消费者应用）

Windows 应用商店应用

选择 OneNote 权限范围（消费者应用程序）

让用户登录签并获取访问令牌（消费者应用程序）

使用令牌流让用户登录

使用“代码”流让用户登录

将访问令牌包含在对 OneNote API 的请求中

到期后获取新的访问令牌

注销用户（消费者应用程序）

撤销访问权限

使用 Azure AD 进行身份验证（企业应用程序）

注册你的应用程序并获取客户端 ID 和机密（企业应用程序）

将你的 Azure 订阅与 Office 365 订阅相关联

将应用注册到 Azure 管理门户

选择 OneNote 权限范围（企业应用）

当前用户拥有的个人笔记本的范围

当前用户可以访问的站点和组笔记本的范围

让用户登录并获取访问令牌（消费者应用程序）

将访问令牌包含在对 OneNote API 的请求中

到期后获取新的访问令牌（企业应用）

适用于 OneNote 开发的 SDK

错误

另请参阅

其他资源