英语(美国)
  1. 亚博Zendesk帮助
  2. 支持
  3. 使用支持票务系统亚博
  4. 安全性和用户访问在Zendesk支持亚博

对应用程序使用OAuth身份验证

查尔斯Nadeau
  • 编辑
亚博Zendesk文档团队

套件中所有”class=所有计划”class=

快速路径: “管理中心>应用和集成> api > Zendesk api”亚博

你可以用OAuth 2向Zendesk验证所有应用程序的API请求。亚博OAuth为您的应用程序提供了一种安全的方式来访问Zendesk数据，而不必存储和使用Zendesk用户的密码，这是敏亚博感信息。

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

本文涉及的主题:

相关主题:

在Zendesk上注册应用程序亚博

您必须注册您的应用程序以生成OAuth凭据，您的应用程序可以使用这些凭据来验证对Zendesk的API调用。亚博

注意:本节介绍如何为一个Zendesk帐户的用户设置OAuth客户端。亚博如果您的应用程序不仅与一个Zendesk帐户交互，而且与许多帐户交互，您可以请求一个亚博全球OAuth客户机。全局OAuth客户端是使用多个Zendesk实例进行API身份验证的一种安全、简洁的方式。亚博有关更多信息，请参见设置一个全局OAuth客户端。

登记你的申请

  1. 在管理中心，点击应用程序和集成图标()，然后选择api > Z亚博endesk api．
  2. 单击OAuth客户选项卡，然后单击亚博添加OAuth客户端在OAuth客户端列表的右侧。
  3. 填写以下字段创建客户端:
    • 客户端名称-为您的应用程序输入一个名称。这是用户在被要求授予对您的应用程序的访问权限时，以及当他们检查有权访问其Zendesk的第三方应用程序列表时将看到的名称。亚博
    • 描述-可选的。这是你的应用程序的简短描述，用户将在被要求授予访问权限时看到它。
    • 公司-可选的。这是用户在被要求授予对应用程序的访问权限时将看到的公司名称。这些信息可以帮助他们了解他们授予谁访问权限。
    • 标志-可选的。这是用户在被要求授予对应用程序的访问权限时将看到的徽标。支持JPG、GIF和PNG格式。为了获得最佳效果，请上传方形图像。它将根据授权页调整大小。
    • 唯一标识符-该字段将自动填充为您输入的应用程序名称的重新格式化版本。如果您愿意，您可以更改它。
    • 重定向url-输入URL或多个URL, Zendesk应该使用这些UR亚博L来发送用户决定是否授予对应用程序的访问权限。url必须是绝对的，而不是相对的，https(除非localhost或127.0.0.1)，并且以换行符分隔。
  4. 点击保存．

    页面刷新后，一个新的预填充秘密Field出现在下方。属性中指定的“client_secret”值OAuth2规范．

  5. 复制秘密值保存到剪贴板，并将其保存在安全的地方。注意:字符可能会超出文本框的宽度，因此在复制之前请确保选择所有内容。
    重要的是:出于安全考虑，您的密码只完整显示一次。在点击保存，您只能访问前九个字符。
  6. 点击保存．

在应用程序中使用唯一标识符和秘密值，如下面的主题所述。

在应用程序中实现OAuth授权流

亚博Zendesk支持多种OAuth授权类型。本文描述了授权代码授予类型的详细信息。另一个流，隐式的授权类型，与第一种类似，只是它不使用授权代码。第三种选择是密码授权类型，是不需要与最终用户交互的服务器端授权类型。

授权码授予流程

此流称为授权码授予流，因为在请求访问令牌之前必须获得授权码。

流不使用刷新令牌。访问令牌没有过期。

要实现授权码授予流程，您需要在应用程序中添加以下功能:

有关构建实现OAuth授权流的web应用程序的教程，请参见构建OAuth web应用．

步骤1—将用户发送到Zendesk授权页面亚博

首先，您的应用程序必须将用户发送到Zendesk授权页面。亚博该页面要求用户授权您的应用程序代表他们访问Zendesk。亚博用户做出选择后，Zendesk将选择和其他一些信息发送回应用程亚博序。

将用户发送到Zendesk授权页面亚博

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

https://{子域名}.zendes亚博k.com/oauth/authorizations/new

