启用 JWT 单点登录

我的服务模式是什么？

快速查看：管理中心 > 帐户 > 安全 > 单点登录

单点登录机制允许您对系统中用户进行身份验证，并随后告知 Zendesk 该用户是否已通过身份验证。如果您使用 JSON 网络密钥 (JWT) 单点登录，则在用户登录时，系统会自动使用身份提供者对其进行身份验证，然后允许通过验证的用户访问 Zendesk，而不会提示其输入单独的登录凭证。

Zendesk 管理员可以启用 SSO 选项。本文章介绍了如何启用多个 JWT 单点登录配置，用于对团队成员（管理员和专员，包括低权限专员和参与者）和/或终端用户进行身份验证。

单点登录的核心是一种安全机制，让 Zendesk 可以信任从您的系统发出的登录请求。Zendesk 仅授权已通过您身份验证的用户访问。Zendesk SSO 依靠 JWT 确保用户身份验证数据的交换安全。

重要提示：您在使用基于 JWT 或 SAML 的 SSO 时应验证用户身份（包括其电邮地址）。否则，您的帐户就面临未经授权访问的风险，且 Zendesk 无法保证您的帐户安全。

本文章包含以下部分：

• Zendesk 的 JWT SSO 如何工作
• 启用 JWT SSO 的要求
• 启用 JWT SSO
• 将 JWT SSO 分配给用户
• 启用 JWT SSO 后管理 Zendesk 中的用户
• 生成新的共享密钥
• 切换身份验证方法
• 关于 JWT 的其他信息

公司的 IT 团队通常负责设置和管理公司的 JWT 身份验证系统。他们的任务是在系统上实施 Zendesk 的 SSO。建议团队参考本文章中以下主题：

• 技术实施工作表

相关文章：

• Zendesk 中的单点登录 (SSO) 选项
• 为用户提供登录 Zendesk 的不同方式
• SSO 服务不可用时访问 Zendesk 帐户

Zendesk 的 JWT SSO 如何工作

启用 SSO 后，登录请求将转接到 Zendesk Support 外部登录页面。

JWT SSO 身份验证流程步骤：

1. 假设一个未经身份验证的用户导航到您的 Zendesk Support URL，例如：https://yoursubdomain.zendesk.com/。
2. Zendesk SSO 机制识别 SSO 是否已启用，以及用户是否已通过身份验证。
3. Zendesk 会尝试确定未经身份验证的用户是终端用户还是团队成员，并将用户重定向到您组织的相应远程登录页面。例如：https://mycompany.com/zendesk/sso。
4. 远程服务器上的脚本使用您组织的专有登录过程对用户进行身份验证。
5. 身份验证系统建立一个包含相关用户数据的 JWT 请求。
6. 身份验证系统将用户重定向到以下带有 JWT 有效载荷的 Zendesk 端点：

   https://yoursubdomain.zendesk.com/access/jwt

7. Zendesk 会验证密钥，然后从 JWT 有效载荷解析用户详情，并授予用户会话权限。

由此可见，此流程依赖于浏览器重定向和使用 JWT 传递签名消息。重定向完全在浏览器中进行，且 Zendesk 和您的系统之间没有直接连接，因此您可以依靠公司防火墙保管身份验证脚本。

启用 JWT SSO 的要求

与您公司负责 JWT 身份验证系统的团队（通常是 IT 团队）沟通，确保 Zendesk 绑定的流量通过 HTTPS 而不是 HTTP 传输。

在 Zendesk 中配置 JWT SSO 方法需要以下信息。您的 IT 团队可以为您提供这些信息。

• Zendesk 用户尝试访问 Zendesk 时应重定向到的远程登录 URL
• （可选）Zendesk 在用户退出后将重定向到的远程退出 URL
• （可选）将用户重定向到相关登录选项的 IP 范围列表。从指定 IP 范围发出请求的用户将转接到远程 JWT 身份验证登录表格。从该范围外的 IP 地址发出请求的用户将转接到常规的 Zendesk 登录表格。如果您不指定范围，所有用户都将重定向到远程身份验证登录表格。

IT 团队可能需要来自 Zendesk 的更多信息以配置 JWT 实施。建议他们参考本文章中的技术实施工作表。

