您可使用 OAuth 2 对您的应用程序向 Zendesk 发送的所有 API 请求进行身份验证。OAuth 为您的应用程序提供了一种访问 Zendesk 数据的安全方式,而无需存储和使用 Zendesk 用户的密码,密码属于敏感信息。
要使用 OAuth 身份验证,您需要向 Zendesk 注册您的应用程序。您还需要在您的应用程序中添加一些功能,以支持 OAuth 授权工作流程。
本文章涵盖以下主题:
相关主题
- 有关构建实现 OAuth 授权工作流程的 Web 应用程序的教程,请参阅构建 OAuth Web 应用程序。
- 要在 Zendesk 应用中实现 OAuth 授权流程,请参阅在 Support 应用中添加第三方 OAuth。
- 如果您不需要用户授予您的应用程序对其帐户的访问权限,您仍然可以使用 OAuth 密钥对 API 请求进行身份验证。请参阅通过 API 创建和使用 OAuth 令牌。
使用 Zendesk 注册应用程序
您必须注册应用程序以生成 OAuth 凭证,您的应用程序可使用该凭证对 Zendesk 的 API 调用进行身份验证。
注册应用程序的步骤
- 在管理中心,单击侧栏中的应用和整合 (),然后选择 API > Zendesk API。
- 单击 Zendesk API 页面上的 OAuth 客户端选项卡,然后单击 OAuth 客户端列表右侧的添加 OAuth 客户端。
- 填写以下字段以创建客户端:
- 客户端名称——为您的应用输入一个名称。这是当用户被询问是否授予应用程序访问权限,以及当他们查看可访问其 Zendesk 的第三方应用列表时看到的名称。
- 描述(选填)。这是对您的应用的简短描述,当用户被询问是否授予访问权限时,将会看到该描述。
- 公司(选填)。这是当用户被询问是否授予应用程序访问权限时看到的公司名称。此信息可帮助他们了解正在向谁授予访问权限。
- 徽标(选填)。这是当用户被询问是否授予应用程序访问权限时看到的徽标。图像可以是 JPG、GIF 或 PNG。为获得最佳效果,请上传方形图像。系统将针对授权页面调整图像大小。
- 唯一标识符——此字段将使用您为应用输入的名称的重新格式化版本自动填充。您可以根据需要进行更改。
- 客户端类型 - 公共或机密。公共 OAuth 客户端是在无法安全存储凭证的环境中运行的应用程序,例如移动和网络应用。这些客户端必须使用 PKCE。机密 OAuth 客户端在安全服务器上运行,其凭证可妥善保存。这些客户端可以使用 PKCE 和/或客户端密钥。请参阅 OAuth 客户端类型。
- 重定向 URL——输入 Zendesk 应该用于发送用户决定以授予您应用程序访问权限的 URL。URL 必须是绝对的而不是相对的,https(除非是本地主机或 127.0.0.1),并且用新建行隔开。
- 单击保存。
页面刷新后,下方会出现一个新的预填充密钥字段。这是 OAuth2 规范中指定的“client_secret”值。
- 将密钥值复制到剪贴板并保存在安全的地方。注意:字符可能超出文本框的宽度,因此请确保在复制前选择所有内容。重要提示:出于安全的原因,您的密钥仅完整显示一次。单击保存后,您将只能访问前九个字符。
- 单击保存。
按以下主题中所述,在您的应用程序中使用唯一标识符和密钥值。
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
属性。
kind
属性更改为 public
,则必须先实施 PKCE。否则将导致客户端无法工作,因为此时需要立即提供 PKCE。设置 kind
属性对于在管理中心创建的所有新 OAuth 客户端是必须的。而 kind
属性对于使用 api/v2/oauth/clients endpoint
创建的 OAuth 客户端而言不是必须的,但 Zendesk 建议设置此属性。
在您的应用程序中实施 OAuth 授权工作流程
Zendesk 支持授权代码授权工作流程以获取访问密钥。此流程称为授权代码授予工作流程,因为您必须先获取授权代码,然后才能请求访问密钥。其他授权工作流程已停用。
此工作流程不使用刷新密钥。访问密钥不会过期。
要实施授权代码授予工作流程,您需要将以下功能添加到您的应用程序:
有关构建实现 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
在请求中包含以下必要参数:
- 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 值。
请求必须通过 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"