What's my plan?
Suite Any plan
Support Any plan

单点登录身份验证的核心是一种称为 JSON 网络密钥 (JWT) 的技术,让 Zendesk 可以信任从您的系统收到的登录请求。有关详情,请参阅设置使用 JWT(JSON 网络密钥)的单点登录

对于 Zendesk SSO 整合,服务器端机制应生成 JWT 并将用户的浏览器重定向到特定于 Zendesk 的 URL,将 JWT 作为查询字符串中的参数而不是 HTTP 标头中的参数传递。

JWT 通常由三部分组成,各部分用句点(句号)隔开。JWT 结构中的每个部分都有不同的用途:标头、有效负载和签名。

重要提示:为了 SSO 的安全,最好使用 HTTP POST 请求(而不是 HTTP GET 请求)。使用 HTTP POST 时,用户数据将在请求正文中传递。对于 HTTP GET 请求,用户相关数据(如电话号码或工单标签)连同 JWT 一起在 URL 中传递,而 JWT 可能存储在浏览器的历史记录或缓存中,使其面临暴露的风险。

本文章包含以下部分:

  • 组块 1:JWT 标头
  • 组块 2:JWT 声明集/有效负载
  • 组块 3:JWS Signature

组块 1:JWT 标头

第一个块是 JWT 标头。它表明这是一个 JWT 请求,并说明了所用哈希算法的类型。(稍后会详细介绍。)

eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9

此数据(以及其余数据)最重要的是它是 base64 编码的。这实际上不是加密,因此可以使用以下工具轻松解码:

  • 网络工具:http://www.base64decode.org/
  • 终端:/tools/base64decode/http://drewsymo.com/how-to/quiick-and-simple-base64-encode-on-mac-osx-terms/

该字符串解码后的样子:

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

可以看到,它采用 JSON 结构,有两个键值对,分别表示 type: JWT 和 Algorithm: HMAC SHA 256更新。SHA 256 是由 US 设计的 256 位加密算法 设计的一种 256 位加密算法。它将用于生成第三个块,即签名,我们稍后将对此进行介绍。

组块 2:JWT 声明集/有效负载

第二个块要长得多,因为它包含了有效负载。它称为“JWT 声明集”。

eyJpYXQiOjEzNzIxMTMzMDUsImp0aSI6ODg4MzM2MjUzMTE5Ni4zMjYsIm5hbWUiOiJUZXN0IFVzZXIiLCJlbWFpbCI6InR1c2VyQGV4YW1wbGUub3JnIiwiZXh0ZXJuYWxfaWQiOiI1Njc4Iiwib3JnYW5pemF0aW9uIjoiQXBwbGUiLCJ0YWdzIjoidmlwX3VzZXIiLCJyZW1vdGVfcGhvdG9fdXJsIjoiaHR0cDovL21pdC56ZW5mcy5jb20vMjA2LzIwMTEvMDUvQmFybmFieV9NYXR0X2Nyb3BwZWQuanBnIiwibG9jYWxlX2lkIjoiOCJ9

其中包含一个时间戳、一个随机值、一个用户名、一个电邮地址、一个外部 ID 和一些标签。还有更多选项。同样,只需对其进行 base64 解码即可理解有效载荷。我将把这些内容拆分一下,以便于理解。

{
"iat":1372113305,
"jti":8883362531196.326,
"name":"Test User",
"email":"tuser@example.org",
"external_id":"5678",
"organization":"Apple",
"tags":"vip_user",
"remote_photo_url":"http://mit.zenfs.com/206/2011/05/Barnaby_Matt_cropped.jpg",
"locale_id":"8"
}

必要属性

IAT

第一个密钥是iat,它代表颁发于。这是一个自 1970 年 1 月 1 日以来的时间戳,格式为整数秒,1970 年 1 月 1 日是标准 UNIX 时间表示形式。时间戳必须是整数(没有小数),而且必须是 UTC。当 Zendesk 服务器收到它时,它也必须与当前时间相差在 3 分钟内。这样可以在每个远程身份验证请求中加入自销毁机制,防止任何单个请求在生成后超过 3 分钟后被使用。

JTI