确认满足要求并拥有所有必要信息后就可以启用 JWT SSO 了。

启用 JWT SSO

管理员可以仅对终端用户或团队成员（包括低权限专员和参与者）或这两个组启用 JWT 单点登录。您可以创建多个 JWT SSO 配置。在开始之前，请从您公司的 IT 团队获取所需的信息。请参阅启用 JWT SSO 的要求。

启用 JWT 单点登录

1. 在管理中心，单击侧栏中的帐户图标 ()，然后选择安全 > 单点登录。
2. 单击创建 SSO 配置，然后选择 JSON 网络密钥。
3. 输入唯一的配置名称。
4. 对于远程登录 URL，输入用户尝试访问您的 Zendesk URL 时应重定向到的 URL。

   Zendesk 会自动将参数 brand_id 添加到 URL。该参数是用户尝试登录时使用的 Zendesk Support 品牌。

5. （可选）对于远程退出 URL，输入用户退出 Zendesk 后应重定向到的退出 URL。

   Zendesk 会自动将参数 email、external_id 和 brand_id 添加到退出 URL 中。如果您不希望 URL 中含有电邮和外部 ID 信息，请指定退出 URL 中的空白参数，例如：

   https://www.xyz.com/user/signout/?email=&external_id=

   注意：如果您使用的是 Ember.js 应用程序，必须修改退出 URL 才能在哈希值之前使用空白参数，例如，https://somedomain.com/?brand_id=&return_to=&email=#/zendesk-login/。
6. （可选）对于 IP 范围，如果您想将用户重定向到相关登录选项，请输入 IP 范围列表。

   从指定 IP 范围发出请求的用户将转接到 JWT 身份验证登录表格。从该范围外的 IP 地址发出请求的用户将转接到常规的 Zendesk 登录表格。如果您希望将所有用户重定向到 JWT 身份验证登录表格，请勿指定范围。

7. 如果您对用户使用外部 ID，可对更新外部 ID？选择开启以在 Zendesk Support 中更新这些 ID。
8. 向您的 IT 团队提供共享密钥，以便他们进行 JWT 实施。
   重要提示：请妥善保管共享密钥，一旦泄露，您的 Support 帐户中所有数据都将面临风险。
9. 选择在用户登录时显示按钮，为 Zendesk 登录页面添加用 SSO 继续按钮。

   在按钮名称字段中输入值可以自定义按钮标签。如果您为登录页面添加了多个 SSO 按钮，自定义按钮标签会很有用。有关更多信息，请参阅为 Zendesk 登录页面添加“用 SSO 继续”按钮。

10. 单击保存。

默认情况下，企业 SSO 配置是非活跃的。您必须将 SSO 配置分配给用户才能将其激活。

将 JWT SSO 分配给用户

创建 JWT SSO 配置后，必须将其分配给终端用户和/或团队成员才能将其激活。

将 SSO 配置分配给团队成员或终端用户

1. 打开团队成员或终端用户的安全设置。
   • 在管理中心，单击侧栏中的帐户图标 ()，然后选择安全 > 团队成员身份验证。
   • 在管理中心，单击侧栏中的帐户 ()，然后选择安全 > 终端用户身份验证。
2. 选择外部身份验证以显示身份验证选项。
3. 选择您要使用的 SSO 配置名称。

   单点登录可能无法涵盖所有用例，因此 Zendesk 身份验证默认保持活跃状态。

4. 选择允许用户登录的方式。

   

   让他们选择允许用户使用任何活跃的身份验证方法登录。请参阅为用户提供登录 Zendesk 的不同方式。

   重定向到 SSO 仅允许用户使用主要 SSO 配置进行身份验证。用户不会看到其他登录选项，即使这些身份验证选项是活跃的。如果您选择重定向到 SSO，随即将显示主要 SSO 字段，供您选择主要 SSO 配置。

5. 单击保存。

启用 JWT SSO 后管理 Zendesk 中的用户

在 Zendesk 中启用 JWT 单点登录后，在 Zendesk 外部对用户所作更改不会自动同步到 Zendesk 帐户。用户在进行身份验证时，其信息会在 Zendesk 中更新。例如，如果将用户添加到您的内部系统，则该用户在登录 Zendesk 时将添加到您的 Zendesk 帐户。如果将用户从内部系统中删除，该用户将无法再登录 Zendesk。但其帐户仍将保存在 Zendesk 中。

