在您的应用程序中使用 OAuth 身份验证

What's my plan?

Suite

Team, Growth, Professional, Enterprise, or Enterprise Plus

Support

Team, Professional, or Enterprise

位置：管理中心 > 应用和整合 > API > Zendesk API

您可使用 OAuth 2 对您的应用程序向 Zendesk 发送的所有 API 请求进行身份验证。OAuth 为您的应用程序提供了一种访问 Zendesk 数据的安全方式，而无需存储和使用 Zendesk 用户的密码，密码属于敏感信息。

要使用 OAuth 身份验证，您需要向 Zendesk 注册您的应用程序。您还需要在您的应用程序中添加一些功能，以支持 OAuth 授权工作流程。

本文章涵盖以下主题：

• 在 Zendesk 中注册应用程序
• OAuth 客户端类型
• OAuth 客户端凭证授权类型
• 在您的应用程序中实施 OAuth 授权工作流程

相关主题

• 有关构建实现 OAuth 授权工作流程的 Web 应用程序的教程，请参阅构建 OAuth Web 应用程序。
• 要在 Zendesk 应用中实现 OAuth 授权流程，请参阅在 Support 应用中添加第三方 OAuth。
• 如果您不需要用户授予您的应用程序对其帐户的访问权限，您仍然可以使用 OAuth 密钥对 API 请求进行身份验证。请参阅通过 API 创建和使用 OAuth 令牌。

使用 Zendesk 注册应用程序

您必须注册应用程序以生成 OAuth 凭证，您的应用程序可使用该凭证对 Zendesk 的 API 调用进行身份验证。

注意：本节介绍如何为拥有一个 Zendesk 帐户的用户设置 OAuth 客户端。如果您的应用程序不仅要与一个 Zendesk 帐户交互，而是多个帐户，您可以申请一个全局 OAuth 客户端。全局 OAuth 客户端是对多个 Zendesk 实例进行 API 身份验证的一种安全、简洁的方式。有关更多信息，请参阅设置全局 OAuth 客户端。

注册应用程序的步骤

1. 在管理中心，单击侧栏中的应用和整合 ()，然后选择 API > Zendesk API。
2. 单击 Zendesk API 页面上的 OAuth 客户端选项卡，然后单击 OAuth 客户端列表右侧的添加 OAuth 客户端。
3. 填写以下字段以创建客户端：
   • 客户端名称——为您的应用输入一个名称。这是当用户被询问是否授予应用程序访问权限，以及当他们查看可访问其 Zendesk 的第三方应用列表时看到的名称。
   • 描述（选填）。这是对您的应用的简短描述，当用户被询问是否授予访问权限时，将会看到该描述。
   • 公司（选填）。这是当用户被询问是否授予应用程序访问权限时看到的公司名称。此信息可帮助他们了解正在向谁授予访问权限。
   • 徽标（选填）。这是当用户被询问是否授予应用程序访问权限时看到的徽标。图像可以是 JPG、GIF 或 PNG。为获得最佳效果，请上传方形图像。系统将针对授权页面调整图像大小。
   • 唯一标识符——此字段将使用您为应用输入的名称的重新格式化版本自动填充。您可以根据需要进行更改。
   • 客户端类型 - 公共或机密。公共 OAuth 客户端是在无法安全存储凭证的环境中运行的应用程序，例如移动和网络应用。这些客户端必须使用 PKCE。机密 OAuth 客户端在安全服务器上运行，其凭证可妥善保存。这些客户端可以使用 PKCE 和/或客户端密钥。请参阅 OAuth 客户端类型。
   • 重定向 URL——输入 Zendesk 应该用于发送用户决定以授予您应用程序访问权限的 URL。URL 必须是绝对的而不是相对的，https（除非是本地主机或 127.0.0.1），并且用新建行隔开。
4. 单击保存。

   页面刷新后，下方会出现一个新的预填充密钥字段。这是 OAuth2 规范中指定的“client_secret”值。