第二个密钥jti表示JSON 密钥 ID。这其实只是一个随机字符串。它必须足够长,而且是随机的,这样就不会被再次用于此帐户。如果它无意中被另一个身份验证请求重复使用,则请求将失败。这是一把一次性钥匙。通过包含这样一个(强制)随机值,我们可以确保没有两个身份验证请求是相同的。这样可以防止重复使用有效的请求 URL。例如,假设有人在您的计算机或网络上成功安装了恶意软件,并已开始记录您的流量。他们可以看到您点击的每个 URL。如果他们看到并抓取了您颁发的登录 Zendesk 的 URL,他们可以在 3 分钟内以您的身份登录,而不需要这个一次性密钥。

名称

接下来是用户的全名,包括空格。Zendesk 在这里收到的任何内容都将设置为用户名,即使之前设置了不同的名称。

电邮

之后是用户的电邮。电邮始终是必填项。除非收到外部 ID*,否则它将用作用户的唯一标识符。这意味着,如果我们收到电邮和外部 ID,我们会尝试先匹配 ID。 如果是的话,我们会更新指定电邮地址的用户。

*注意: 如果在 Zendesk 中启用了“允许更新外部 ID”选项,即使收到了外部 ID,我们也将继续关闭电邮。如果电邮和外部 ID 不同,我们将更改 ID。 

可选属性

外部 ID

外部 ID 是一个可选 ID,可用于代替用户电邮地址(如上所述)来识别用户。

组织

您还可以传递组织值以将用户添加到组织。指定的组织必须已存在,且名称必须完全匹配。否则不进行任何操作。

工单标签

tags密钥允许您设置标签 在用户登录时。此密钥会将用户上任何现有的工单标签替换为您指定的工单标签,因此请谨慎使用。传递空白 tags 参数可移除用户的所有工单标签 。

远程照片 URL

您还可以传递 remote_photo_url的值,该值接受包含照片的公开 URL,并将此照片设置为用户的个人资料图片。

区域设置(语言) 

您可以传递locale_id 的值,以设置或更新已通过身份验证的用户在 Zendesk 中的语言。值必须是与您 Zendesk 当前激活的区域设置匹配的数字。您可以使用我们 API 的 locales.json 端点找到区域设置:https://developer.zendesk.com/api-reference/ticketing/account-configuration/locales/#list-locales

用户字段(示例中未显示)

这必须是一个 JSON 对象,其中包含每个字段键和值的键值对。字段密钥可在“用户字段”界面中找到或定义。请注意,只有自定义用户字段可以被传递。

例如:

"user_fields": {"checked": false,"date_joined": "2013-08-14T00:00:00+00:00","region": "EMEA","text_field": null}

复选框使用布尔值,日期代码沿用上例,下拉菜单接受选项名称。文本字段接受字符串。

电话号码(示例中未显示)

这接受一个字符串作为电话号码身份。确保以可接受的格式指定电话号码。有关更多信息,请参阅接受的电话号码格式是什么?

组块 3:JWS Signature

请求的最后一个数据块是已加密部分。您无需太担心这一点,但它基本上会将上述所有信息(iat、jti、名称、电邮等)与共享密钥一起提取,并从中生成一个加密字符串。然后,根据 JWT 标准,从该加密的字符串中提取一大块(称为 检验和),即 JWS 签名。

那么这如何安全呢?

要生成有效的加密字符串,您必须知道共享密钥。

加密经过专门设计,使您无法从加密字符串倒推到数据和密钥。即使您有数据内容,实际上也不可能推导出密钥。

但是,既然您有密钥,我们也有密钥,而且您发送给我们的未加密数据与已加密数据相同,我们就可以自己构建签名,并检查它是否与您发送的数据匹配。

它还确保没有人可以篡改传输过程中的数据。

这是使用伪代码构建它的方式:

URLBase64Encode( 
HMAC-SHA256(
URLBase64Encode( header_json ).URLBase64Encode( payload_json )
)
)

在生成已编码标头和有效负载的 HMAC-SHA256 时,请包含共享密钥。

结果如下:

Zv9P7PNIcgHfxZaMwQtMpty3TZnmVHRWcsmAMM-mNHg

翻译免责声明:本文章使用自动翻译软件翻译,以便您了解基本内容。 我们已采取合理措施提供准确翻译,但不保证翻译准确性

如对翻译准确性有任何疑问,请以文章的英语版本为准。

由 Zendesk 提供技术支持