默认情况下，启用单点登录时，Zendesk 中存储的唯一用户数据是用户的名称和电邮地址。Zendesk 不存储密码。因此，您应关闭来自 Zendesk 的所有关于密码的自动电邮通知。

为提供更好的客户体验，您可能希望在 Zendesk 中不仅存储用户的名称和电邮地址。您可以使用其他 JWT 属性来达到此目的。

关闭来自 Zendesk 的密码通知电邮

对于任何通过 SAML、JWT 或 OpenID Connect (OIDC) 单点登录访问您 Zendesk 帐户的新用户，都会创建 Zendesk 用户个人资料。用户是使用非 Zendesk 密码通过 IdP 进行身份验证，不需要直接登录 Zendesk，因此创建个人资料时没有密码。

新用户通过 SSO 登录 Zendesk 并通过 IdP 进行身份验证，因此他们不会收到验证帐户的电邮通知。但是，仍建议关闭这些自动电邮通知，以防其在 IdP 未成功验证用户时发送。使用 SSO 时，务必通过 IdP 进行用户验证。

关闭密码通知电邮

1. 在管理中心，单击侧栏中的人员 ()，然后选择配置 > 终端用户。
2. 在帐户电邮部分，取消选择专员或管理员创建新用户时也发送欢迎电邮。
3. 在允许用户更改密码中，取消选择此选项。

生成新的共享密钥

在某些情况下（例如您的密钥已泄露），您可能需要颁发新的 JWT 共享密钥，并将其提供给 IT 团队或外部身份提供者。您可以从 Zendesk 管理中心生成新的 JWT 共享密钥。此操作将创建新密钥，并使旧密钥失效。您需要向 IT 团队或外部身份提供者通知新的共享密钥，以保持 Zendesk SSO 帐户身份验证正常工作。

重要提示：在新密钥到位之前，用户无法使用 JWT SSO 进行身份验证。请确保用户在此期间有备用身份验证方法。

生成新的共享密钥

1. 在管理中心，单击侧栏中的帐户图标 ()，然后选择安全 > 单点登录。
2. 将鼠标悬停在要创建新共享密钥的 JWT 配置上，单击选项菜单图标 ()，然后选择编辑。
3. 滚动至配置页面底部的共享密钥，然后单击重置密钥。

   

   随即出现一条确认消息。

   

4. 单击重置密钥以确认重置。

   您应会看到一个新的纯文本共享密钥。

   

5. 单击复制以制作新共享密钥的副本，并将其提供给您的 IT 团队或外部身份提供者。
6. 保存更改。

切换身份验证方法

如果您使用第三方 SSO 方法在 Zendesk 中创建用户并对用户进行身份验证，然后切换到 Zendesk 身份验证，这些用户将没有密码可用于登录。要获得访问权限，用户可在 Zendesk 登录页面重置密码。

关于 JWT 的其他信息

JWT 是国际标准机构 IETF 推行的一种开放标准，拥有 Microsoft、Facebook 和 Google 等科技行业顶级支持者。

JWT 是一种相当简单的规范，其基本组成部分非常好理解（详见 http://tools.ietf.org/html/draft-jones-json-web-token-10）。JWT 规范有很多开源实施，涵盖大多数现代技术。这意味着您可以轻松设置 JWT 单点登录。

需要注意的是，JWT 有效载荷仅经过编码和签名，并未加密，因此请勿在哈希表格中放置任何敏感数据。JWT 工作时首先将传输的 JSON 序列化为字符串（Base64 编码字符串），然后再根据共享密钥生成 Base64 字符串的 HMAC，从而生成一个可供收件人用于验证用户身份的签名。

技术实施工作表

本部分介绍了 Zendesk JWT SSO 实施相关详情，适用于公司中负责 JWT 身份验证系统的团队。

注意：如果您从较早版本的 Zendesk SSO（称为 Zendesk 远程身份验证）升级到 JWT，就可以同时启用多个 SSO 实施。Zendesk 可识别请求是发送给 JWT 还是其他类型的 SSO，并相应处理请求。这意味着您可以先启用并测试 JWT，然后再停用以前的 SSO 实施。

涵盖的主题：

