您可使用 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 客户端凭证授权类型
OAuth 客户端凭证授权类型仅适用于机密客户端，允许您仅使用特定客户端的密钥创建 OAuth 密钥。要使用此工作流程，请使用 grant_type: client_credentials 传递有效的 client_secret 参数到 /oauth/tokens 端点以生成新的 OAuth 访问密钥。与其他授权流程不同，此授权类型不会返回刷新密钥，也不需要用户授权。出于安全的原因，不允许公开客户端使用此授权类型。有关更多信息，请参阅 OAuth 客户端。
在您的应用程序中实施 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%20writeZendesk 授权页面将在终端用户的浏览器中打开。用户做出决定后，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"
63 条评论
登录再写评论。