5. 将密钥值复制到剪贴板并保存在安全的地方。注意：字符可能超出文本框的宽度，因此请确保在复制前选择所有内容。
   重要提示：出于安全的原因，您的密钥仅完整显示一次。单击保存后，您将只能访问前九个字符。
6. 单击保存。

按以下主题中所述，在您的应用程序中使用唯一标识符和密钥值。

OAuth 客户端类型

Zendesk OAuth 客户端包括 kind 属性（在 OAuth 客户端创建期间传递），可具有以下值之一：

• 公开：公共 OAuth 客户端是在无法安全存储凭证的环境中运行的应用程序，例如移动和网络应用。这些客户端需要使用 PKCE。
• 机密：机密 OAuth 客户端在安全服务器上运行，其凭证可妥善保存。这些客户端可以使用 PKCE 和/或客户端密钥。

有关更多信息，请参阅客户端类型。

Zendesk OAuth 客户端类型仅适用于 Zendesk Support 工单处理系统。Chat、Conversations 或 Sell 不支持此功能。

现有的 Zendesk OAuth 客户端当前的 kind 属性已设置为 unknown。在 kind 属性更新为 public 或 confidential 之前，这些客户端不受影响。在管理中心创建的新 OAuth 客户端必须在创建期间设置 kind 属性。

注意：如果您使用现有的 Zendesk OAuth 客户端，并计划将 kind 属性更改为 public，则必须先实施 PKCE。否则将导致客户端无法工作，因为此时需要立即提供 PKCE。

设置 kind 属性对于在管理中心创建的所有新 OAuth 客户端是必须的。而 kind 属性对于使用 api/v2/oauth/clients endpoint 创建的 OAuth 客户端而言不是必须的，但 Zendesk 建议设置此属性。

OAuth 客户端凭证授权类型

OAuth 客户端凭证授权类型仅适用于机密客户端，允许您仅使用特定客户端的密钥创建 OAuth 密钥。要使用此工作流程，请使用 grant_type: client_credentials 传递有效的 client_secret 参数到 /oauth/tokens 端点以生成新的 OAuth 访问密钥。与其他授权流程不同，此授权类型不会返回刷新密钥，也不需要用户授权。与该密钥关联的用户将与所用客户端链接的用户相同。您可以选择添加 expires_in 值以设置密钥的过期时间（毫秒）。出于安全的原因，不允许公开客户端使用此授权类型。有关更多信息，请参阅 OAuth 客户端。

OAuth 刷新密钥授权类型

OAuth 刷新密钥授权类型允许刷新已过期或即将过期的访问密钥。要生成新的 OAuth 访问密钥，请使用 grant_type: refresh_token 将 refresh_token 参数传递到 https://{subdomain}.zendesk.com/oauth/tokens 端点，这会返回新的访问密钥和刷新密钥，同时使之前的访问密钥和刷新密钥失效。

OAuth 客户端应实施回退机制来处理过期的访问密钥和刷新密钥。例如，如果访问密钥已过期或遇到错误，可以进行刷新。但是，如果刷新失败，或没有刷新密钥链接到访问密钥，则必须将用户重定向到 https://{subdomain}.zendesk.com/oauth/authorizations/new 以对应用程序重新授权。有关更多信息，请参阅授权类型的 OAuth 密钥和在 API 中创建和使用 OAuth 访问密钥。

在您的应用程序中实施 OAuth 授权工作流程

Zendesk 支持授权代码授权工作流程以获取访问密钥。此流程称为授权代码授予工作流程，因为您必须先获取授权代码，然后才能请求访问密钥。

此流程使用刷新密钥，可以生成新的访问密钥，而不需要用户重新授权。如果 API 提供了有效的 expires_in 参数，说明密钥的具体有效期，则访问密钥可能会过期。在这种情况下，应实施一种机制，让用户在访问密钥过期前使用系统提供的刷新密钥刷新访问密钥。

要实施授权代码授予工作流程，您需要将以下功能添加到您的应用程序：