• JWT 算法
• Zendesk JWT 端点
• JWT 属性
• 远程登录 URL 参数 (return_to)
• 错误处理
• 表格提交示例
• JWT 生成示例

JWT 算法

在 JWT 有效载荷的页首中指定 HS256 为 JWT 算法：

{
  "typ":"JWT",
  "alg":"HS256"
}

HS256 即 HMAC SHA 256，是美国国家安全局设计的一种 256 位加密算法。

注意：Zendesk 不支持 RS256 和 ES256 JWT 算法。

Zendesk JWT 端点

成功对用户进行身份验证后，创建 JWT 有效载荷，并将包含 JWT 有效载荷的 POST 请求提交到以下 Zendesk 端点：

https://yoursubdomain.zendesk.com/access/jwt

有效载荷必须是 base64 编码的，并通过客户端提交的表格提交。无法提交包含客户端 AJAX、Fetch 或 Axios 请求的有效载荷，因为请求将被客户端的同源政策阻止。同样，也无法从您的服务器发出 POST 请求，因为它无法正确设置用于在用户浏览器上进行身份验证的 Cookie。

JWT 有效载荷必须使用 https 协议发送到您的 Zendesk Support 子域名，例如：

https://yoursubdomain.zendesk.com/access/jwt

不支持主机映射子域名。

JWT 属性

使用哈希 (Ruby) 或字典 (Python) 发送 JWT 属性。JWT 必须为 Base64 编码，例如（使用 Ruby）：

payload = JWT.encode({
   :email => "[e-mail]", :name => "Bob", :iat => Time.now.to_i, :jti => rand(2<<64).to_s
}, "Our shared secret")

Zendesk 需要一个电邮地址来唯一标识用户。除下表列出的必要属性外，您还可以选择发送其他用户个人资料数据。此类数据会在您的用户管理系统和 Zendesk Support 之间同步。

必要属性

属性	数据类型	描述
iat	数字日期	即 Issued At密钥的生成时间，用于确保提供的密钥在生成后不久即可用。该值必须是 UNIX 时间戳格式的秒数。Zendesk 允许最多三分钟的时钟偏差，因此请务必在您的服务器上配置 NTP 或类似功能。
jti	字符串	JSON 网络密钥 ID。该密钥的唯一 ID，供 Zendesk 用于防止密钥重放攻击。
email	字符串	登录用户的电邮，用于在 Zendesk Support 中唯一标识用户记录。
name	字符串	用户的名称。Zendesk Support 中的用户将据此名称创建或更新。

可选用户属性

属性	数据类型	描述
external_id	字符串	如果您的用户不是由电邮地址唯一标识，且其电邮地址可能会更改，请从您的系统发送唯一 ID。并将该 ID 指定为字符串。
locale（用于终端用户） locale_id（用于专员）	整数	Zendesk Support 中的区域设置，指定为数字。
organization	字符串	要添加用户的组织的名称。 如已启用允许用户属于多个组织选项，其他组织将附加在原始组织后面，并视为辅助组织。这不会删除现有成员资格。 如果您想同时传递多个组织，请使用 organizations 属性。组织名称必须以字符串的形式传递，并用逗号分隔。
organization_id	整数	Zendesk API 中组织的外部 ID。如果同时提供了 organization 和 organization_id，则前者将被忽略。 如已启用允许用户属于多个组织选项，其他组织将附加在原始组织后面，并视为辅助组织。这不会删除现有成员资格。 如果您想同时传递多个组织 ID，请使用 organization_ids 属性。组织 ID 必须以字符串的形式传递，并用逗号分隔。
phone	字符串	电话号码，指定为字符串。 电话号码应符合 E.164 国际电话号码服务模式。示例：[phone]。 E164 号码是带有国家/地区拨号前缀的国际号码，通常是区号和订阅者号码。有效的 E.164 电话号码必须包含国家/地区呼叫代码。
tags	数组	要在用户上设置的一系列 JSON 标签。这些标签将替换用户个人资料中可能存在的任何其他标签。
remote_photo_url	字符串	要在用户个人资料上设置的照片 URL。
role	字符串	用户角色，此值可设置为 end_user、agent 或 admin。默认为 end_user。如果用户角色与 Zendesk Support 中的用户角色不同，则该用户角色将在 Zendesk Support 中更改。
custom_role_id	整数	仅当用户的角色是专员时适用。
user_fields	对象	要在用户上设置的自定义用户字段键和字段值的 JSON 哈希值。必须有自定义用户字段，以便设置字段值。每个自定义用户字段都由用户字段管理员设置中相应字段键标识。日期值格式为 yyyy-mm-dd。 如果自定义用户字段键或字段值无效，更新该字段将静默失败，但用户仍可成功登录。有关自定义用户字段的更多信息，请参阅添加自定义字段到用户。 注意：在 user_fields 属性中发送空值将移除相应字段中所有现有值。

