文档 API参考

为Support SDK构建专用的JWT端点

本文适用于负责在组织中实现JWT服务的团队。描述了如何构建一个JWT端点来使用支持SDK移动应用在Zendesk Support中认证用户。亚博

当集成Support SDK在移动应用程序中，SDK可以在Zendesk Support中配置为验证应用程序用户。亚博如果选择此选项，Zendesk需要调用您的组织提供的亚博自定义端点来验证用户。

您的专用自定义端点必须接受唯一的安全令牌并返回JWT。亚博Zendesk将向终端发送由移动应用程序提供的唯一安全令牌。反过来，您的服务应该查找令牌，确认用户是已知和可信的，并使用JWT有效负载进行响应。基本上，我们交换的是后端服务器能理解的JWT和Zendesk能理解的JWT。亚博

请注意:客户端提供令牌，但实际的JWT挑战和响应发生在后端服务器之间。不要在客户端SDK代码中放置JWT。这是不支持的，您可能会遇到意想不到的结果。

用于实现JWT服务的库可用于大多数现代语言。亚博Zendesk Support提供了许多JWT端点代码示例Github上的不同堆栈。虽然是为SSO登录而设计的，但是您可以使用包含JWT有效负载的HTTP响应替换和重构示例中的登录重定向。

安全令牌是由移动应用程序提供给Zendesk的。亚博移动应用程序的开发人员负责提供自定义端点支持的标识符值。安全令牌为字符串形式，没有格式限制。

构建端点

在从您组织的移动应用程序中获得唯一的令牌后，Zendesk支持服务将以请求的形式将其发送到您的专用JWT端点。亚博Zend亚博esk支持服务将期望一个包含JWT令牌的响应，以确认用户是已知和可信的。请参阅下面的请求和响应格式。

您组亚博织中的Zendesk Support管理员应该为您提供用于签署JWT令牌的共享秘密。看到JSON web令牌响应在下面。

构建端点之后，向Support管理员提供端点URL。管理员需要在Support账户中获取URL来完成SDK的配置。

如果管理员不确定将URL添加到何处，则应在JWT URL字段在安装页面渠道>经典>移动SDK在管理中心。JWT应该选择作为验证方法来查看字段。

下面是身份验证流程(扩大)：

请求格式

Zend亚博esk支持服务将做出一个帖子向JWT端点发送如下格式的请求:

             

              
帖子｛your_service_uri｝user_token＝｛secure_token_provided_by_the_app｝

响应格式

Zend亚博esk支持服务期望以下响应格式:

             

              
200好吧｛“jwt”：“{your_jwt_token_response}”｝

如果Zendesk Support服务发送到JW亚博T端点的安全令牌是未知或不受信任的，则aHTTP 401未经授权响应应该返回给Zendesk支持服务。亚博

JSON web令牌响应

Ze亚博ndesk支持管理员应该为您提供共享秘密。如果没有，请管理员参考设置SDK在Zendes亚博k支持帮助中心。使用secret为JWS签名生成加密字符串。

请注意:你必须使用HMAC与sha - 256(HS256)签名算法。不支持RS256 (SHA-256)算法的RSA签名。

需要以下令牌属性:

  • 的名字
  • 电子邮件
  • jti
  • iat

注:

  • 如果任何属性缺失或为空，JWT将被拒绝
  • 键必须小写
  • 的电子邮件而且的名字在Zendesk支持中，值是区分大小写的亚博
  • iat一定是以秒为单位的整数

对JWT实现进行故障排除

如果您的JWT实现没有按预期工作，请尝试以下故障排除步骤:

确保您没有使用SSO JWT

Support SDK JWT与Zendesk Support SSO JWT亚博不一样。您必须为Support SDK构建一个专用的JWT端点，如上所述。如果你使用JWT图书馆要生成JWT令牌，请确保将登录重定向替换为HTTP响应。

在Zendesk Support中检查应用程序设置亚博

您需要以Zendesk Support管理员身份登亚博录，或请您所在组织中的Zendesk Support管理员在管理中心为您检查应用程序设置。

  1. 在管理中心，按渠道图标()，然后选择经典>移动SDK．

  2. 检查以下设置:

    注:

    • 身份验证方法一定是JWT
    • JWT URL是必须专门为移动SDK构建的端点。它不是您的Zendesk S亚博upport SSO JWT端点(如果您的组织有一个)
    • JWT秘密是一个秘密，您的服务使用它来签署它发送给Zendesk支持服务的JWT令牌。亚博这个秘密只会在应用程序设置好后完整地显示一次。确保你不用修改过的版本