• 步骤 1：将用户发送到 Zendesk 授权页面
• 步骤 2：处理用户的授权决定
• 步骤 3：从 Zendesk 获取访问密钥
• 步骤 4：在 API 调用中使用访问密钥

有关构建实现 OAuth 授权工作流程的 Web 应用程序的教程，请参阅构建 OAuth Web 应用程序。

授权代码授予方法支持代码交换证明密钥 (PKCE)，增添了额外的安全保护。有关更多信息，请参阅开发者文档中的使用 PKCE 提高 Zendesk OAuth 访问密钥的安全性。

步骤 1：将用户发送到 Zendesk 授权页面

首先，您的应用程序必须将用户发送到 Zendesk 授权页面。此页面会要求用户授权您的应用程序代表其访问 Zendesk。在用户做出选择后，Zendesk 会将该选择以及其它一些信息发送回您的应用程序。

将用户发送到 Zendesk 授权页面

在您的应用程序中添加一个链接或按钮，将用户发送到以下 URL：

https://{subdomain}.zendesk.com/oauth/authorizations/new

其中 {subdomain} 是您的 Zendesk 核心子域名，而不是主机映射的子域名。

您可以使用 POST 或 GET 请求。包括以下参数：

• response_type：必填。Zendesk 在响应中返回授权代码，因此请指定 code 作为响应类型。例如：response_type=code。
• redirect_uri：必填。Zendesk 应该用于发送用户决定以授予您应用程序访问权限的 URL。URL 必须是绝对 URL，而不能是相对 URL。URL 还必须是安全的 (https)，除非您使用的是 localhost 或 127.0.0.1。
• client_id：必填。这是您在 Zendesk 注册应用程序时获得的唯一标识符。请参阅上面的部分。
• scope：必填。这是控制对 Zendesk 资源访问的范围列表，用空格分隔。您可以请求对所有资源或特定资源的读取、写入或模拟访问权限。请参阅设置范围。
• state：在用户决定是否授予访问权限后，包含在 Zendesk 响应中的任意字符串。您可以使用该参数来防范跨站请求伪造 (CSRF) 攻击。在 CSRF 攻击中，终端用户被欺骗单击一个链接，在终端用户仍通过身份验证的 Web 应用程序中执行操作。要防范此类攻击，请为 state 参数添加值并在它返回时进行验证。
• code_challenge：使用 PKCE 时必填。它是一个字符串，表示来自代码验证程序的代码质询。请参阅开发者文档中的生成 code_challenge 值。
• code_challenge_method - 使用 PKCE 时必填。用于生成代码质询的方法。指定值 S256。

确保对参数进行 URL 编码。

GET 请求范例

https://{subdomain}.zendesk.com/oauth/authorizations/new?response_type=code&redirect_uri={your_redirect_url}&client_id={your_unique_identifier}&scope=read%20write

Zendesk 授权页面将在终端用户的浏览器中打开。用户做出决定后，Zendesk 将决定发送到您在请求中指定的重定向 URL。

设置范围

您必须指定一个范围以控制应用对 Zendesk 资源的访问。读取范围授予应用访问 GET 端点的权限。它包括侧载相关资源的权限。写入范围授予应用对 POST、PUT 和 DELETE 端点的访问权限，用于创建、更新和删除资源。

有关范围的更多信息，请参阅用于授予类型的 OAuth 密钥。

模拟范围允许 Zendesk 管理员代表终端用户发出请求。请参阅代表终端用户发出 API 请求。

例如，以下参数授予应用对所有资源的读取权限：

"scope": "read"

以下参数授予对所有资源的读取和写入权限：

"scope": "read write"

您可以将范围微调到以下资源：

• tickets
• users
• auditlogs（只读）
• organizations
• hc
• apps
• triggers
• automations
• targets
• webhooks
• zis

语法如下：

"scope": "resource:scope"

例如，以下参数将应用限制为仅读取工单：

"scope": "tickets:read"

要授予应用对资源的读写权限，请指定两个范围：

"scope": "users:read users:write"

要仅授予应用对一个资源（如组织）的写入权限，并授予其它所有内容的读取权限：

