OneNote 身份验证和 Azure AD 应用程序权限

项目
02/14/2017

适用于：Office 365 上的企业笔记本

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

注册你的应用程序并获取客户端 ID 和密码
选择 OneNote 应用程序权限范围
获得管理员同意
获取访问令牌
到期后获取新的访问令牌

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

请参阅注册你的应用程序并获取客户端 ID 和密码。

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

权限范围表示对 OneNote 内容的访问级别。应用程序权限是由组织管理员授予应用程序的，并且只能用于访问该组织及其员工拥有的数据。例如，OneNote API 公开多个应用程序权限以执行以下操作：

查看所有用户的笔记
查看和修改所有用户的笔记

按照这些步骤将 OneNote 应用程序权限分配给您的应用程序：

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

应用程序权限的范围

如果要使用应用程序权限访问笔记本，请从以下范围中进行选择。

范围（企业）	在 Azure 门户中的权限	说明
Notes.Read.All	查看所有用户的笔记	允许应用程序不以登录用户的身份查看机构中所有用户的 OneNote 笔记。该应用无法创建新笔记、修改现有笔记或在受密码保护部分查看笔记。
Notes.ReadWrite.All	查看和修改所有用户的笔记	允许应用程序不以登录用户的身份查看并修改机构中所有用户的 OneNote 笔记。该应用程序无法访问受密码保护部分的笔记。

建议：将用户登录到你的应用

通常，当你构建使用应用程序权限的应用程序时，此应用需要一个页面或视图，以便管理员批准此应用的权限。这一页面可以是此应用登录流程的一部分、应用设置的一部分，也可以是一个专用“连接”流程。在很多情况下，只有在用户使用工作或学校 Microsoft 帐户登录后，应用才会显示此“连接”视图。

如果你将用户登录到你的应用，你可以在要求用户批准应用程序权限之前识别用户所属的组织。虽然不是绝对必要，但这能帮助你为用户创造更直观的体验。要将用户登入，按照我们的 v2.0 协议教程执行。

向目录管理员请求权限

当你准备从组织管理员那里请求权限时，你可以将用户重定向到管理员同意端点。您可以进行如下所示的 API 调用：

// Line breaks are for legibility only.

// Replace {tenant} with the tenant (GUID or name) you need admin consent for
// Replace {app_id} with your Azure AD assigned application id

GET https://login.microsoftonline.com/{tenant}/adminconsent?
client_id={app_id}
&state=12345
&redirect_uri=https://localhost/myapp/permissions

你也可以在浏览器中尝试上述请求，在浏览器的地址栏中输入以下 URL（按照这些说明制作一个有效的 URL）。

// Replace {tenant} with the tenant (GUID or name) you need admin consent for
// Replace {app_id} with your Azure AD assigned application id

https://login.microsoftonline.com/{tenant}/adminconsent?client_id={app_id}&state=12345&redirect_uri=https://localhost/myapp/permissions

此表描述了在上一个请求中使用的参数：

参数	条件	说明
租户	必需	你想要请求其权限的目录租户。可以采用 GUID 或友好的名称格式。如果你不知道用户属于哪个租户，并且想让他们登录到所有租户，请使用通用租户。
client_id	必需	应用程序注册门户分配给你的应用的应用程序 ID。
redirect_uri	必需	要向其发送响应供应用处理的重定向 URI。它必须完全匹配在门户中注册的重定向 URI 之一，但它必须采用 URL 编码，且可以拥有其他路径段。
状态	建议	请求中包含的值，也会在令牌响应中返回。它可以是你希望的任何内容的字符串。此状态用于在发生身份验证请求前，对应用中的用户状态信息进行编码（例如它们所在的页面或视图上）。

将提供一个管理员同意对话框，让你可以继续和批准。

成功的响应

如果管理员批准应用程序的权限，则成功的响应如下所示：

GET https://login.microsoftonline.com/{tenant}/Consent/Grant

此表介绍了以前的响应中返回的值：

参数	说明
租户	以 GUID 格式向应用程序授予其请求的权限的目录租户。

错误响应

如果管理员不批准你的应用程序的权限，则失败的响应如下所示：

GET https://login.microsoftonline.com/{tenant}/login

Additional technical information: 
Correlation ID: f3817dd1-8476-46c2-a81b-fdefd209f988 
Timestamp: 2017-01-18 05:36:57Z 
AADSTS90093: This operation can only be performed by an administrator. Sign out and sign in as an administrator or contact one of your organization's administrators.

此表介绍了以前的响应中返回的值：

参数	说明
租户	以 GUID 格式向应用程序授予其请求的权限的目录租户。