在哪里{子域名}是您的Zende亚博sk子域名。您可以使用POST或GET请求。包括以下参数:

  • response_type——需要。亚博Zendesk在响应中返回一个授权码，因此请指定代码作为响应类型。例子:response_type =代码．
  • redirect_uri——需要。Zendesk应该用来发送亚博用户决定是否授予对应用程序的访问权限的URL。URL必须是绝对的而不是相对的。它还必须是安全的(https)，除非您使用localhost或127.0.0.1。
  • client_id——需要。您在Zendesk注册应用程序时获得的唯一标识符。亚博请参阅上面的部分。
  • 范围——需要。用空格分隔的作用域列表，控制对Zendesk资源的访问。亚博电脑端亚博你可以要求读，写,或模仿访问所有资源或特定资源。亚博电脑端看到设置范围．
  • 状态-用户决定是否授予访问权限后，Zendesk的响应中包含的任意字符串。亚博您可以使用该参数来防止跨站点请求伪造(CSRF)的攻击。在CSRF攻击中，最终用户被诱骗单击在web应用程序中执行操作的链接，而最终用户仍然经过身份验证。要防范这种攻击，请在状态参数，并在返回时验证它。

确保对参数进行url编码。

GET请求

https://{子域名}.zendes亚博k.com/oauth/authorizations/new ? response_type = code&redirect_uri = {your_redirect_url} client_id = {your_unique_identifier}范围=读% 20写

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

设置范围

你必须指定作用域来控制应用程序对Zendesk资源的访问。亚博电脑端亚博的读作用域允许应用访问GET端点。包括旁路加载相关资源的权限。亚博电脑端的写作用域允许应用程序访问POST、PUT和DELETE端点，以创建、更新和删除资源。亚博电脑端

有关范围的更多信息，请参见授予类型的OAuth令牌．

的模仿scope允许Zendesk管亚博理员代表最终用户发出请求。看到代表最终用户发出API请求．

例如，以下参数赋予应用程序对所有资源的读访问权限:亚博电脑端

“范围”:“读”

下面的形参提供了对所有资源的读写访问:亚博电脑端

scope:读写

您可以根据以下资源对范围进行微调:亚博电脑端

  • 票
  • 用户
  • 审计日志(只读)
  • 组织
  • hc
  • 应用程序
  • 触发器
  • 自动化
  • 目标
  • 人则
  • 子

语法如下:

“范围”:“资源:范围”

例如，下面的参数限制一个应用程序只能读取门票:

“范围”:“门票:阅读”

要赋予应用程序对资源的读写访问权限，需要同时指定两个作用域:

scope: users:读users:写

让一个应用程序只对一个资源(比如组织)有写访问权限，对其他所有资源都有读访问权限:

scope: organizations:write: read

步骤2 -处理用户的授权决策

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

如果用户决定授予对应用程序的访问权限，则重定向URL包含授权代码。例子:

{redirect_url} ?代码=7xqwtlf3rrdj8uyeb1yf

授权码的有效期为120秒。

如果用户决定不授予对应用程序的访问权限，则重定向URL包含错误和error_description通知应用程序用户拒绝访问的参数:

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

使用这些值来控制应用程序的流。如果URL包含代码参数，从Zendesk获取访问令牌，如下部分所述。亚博这是要包含在对Zendesk的API调用中的令牌。亚博

步骤3 -从Zendesk获得访问令牌亚博

如果您的应用程序从Zendesk接收到用户授予访问权限的授权码，您的应用程序可以将其交换为访问令牌。亚博要获得访问令牌，向以下端点发出POST请求:

https://{子域名}.zendes亚博k.com/oauth/tokens
注意:不要将这个端点与创建令牌OAuth令牌API中的端点。虽然两个端点都返回有效的OAuth访问令牌，但端点不共享相同的路径、JSON格式或请求参数。