"scope": "organizations:write read"

步骤 2：处理用户的授权决定

您的应用程序必须处理来自 Zendesk 的响应，告知用户的决定。此信息包含在重定向 URL 的 URL 参数中。

如果用户决定授予应用程序访问权限，重定向 URL 将包含一个授权代码。例如：

{redirect_url}?code=7xqwtlf3rrdj8uyeb1yf

授权码的有效期仅 120 秒。

如果用户决定不授予应用程序访问权限，重定向 URL 将包含 error 和 error_description 参数，通知应用用户已拒绝访问：

{redirect_url}?error=access_denied&error_description=The+end-user+or+authorization+server+denied+the+request

使用这些值可控制应用程序的工作流程。如果 URL 包含 code 参数，则从 Zendesk 获取访问密钥，如以下部分所述。这是要包含在对 Zendesk 的 API 调用中的密钥。

步骤 3：从 Zendesk 获取访问密钥

如果您的应用程序在用户授予访问权限时从 Zendesk 收到了授权代码，您的应用程序可以用它来交换访问密钥。要获取访问密钥，请向以下端点发出 POST 请求：

https://{subdomain}.zendesk.com/oauth/tokens

注意：不要将此端点与 OAuth 密钥 API 中的 Create Token 端点混淆。尽管两个端点都返回有效的 OAuth 访问密钥，但它们的路径、JSON 格式或请求参数不同。

在请求中包含以下必要参数：

• grant_type：指定“authorization_code”作为值。
• code：使用您在用户授予访问权限后从 Zendesk 收到的授权代码。
• client_id：使用在 Support 管理界面的 OAuth 客户端中指定的唯一标识符（管理 > 渠道 > API > OAuth 客户端）。请参阅在 Zendesk 中注册应用程序。
• client_secret：使用在 Support 管理界面的 OAuth 客户端中指定的密钥（管理 > 渠道 > API > OAuth 客户端）。请参阅在 Zendesk 中注册应用程序。

  如果您使用 PKCE code_challenge 和 code_verifier 参数，client_secret 不是必填项。您可以使用此特征从隐式授权工作流程迁移，但出于安全考虑，已不再建议使用此功能。请参阅开发者文档中的使用 PKCE 从隐式授权工作流程迁移。

• redirect_uri：与第 1 步中相同的重定向 URL。仅用于 ID。
• scope：请参阅设置范围。
• code_verifier：使用 PKCE 时必填。用于生成 code_challenge 值的字符串。请参阅开发者文档中的生成 code_challenge 值。
• expires_in - 可选。访问密钥有效的秒数。请参阅授权类型的 OAuth 密钥。
• refresh_token_expires_in - 可选。刷新密钥有效的秒数。请参阅授权类型的 OAuth 密钥。

请求必须通过 https 发送，且属性必须采用 JSON 格式。如果您使用自定义或第三方应用程序发出 API 请求，请参阅其文档，了解属性值的正确格式。

使用 curl

curl https://{subdomain}.zendesk.com/oauth/tokens \
  -H "Content-Type: application/json" \
  -d '{"grant_type": "authorization_code", "code": "{your_code}",
    "client_id": "{your_client_id}", "client_secret": "{your_client_secret}", 
    "redirect_uri": "{your_redirect_url}", "scope": "read" }' \
  -X POST

响应范例

Status: 200 OK

{
  "access_token": "gErypPlm4dOVgGRvA1ZzMH5MQ3nLo8bo",
  "token_type": "bearer",
  "scope":"read"
}

步骤 4：在 API 调用中使用访问密钥

应用可使用访问密钥进行 API 调用。在请求的 HTTP 授权标头中包含密钥，如下所示：

Authorization: Bearer {a_valid_access_token}

例如，一个列出工单的 curl 请求将如下所示：

curl https://{subdomain}.zendesk.com/api/v2/tickets.json \
  -H "Authorization: Bearer gErypPlm4dOVgGRvA1ZzMH5MQ3nLo8bo"