远程登录 URL 参数 (return_to)

您可以选择是否传入 return_to 参数，但我们建议传入该参数以便获得最佳用户体验。当 Zendesk 将用户重定向到您的远程登录页面时，还会传递 return_to URL 参数。该参数包含 Zendesk 在您的系统对用户进行身份验证后将返回的页面。将该参数名称和值附加到 Zendesk JWT 端点后面。

例如，假设已退出的专员单击以下链接以在 Support 中打开工单：https://mycompany.zendesk.com/tickets/1232。具体工作流程如下：

1. 单击后，Zendesk 将用户重定向到您的远程登录 URL，并将以下 return_to 参数附加到 URL 后面： 

   https://mycompany.com/zendesk/sso?return_to=https://mycompany.zendesk.com/tickets/123

2. 您的身份验证系统将从 URL 中获取 return_to 参数，并在成功对用户进行身份验证后将其附加到 Zendesk JWT 端点后面，或添加到请求正文。例如：

   https://mycompany.zendesk.com/access/jwt?&return_to=https://mycompany.zendesk.com/tickets/123

3. Zendesk 使用该参数打开专员的工单页面。

return_to 参数是专员界面的绝对 URL，也是帮助中心的相对 URL。

注意：如果您的 return_to 地址含有其自己的 URL 参数，请确保您的脚本在提交 JWT 密钥时对整个 return_to 值进行 URI 编码。

错误处理

如果 Zendesk 在处理 JWT 登录请求时遇到错误，会发送消息说明该问题。如果您在配置 JWT 整合时指定了远程退出 URL，则 Zendesk 会重定向到该 URL，并传递消息和类型参数。如果该类型参数的值一直是“error”，则表示发生了错误。建议指定一个远程退出 URL，并在类型旁记录来自 Zendesk 的消息。您将需要修复大多数潜在错误，例如时钟偏移、达到速率限制、密钥无效。

表格提交示例

JWT 有效负载必须使用表格提交从浏览器提交到以下 Zendesk 端点：

https://yoursubdomain.zendesk.com/access/jwt

Zendesk 在 GitHub 的 Zendesk JWT SSO 存储库中提供了各种技术堆栈的一系列示例。您必须使用表格提交从浏览器提交 JWT 有效负载，以确保可在浏览器上正确设置 Cookie，且请求不会被 CORS 阻止。

请参阅以下表格提交示例：

• JavaScript 示例
• jQuery 示例
• Rails 示例
• React 示例

响应

响应应为 HTML，带有 200 OK 状态。响应格式如下：

<html><body>You are being <a href="">redirected</a>.</body></html>

如果 href 匹配您的 return_to 值，则用户已成功通过身份验证，应设置 cookie。如果 href 开头为 https://SUBDOMAIN.zendesk.com/access/unauthenticated，则 Zendesk 无法对用户进行身份验证。

JWT 生成示例

JWT 编码简单易懂，在大多数现代语言中都有其支持库。Zendesk 在 JWT SSO GitHub 存储库中提供了各种堆栈的一系列示例：

• https://github.com/zendesk/zendesk_jwt_sso_examples/tree/master/jwt_generation

JWT 生成代码用于您的服务器实施。您可以将生成的 JWT 传回登录页面，然后从浏览器启动表格提交。

如果您在任何其他堆栈中实施 JWT，我们也很乐意推荐相关示例。请为本文章添加评论，分享您已实施的内容。

如果您运行 IIS/AD，但不想构建自己的 .NET 解决方案，我们可提供传统版 ASP 的完整实施，您只需调整几个变量。从 Github 下载 ASP 身份验证脚本。