检查初始化代码

在应用程序代码中，确保设置了标识后初始化代码。例子:

             

              
亚博．初始化（appId：“1 e41a02a5f85d58e009ed4fa”，clientId：“mobile_sdk_client_e1c4e6262f1d02f43496”，亚博zendeskUrl：“https://omniwear.亚博zendesk.com”）；让令牌＝身份．createJwt（令牌：“unique_db_user_identifier”）亚博．实例?。setIdentity（令牌）

测试JWT端点

使用curl向端点发出请求。您需要一个有效的令牌。例如，如果端点是https://example.com/services/jwt令牌是BD2F35A7621，使用以下curl语句:

             

              
旋度“https://example.com/services/jwt”-d“user_token = BD2F35A7621”-v-X帖子

Zend亚博esk支持服务期望从您的服务中得到非常具体的响应，并且对此非常严格。答复必须:

  • 如果成功，则返回200响应代码，没有异常。重定向将不会被遵循
  • 返回一个JWT有效负载
  • 使用HS256算法对共享密钥进行签名

示例响应:

为了清晰起见，JWT令牌值应该如下所示:

             

              
｛“jwt”：“eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9．eyJlbWFpbCI6ImJjYXJyb2xsQHplbmRlc2suY29tIiwibmFtZSI6ImJjYXJyb2xsIiwicGhvbmUiOiI5ODc2NTQzMjM0NTY3ODkiLCJ0YWdzIjpbImZyZWVfcGxheWVyIiwiYmlnX2Zpc2giXSwicm9sZSI6InVzZXIiLCJpYXQiOjE0NDkzNTUxNjIsImp0aSI6IjIxMTUyMzc5MDcyMDg5MzEyMjc不．b_0rr6_1MWrmKEzqMfvf_DI4dPPMSmDjKh_M6STIIas”｝

如果您的服务返回类似JWT令牌和200响应代码的内容，那么就应该检查有效负载本身。

请注意: curl识别某些证书链可用于建立安全连接。如果对远程测试服务器的curl请求返回错误，例如“SSL证书问题:无效的证书链”或“没有替代证书主题名称与目标主机名匹配”，请尝试添加——不安全curl命令的选项。此选项允许curl继续执行和操作，即使是在其他情况下被认为不安全的服务器连接。您负责确保任何生产环境SSL配置都是正确的。仅在可信的测试环境中使用此选项。

验证JWT有效负载

将curl请求中的JWT令牌粘贴到解码器中https://jwt.io．确保为解码器选择了HS256算法。一旦粘贴令牌，解码后的数据就会出现在右侧。

解码后的有效载荷数据必须包含以下属性:

  • 的名字
  • 电子邮件
  • jti
  • iat

如果任何属性缺失或为空，JWT将被拒绝。

键必须小写。

iat一定是个以秒为单位的整数。

其他的都是可选的。

例子:

验证共享密钥

JWT依靠共享秘密来验证JWT有效负载。确保你的JWT服务中的秘密超过9个字符。

您组亚博织中的Zendesk Support管理员可能为您提供了一个9个字符的秘密。这是在Zendesk支持管理界面中显示的秘密的修订版本。亚博请您的Zendes亚博k支持管理员在Zendesk支持的应用程序设置中重新生成秘密，然后用新的秘密更新您的JWT服务。

检查SSL证书

亚博如果SSL证书有问题，Zendesk将不会连接到JWT端点。您可以通过运行以下命令来检查这一点，其中example.com是您端点的域:

             

              
openssl s_client-连接示例．com：443

如果输出如下所示，这意味着链中的某些证书验证失败:

             

              
深度＝0/欧＝域控制验证/欧＝免费的SSL/CN＝例子．com验证错误：全国矿工工会＝20.：无法得到本地发行人证书验证返回：1深度＝0/欧＝域控制验证/欧＝免费的SSL/CN＝例子．com验证错误：全国矿工工会＝27：证书不受信任验证返回：1深度＝0/欧＝域控制验证/欧＝免费的SSL/CN＝例子．com验证错误：全国矿工工会＝21：无法验证第一个证书验证返回：1