在你收到应用配置终端的成功响应后，你的应用获得了它所请求的直接应用权限。现在可以为你需要的资源申请一个令牌。

备注

对特定租户而言，管理员同意是一次性步骤。
如果您希望应用程序运行.her 租户，必须将其配置为在 Azure AD 内的多租户应用程序。
无论应用程序是在自己的租户还是在其他租户中运行，管理员同意是必需的步骤
除了应用程序权限外，你的应用程序还可以选择委托权限（但仍需要管理员同意）。

获取访问令牌（企业应用程序）

在获得应用程序的必要授权后，继续为 API 获取访问令牌。

要通过使用客户端凭据授权获取令牌，请发送一个 POST 请求，如下所示：

// Replace {tenant} with the tenant (GUID or name) you need admin consent for
// Replace {app_id} with your Azure AD assigned application id
// Replace {app_secret} with an Azure AD generated key for your application

POST https://login.microsoftonline.com/{tenant}/oauth2/token HTTP/1.1
Host: login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id={app_id}&client_secret={app_secret}&resource=https%3A%2F%2Fonenote.com%2F

此表描述了在上一个请求中使用的参数：

参数	条件	说明
grant_type	必需	必须是 `client_credentials`。
client_id	必需	应用程序注册门户分配给你的应用的应用程序 ID。
client_secret	必需	你在应用注册门户中为应用生成的应用程序密码。注意，这是 URL 编码
资源	必需	为此请求中 `resource` 参数传递的值应该是所需资源的资源标识符（应用程序 ID URI）。对于 OneNote API，此值为 `https://onenote.com/`。此值会通知 v2.0 令牌端点您为应用配置的所有直接应用程序权限，它应该为与您要使用的资源关联的应用颁发令牌。

成功的响应

成功的响应如下所示：

{
  "token_type": "Bearer",
  "expires_in": "3600",
  "resource": "https:\/\/onenote.com\/",
  "access_token": "eyJ0eXAiOiJKV1Qi..."
}

此表描述了在上一个请求中使用的参数：

参数	说明
token_type	表示令牌类型值。Azure AD 唯一支持的类型是`bearer`
expires_in	访问令牌的有效期是多久（以秒为单位）。
资源	此令牌可用于相应资源的资源标识符（应用程序 ID URI）。
access_token	请求的访问令牌。应用可以使用此令牌针对受保护的资源（如 Web API）进行身份验证。

错误响应

错误响应如下所示（在本例中，请求提供了无效的 client_secret 值）：

{
  "error": "invalid_client",
  "error_description": "AADSTS70002: Error validating credentials. AADSTS50012: Invalid client secret is provided.\r\nTrace ID: b6e89947-f005-469e-92ad-18aed399b140\r\nCorrelation ID: c2d1c230-bee9-41f1-9d4d-a5687e01b7bc\r\nTimestamp: 2017-01-19 20:34:11Z",
  "error_codes": [
    70002,
    50012
  ],
  "timestamp": "2017-01-19 20:34:11Z",
  "trace_id": "b6e89947-f005-469e-92ad-18aed399b140",
  "correlation_id": "c2d1c230-bee9-41f1-9d4d-a5687e01b7bc"
}

此表描述了在上一个请求中使用的参数：

参数	说明
错误	一个错误代码字符串，可用于对发生的错误类型进行分类，并对错误作出回应。
error_description	一条特定的错误消息，可能会帮助你确定身份验证错误的根本原因。
error_codes	可能有助于诊断的 STS 特定错误代码列表。
时间戳	发生错误的时间。
trace_id	可能有助于诊断的请求唯一标识符。
correlation_id	可能有助于组件间诊断的请求唯一标识符。

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

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

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

访问令牌只有一个小时的有效期，因此到期时你必须获取新令牌。你应该在使用前检查令牌的到期时间，并在必要时获取新的访问令牌。管理员不必再次同意授予权限，除非他们撤消权限。

到期后获取新的访问令牌

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

你可以重复本主题前面获取访问令牌一节所述的流程请求新的访问令牌。

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

错误

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

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

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

通过

OneNote 身份验证和 Azure AD 应用程序权限

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

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

应用程序权限的范围

建议：将用户登录到你的应用

向目录管理员请求权限

成功的响应

错误响应

获取访问令牌（企业应用程序）

成功的响应

错误响应

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

到期后获取新的访问令牌

错误

另请参阅

其他资源

通过

OneNote 身份验证和 Azure AD 应用程序权限

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

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

应用程序权限的范围

获得管理员同意

建议：将用户登录到你的应用

向目录管理员请求权限

成功的响应

错误响应

获取访问令牌（企业应用程序）

成功的响应

错误响应

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

到期后获取新的访问令牌

错误

另请参阅

其他资源