在申请中包括下列必需的参数:

  • grant_type——指定“authorization_code”作为值。
  • 代码—使用用户授权后从Zendesk收到的授权码。亚博
  • client_id-在Support管理界面中使用OAuth客户端指定的唯一标识符(管理>渠道>API>OAuth客户）.看到在Zendesk上注册应用程序亚博．
  • client_secret-在Support管理界面中使用OAuth客户端中指定的secret (管理>渠道>API>OAuth客户）.看到在Zendesk上注册应用程序亚博．
  • redirect_uri-与步骤1中相同的重定向URL。只作识别用途。
  • 范围——看设置范围．.

请求必须通过https，参数必须格式化为JSON。

使用旋度

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

示例响应

状态:200 OK {"access_token": "gErypPlm4dOVgGRvA1ZzMH5MQ3nLo8bo"， "token_type": "bearer"， "scope":"read"}

步骤4 -在API调用中使用访问令牌

应用程序可以使用访问令牌进行API调用。在请求的HTTP授权头中包含令牌，如下所示:

授权:Bearer {a_valid_access_token}

例如，列出票据的curl请求如下所示:

curl https://{subdomain}.亚博zendesk.com/api/v2/tickets.json \ -H "授权:承载gErypPlm4dOVgGRvA1ZzMH5MQ3nLo8bo"

隐性拨款流程

隐式授权流类似于授权代码授权流，只是没有第3步。您请求令牌而不是授权码。换句话说，您设置的值response_type参数为"token"而不是"code"。如果最终用户授权访问，则在重定向URL中立即发送令牌。不存在用于创建令牌或设置其作用域的端点。令牌授予对所有资源的读写访问权限。亚博电脑端

示例请求

https://{子域名}.zendes亚博k.com/oauth/authorizations/new ? response_type = token&client_id = {your_unique_identifier}范围=读% 20写

示例响应

如果用户授予对应用程序的访问权限，则令牌包含在重定向URL中。

{redirect_url} # access_token = gErypPlm4dOVgGRvA1ZzMH5MQ3nLo8bo&token_type =不记名

如果用户决定不授予对应用程序的访问权限，则URL包含错误和error_description参数。

{redirect_url} #错误= access_denied&error_description = +终端用户+或+服务器+否认+ + +授权请求

密码授予类型

使用密码授予类型直接将Zendesk用户名和密码交换为访问令牌。亚博只有当您的应用程序可以获得Zendesk用户名和密码时，才应该使用这种授权类型。亚博这通常是Zendesk的高度特权应用程序。亚博应用程序不应该存储用户名和密码。它也应该对如何获得它们高度安全。

示例请求

curl https://{subdomain}.亚博zendesk.com/oauth/tokens \ -H "Content-Type: application/json" \ -d '{"grant_type": "password"， "client_id": "{your_client_id}"， "client_secret": "{your_client_secret}"， "scope": "read"， "username": "{zendesk_username}"， "password": "{zendesk_password}"}' \ -X POST

Ze亚博ndesk用户名通常是一个电子邮件地址，如agent@zendesk.com。

示例响应

状态:200 OK {"access_token": "gErypPlm4dOVgGRvA1ZzMH5MQ3nLo8bo"， "token_type": "bearer"， "scope":"read"}
    回到顶端

    43岁的评论

    • 保罗•施特劳斯

      我们最近创建了一个与Zendesk的集成，它允许我们的代理谁登录到Zendesk亚博支持访问一个内部工具。每次代理试图访问我们的工具时，我们都会收到一条消息“允许访问您的Zendesk帐户?”亚博这在我们的Zendesk沙盒帐户测试期间没有发生，但在生产中会发生。亚博关于如何使这成为一次性的“允许”，而不是每次登录时都要求它，有什么想法吗?

      0
    • 格雷格Katechis
      亚博Zendesk开发者倡导

      嗨,保罗!您能分享更多关于这个集成以及如何实现认证流的信息吗?请提供尽可能多的细节，你可以在公共论坛上分享!

      0
    • Groffer安德森

      嗨@……
      你能帮我解决一个类似的问题吗?https://support.亚博zendesk.com/hc/en-us/community/posts/1260801978190-How-to-perform-Authorization-code-grant-flow-on-Zendesk-with-Agent-when-I-have-SSO-enabled-

      0
    • 格雷格Katechis
      亚博Zendesk开发者倡导

      嗨，Raghav，我回答道在这里！

      0
    • 尼克·海明威进行

      你好，我正在尝试实现密码授予类型OAuth流，我很难理解我应该如何获得用户的用户名和密码，以便第一次请求OAuth令牌。这一节似乎暗示有一个端点可以检索我需要的用户名和密码，但是我还没有找到这个端点。任何建议吗?谢谢

      0
    • 维塔利Markitanov

      你好,

      您是否支持OIDC代理?
      我的想法是我有IDP，我的网络用户应该通过SSO与我的IDP进行身份验证。

      0
    • 杰森·谢弗
      亚博Zendesk客户服务

      你好,维塔利,

      亚博Zendesk目前不支持OpenID Connect，根据我们产品团队的说法，这目前不在我们的路线图上。很抱歉给您带来不便。

      0
    • 保罗·莫兰

      上面评论中提到的“authenticity_token”https://support.亚博zendesk.com/hc/en-us/articles/203663836/comments/360000042747对我没用。csrf_token(我可以使用v1模板api访问它)和这个authenticity_token的格式是不同的。

      0
    • 贝尔纳多里斯

      嗨。我已经按照建议实现了OAuth身份验证流，并请求了以下范围:

      “用户:写票:写组织:写身份:写读”

      一切工作如预期，除了当我试图使用Zendesk的API删除用户身份。亚博我得到以下错误:

      {"error":"Forbidden"，"description":"您缺少以下必需的作用域:write"}

      'users:write'作用域不应该让我管理用户身份吗?还是我需要一个额外的范围?看起来“身份:写”不是一个有效的选项

      1
    • 阿丽亚娜·弗朗西斯·德拉·克鲁兹

      你好,贝尔纳多,

      我想进一步研究这个，我将创建一个票给你，请期待一个电子邮件很快。

      0
    • 格雷格Katechis
      亚博Zendesk开发者倡导

      嗨Tiel !这是与Zendesk的特性有关，还是只是关于Oau亚博th的一般性问题?

      1
    • 作者Nishant古普塔

      我一直在尝试在Rest API中实现OAuth。
      请注意，我没有web应用程序(在其中我可以使用重定向URL)
      仅后端- REST api

      对于所有的oauth身份验证类型，很难确定哪一种是最好的。
      哪些curl命令可以帮助我使用oauth成功对Zendesk进行身份验证亚博

      密码授予类型是否最适合使用下面的curl命令?或者我们还有什么选择?

      curl https://{subdomain}.亚博zendesk.com/oauth/tokens \ -H "Content-Type: application/json" \ -d '{"grant_type": "password"， "client_id": "{your_client_id}"， "client_secret": "{your_client_secret}"， "scope": "read"， "username": "{zendesk_username}"， "password": "{zendesk_password}"}' \ -X POST
      0
    • 维克多Hristovski

      嗨，我正在Zendesk中为我们的开发人员生成一个OAuth令牌，但是即亚博使在简单的curl命令中，我们也得到了“未经授权”:

      旋度https://obscura.亚博zendesk.com/api/v2/users.json＼- h"授权:承载gErypPlm4dOVgGRvA1ZzMH5MQ3nLo8bo"

      {"error":"invalid_token"，"error_description":"提供的访问令牌已过期，已撤销，格式错误或因其他原因无效。"}

      我们做错了什么?

      0
    • Chinh表象

      你好,

      如何在一个API中获得完整的访问令牌?我使用javascript调用，并实现从我的网站票务形式。

      1
    • Cheeny波斯历八月
      亚博Zendesk客户服务

      嗨，Chinh Phan

      完全访问API令牌是什么意思?你能告诉我们更多关于你的用例，以便我们为你检查它吗?

      0
    • Chinh表象

      嗨，切尼·阿班。

      我通过Javascript实现从前端的联系形式，提交门票到Zendesk。亚博看起来像这样:

      当我尝试向zendesk发布一个票据时，我面临CORs问题(我亚博使用了所有令牌，在zendesk设置中)。

      Ticket的API要求授权是“Bearer”+ access_token。

      当我通过Postman: https://{subdomain}.zendesk.com/api/v2/oauth/tokens进行测试时，我认为API获得access_to亚博ken工作
      但不，当我应用API获得访问令牌javascript代码。我还面临着CORs问题。

      如果我在文档中实现:https://support.亚博zendesk.com/hc/en-us/articles/203663836?page=3#topic_ar1_mfs_qk

      当浏览器重定向到url: https://{subdomain}.zendesk.com/oauth/aut亚博horizations/new?response_type=code&redirect_uri={your_redirect_url}&client_id={your_unique_identifier}&scope=read%20write

      它迫使我必须登录到zendesk。亚博对于没有帐户的用户是不可行的。

      1
    • 奥斯卡·Omarsson

      不确定这是否是问这个问题的正确地方，但我正试图为Zendesk自动化中的限制创建一个解决方案，我需要能够在自动化更改票证时向票证添加私人评论，只是为了通知任何在自动化执行后打开票证的代理。亚博

      现在我已经使用Webhooks调用Zendesk API实现了这一点亚博

      但只有通过使用我自己的用户名，这将导致某个用户名与评论一起放置，使其看起来像我做了内部评论。

      我的愿望是让它看起来像系统，它确实在这样做，做了内部评论。

      看来我不能使用Zendesk API令牌，除非我使用自己的用户名亚博，如果我错了，请纠正我

      而且我无法使OAuth客户机令牌作为承载令牌身份验证工作。

      我错过了什么?

      致以最亲切的问候
      奥斯卡·

      0
    • 下面是泰勒•克拉克

      是否有现有的查询参数可用于在授权步骤上强制登录?目前，如果用户已经登录，它将直接进入授权屏幕。我希望强迫用户每次通过流程时都登录。
      这个用例是，我们的集成需要一个管理员，只有在检索令牌并通过ID检索经过身份验证的用户之后，我们才能弄清楚这一点

      0
    • 下面是泰勒•克拉克

      其实刚才用UI就算出来了- ' &login=true '

      0
    • 元帅

      我有一个试用帐户zendesk，我试图使用OAuth为亚博我的api请求，它返回无效令牌。如果我使用基本验证，它可以工作，但由于CORS策略，我不能为客户端应用程序使用基本验证来进行调用。我想知道我的试用账户是否可以使用OAuth ?

      0
    • Cheeny波斯历八月
      • 编辑
      亚博Zendesk客户服务
      嗨,元帅,

      是的，试用账户支持使用OAuth令牌。如果您看到无效令牌错误，我建议您再次检查我们的关于设置不同OAuth授权流的文档以确保您的请求的参数符合我们的预期令牌根据那篇文章。如果您仍然看到错误，我建议您在我们这里开一张票，这样我们就可以深入调查。
      0
    • Jishnu年代

      嗨,团队,

      我按照你的指示做了，我拿到了访问令牌。但是没有关于使用访问令牌查找经过身份验证的用户id的信息。

      你能建议我找到认证用户的详细信息吗?

      谢谢

      0
    • 格雷格Katechis
      亚博Zendesk开发者倡导

      嗨Jishnu !我们目前没有提供对底层标准(OpenID Connect)的支持，因此目前没有任何方法可以从访问令牌检索用户数据。

      0
    • 弗拉德Glazov

      你好

      有办法撤销吗全球OAuth客户吗?如果它是由离开组织的成员创建的呢?

      谢谢

      0
    • 乔纳斯·罗查·利马·阿马罗

      你好

      一个OAuth客户端可以有多个访问令牌吗?

      我跑

      https://{子域名}.zendes亚博k.com/oauth/tokens

      连续请求两次，第二个请求撤销了我的authorization_code。我怀疑这是由某种单一访问令牌每个主题策略引起的，对吗?

      谢谢你！

      0
    • 丹麦人
      亚博Zendesk工程
      你好弗拉德,

      可以使用端点撤销它撤销令牌．

      @Jonas,

      事实证明，不允许使用多个访问令牌。因此，您所经历的行为是意料之中的。
      0
    • 弗拉德Glazov

      嗨,丹麦人,

      谢谢你的回答，撤销令牌似乎很清楚。

      现在如何撤销(或删除/禁用/任何)OAuth客户端？

      谢谢,弗拉德。

      0
    • 丹麦人
      亚博Zendesk工程
      你好弗拉德,

      你可以用:删除客户端 

      删除/ api / v2 / oauth /客户/ {oauth_client_id}
      0
    • 塞萨尔麦

      嗨,支持,

      我尝试了“授权代码授予流程”，它很好地获得访问令牌(用于列出门票)，但该流程不适合我的应用程序。

      所以我尝试使用“密码授予类型”流程。我的帐户(xyz@abc.com)是“用户”而不是“管理员”。他们的组织启用了2FA。在尝试POST Api时，我得到了下面的错误。

      2FA是这种情况的阻碍因素吗?

      {
      “错误”:“invalid_grant”,
      "error_description": "提供的访问授权无效、过期或已撤销(例如无效的断言、过期的授权令牌、错误的最终用户密码凭据或不匹配的授权代码和重定向URI)。"
      }
      0
    • 格雷格Katechis
      亚博Zendesk开发者倡导

      嗨塞萨尔!2FA和OAuth应该不是问题。你是否确认这个问题不是回复中提供的(相关)错误之一?

      0

    请登录留下评论。

    相关文章

    由Zendesk提供支亚博持