启用 SAML 单点登录

我的服务模式是什么？

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

Zendesk 支持通过安全声明标记语言 (SAML)、JSON 网络密钥 (JWT) 和 OpenID Connect (IODC) 对 Zendesk 帐户进行企业单点登录访问。使用 SSO，用户可使用其公司登录表格登录一次，以访问多个系统和服务提供商，包括 Zendesk 产品。

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

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

本文章包含以下主题：

• Zendesk 的 SAML SSO 的工作方式
• 启用 SAML SSO 的要求
• 启用 SAML SSO
• 将 SAML SSO 分配给用户
• 启用 SAML SSO 后管理 Zendesk 中的用户
• 切换身份验证方法

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

• 技术实施工作表

相关文章：

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

Zendesk 的 SAML SSO 的工作方式

适用于 Zendesk 的 SAML 的工作方式与适用于所有其他服务提供商的 SAML 相同。一个常见的用例是所有用户身份验证都由 Active Directory（活动目录）或 LDAP（一般称为标识提供者 (IdP)）等公司身份验证系统管理。Zendesk 与标识提供者建立信任关系，允许其对用户进行身份验证并使其登录 Zendesk 帐户。

一个常见的用例是用户在工作日开始时登录其公司系统。登录后，他们即可访问其他公司应用程序和服务（如电邮或 Zendesk Support），而无需单独登录这些服务。

如果用户尝试直接登录 Zendesk 帐户，将被重定向到您的 SAML 服务器或服务以进行身份验证。通过身份验证后，用户将被重定向回您的 Zendesk 帐户并自动登录。

另一个受支持的工作流程是在用户登录您公司的网站后授予其对 Zendesk 的访问权限。当用户使用网站凭证登录网站时，网站会发送请求给标识提供者以验证用户。然后网站将提供商的响应发送到 SAML 服务器，后者将其转发到您的 Zendesk 帐户，由后者授予用户会话权限。

启用 SAML SSO 的要求

与您公司中负责 SAML 身份验证系统的团队（通常是 IT 团队）沟通，确保您的公司满足以下要求：

• 公司有一个 SAML 服务器，其中有已配置的用户，或已连接到身份存储库，如 Microsoft Active Directory 或 LDAP。选项包括使用内部 SAML 服务器（如 OpenAM），或 SAML 服务（如 Okta、OneLogin 或 PingIdentity）。

• 如果使用活动目录联合身份验证服务 (ADFS) 服务器，则必须启用基于表格的身份验证。Zendesk 不支持 Windows 集成身份验证 (WIA)。有关更多信息，请参阅使用带有 ADFS 和 SAML 的 Active Directory 设置单点登录。

• Zendesk 绑定的流量通过 HTTPS，而不是 HTTP 传输。

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

• 您的 SAML 服务器的远程登录 URL（有时称为“SAML 单点登录 URL”）
• （可选）Zendesk 在用户退出后可重定向用户的远程退出 URL
• （可选）将用户重定向到相关登录选项的 IP 范围列表。从指定 IP 范围发出请求的用户将转接到远程 SAML 身份验证登录表格。从该范围外的 IP 地址发出请求的用户将转接到常规的 Zendesk 登录表格。如果您不指定范围，所有用户都将重定向到远程身份验证登录表格。
• 来自您的 SAML 服务器的 SAML 证书的 SHA2 指纹。支持 PEM 或 DER 格式的 X.509 证书，但您仍需提供该证书的 SHA2 指纹。SHA 指纹的大小没有上限。

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

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

启用 SAML SSO

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

在 Zendesk 中启用 SAML 单点登录

1. 在管理中心，单击侧栏中的帐户图标 ()，然后选择安全 > 单点登录。
2. 单击创建 SSO 配置，然后选择 SAML。
3. 输入唯一的配置名称。
4. 对于 SAML SSO URL，输入 SAML 服务器的远程登录 URL。
5. 输入 SHA-256 证书指纹。这是我们与您的 SAML 服务器通信的必需内容。
6. （可选）对于 远程退出 URL，输入用户退出 Zendesk 后应重定向到的退出 URL。
7. （可选）对于 IP 范围，如果您想将用户重定向到相关登录选项，请输入 IP 范围列表。

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

8. 选择在用户登录时显示按钮，为 Zendesk 登录页面添加使用 SSO 继续按钮。

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

9. 单击保存。

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

将 SAML SSO 分配给用户

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

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

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

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

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

   

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

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

5. 单击保存。

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

在 Zendesk 中启用 SAML 单点登录后，在 Zendesk 外部对用户所作更改不会自动同步到 Zendesk 帐户。用户在进行身份验证时，其信息会在 Zendesk 中更新。例如，如果将用户添加到您的内部系统，则该用户在登录 Zendesk 时将添加到您的 Zendesk 帐户。如果内部系统中的用户数据（例如姓名或电邮地址）发生更改，在 SAML 有效负载中共享的所有属性都会在 Zendesk 中更新。如果将用户从内部系统中删除，该用户将无法再登录 Zendesk。但其帐户仍将保存在 Zendesk 中。

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

为提供更好的客户体验，您可能希望在 Zendesk 中不仅存储用户的名称和电邮地址。请参阅获取更多用户数据。

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

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

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

关闭密码通知电邮

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

切换身份验证方法

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

技术实施工作表

此部分提供了 Zendesk SAML SSO 实施相关详情，适用于公司中负责 SAML 身份验证系统的团队。

涵盖的主题：

• 识别正在进行身份验证的用户所必需的用户数据
• 配置 Zendesk 的标识提供者
• 配置 Zendesk 的 SAML 服务器
• 返回到您的远程登录和退出 URL 的参数
• 身份验证后使用 RelayState 重定向用户
• Zendesk 的 SAML 配置故障排除

识别正在进行身份验证的用户所必需的用户数据

当您实施对 Zendesk 帐户的 SAML SSO 访问时，可以指定某些用户数据来识别正在进行身份验证的用户。

这些主题描述了您需要提供的数据：

• 在 SAML 主题的 NameID 中指定用户的电邮地址
• 在 SAML 断言中指定两个必需的用户属性

在 SAML 主题的 NameID 中指定用户的电邮地址

Zendesk 使用电邮地址来唯一识别用户。您应在 SAML 使用者名称 ID 中指定用户的电邮地址。

例如：

 <saml:Subject>
      <saml:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified">[e-mail]</saml:NameID>
      <saml:SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">
        <saml:SubjectConfirmationData NotOnOrAfter="2014-04-23T21:42:47.412Z"/>
      </saml:SubjectConfirmation>
    </saml:Subject>

如果未提供 givenname 和 surname 属性，Zendesk 将使用元素中提供的电邮地址的用户名作为用户的名称。电邮地址的第一部分即“@”符号之前的部分是用户名。

如果电邮的用户名中有句点字符，那么我们将用它来解析名字和姓氏。如果没有句点字符，则整个用户名将作为 Zendesk 中用户的名称。例如，如果电邮地址是 [e-mail]，则 Zendesk 中的用户名称将存储为 Stanley Yelnats；但是，如果电邮地址是 [e-mail]，则 Zendesk 中的用户名称将存储为 Stanleyyelnats。

注意：如果您要设置 Microsoft Entra SSO，请确保“名称”声明指向存储用户登录电邮地址的字段。此值通常为 user.mail，但具体设置可能有所不同。

在 SAML 断言中指定两个必需的用户属性

如果您指定了 givenname 和 surname 属性，则必须使用完整的命名空间，而不是友好名称。例如：友好名称可能是“surname”，您需要为该属性指定的实际值是：http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname

概念	属性	描述	示例值
名字	givenname	此用户的名字。您必须为此属性指定完整的命名空间。	http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname
姓氏	surname	此用户的姓氏。Zendesk 中的用户根据此用户的名字和姓氏创建或更新。请参考以下示例。您必须为此属性指定完整的命名空间。	http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname

名字和姓氏示例：

<saml:Attribute Name="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname">
 <saml:AttributeValue xsi:type="xs:anyType">James</saml:AttributeValue>
 </saml:Attribute>
 <saml:Attribute Name="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname">
 <saml:AttributeValue xsi:type="xs:anyType">Dietrich</saml:AttributeValue>
 </saml:Attribute>

Zendesk 支持更多用户属性。与您的 Zendesk Support 管理员讨论他们在 Support 中的数据要求。

获取更多用户数据

Zendesk 从您的身份验证系统中唯一需要的用户数据是用户的名字、姓氏和电邮地址。名字和姓氏是您应该用于捕获关于用户名的信息的唯一属性名称。但是，您可以让 IT 团队在用户登录时标识提供者发送给 Zendesk 的 SAML 断言中添加用户属性，从而获取更多数据。

一个 SAML 断言包含一个或多个关于用户的语句。一个语句就是授权决定本身——用户是否被授予访问权限。另一个语句可包含描述已登录用户的属性。

Zendesk 支持已登录用户的以下其他用户属性。在 Support 中定义您的数据要求，然后与您的 IT 团队讨论将用户属性添加到 SAML 断言。请注意，仅当断言的属性语句中使用了下表所列属性名称时，Zendesk 才会识别这些额外的用户属性；如果您尝试对这些属性使用完整的命名空间，其将被忽略。

属性	描述
organization	要添加用户的组织名称或 ID。不支持组织的 external_id 属性。如果该组织不存在 Zendesk 中，则不会被创建。用户仍将被创建，但不会被添加到任何组织。
organizations	逗号分隔值，例如 org1，org2，org3
organization_id	Zendesk API 中组织的外部 ID。如果同时提供了 organization 和 organization_id，则前者将被忽略。 例如：134211213 如果您想同时传递多个组织 ID，请使用 organization_ids 属性。组织 ID 必须以字符串的形式传递，并用逗号分隔。
organization_ids	Zendesk API 中组织的外部 ID。同时传递多个组织 ID 时使用此属性。如果同时提供了 organization 和 organization_ids，则忽略前者。 例如：逗号分隔的值，如 23423433, 234324324, 23432
phone	电话号码，指定为字符串。
tags	要在用户上设置的标签。这些标签将替换用户个人资料中可能存在的任何其他标签。
remote_photo_url	要在用户个人资料上设置的照片 URL。
locale（适用于专员） locale_id（适用于终端用户）	Zendesk 中的区域设置，指定为数字。要获取有效数字的列表，请参阅 API 文档中的区域设置。
role	用户的角色。可设置为终端用户、专员或管理员。默认为终端用户。
custom_role_id	仅当上述角色属性的值为专员时适用。您可以使用自定义用户角色 API 获取自定义用户角色的 ID。
external_id	用户不是由电邮地址唯一标识时，或其电邮地址可能会更改时，系统显示的用户 ID。指定为字符串。
user_field_<key>	Zendesk Support 中自定义用户字段的值。请参阅为用户添加自定义字段。<key> 是分配给 Zendesk Support 中自定义用户字段的字段密钥。例如：user_field_employee_number，其中 employee_number 是 Zendesk 中的字段密钥。在属性值中发送空值或空字符串将移除在 Zendesk Support 中设置的所有自定义字段值。

Zendesk 还支持一系列 InCommon 联合属性来将用户属性设置为登录的一部分。对于联合属性，您应使用属性名称而不是友好名称指定完整的命名空间。例如：

友好名称	SAML2 正式名称
ou (organization unit)	urn:oid:2.5.4.11
displayName	urn:oid:2.16.840.1.113730.3.1.241

配置 Zendesk 的标识提供者

指定标识提供者需要以下属性：

属性	值
entityID	https://yoursubdomain.zendesk.com
AudienceRestriction	yoursubdomain.zendesk.com

对于这两个值，将 your_subdomain 替换为 Zendesk Support 子域名。如果不确定子域名，请咨询您的 Zendesk 管理员。

Zendesk 强制执行 AudienceRestriction 属性。

注意：如果您要设置 Microsoft Entra SSO，可能需要使用 https://您的子域名.zendesk.com 或您的子域名 .zendesk.com（不带 https:// 前缀）作为实体 ID 值。

配置 Zendesk 的 SAML 服务器

在配置与 Zendesk 的整合时，一些 SAML 服务器可能需要以下信息：

• 访问使用者服务 (ACS) URL：指定 https://yoursubdomain.zendesk.com/access/saml（区分大小写），其中“accountname”为您的 Support 子域名

• 重定向到 SAML 单点登录 URL：使用 HTTP POST

• 哈希算法 (ADFS)：Zendesk 在使用活动目录联合身份验证服务 (ADFS) 时支持 SHA-2 算法

返回到您的远程登录和退出 URL 的参数

当重定向用户到您的身份验证系统时，Zendesk 会将以下参数附加到远程登录和远程退出 URL。

远程登录 URL 参数

属性	描述
brand_id	用户尝试登录时使用的帮助中心的品牌。请参阅为品牌创建帮助中心，以了解相关信息。

远程退出 URL 参数

属性	描述
email	用户退出电邮。
external_id	您系统中存储在 Zendesk 用户个人资料中的唯一标识符。
brand_id	用户退出时使用的帮助中心的品牌。请参阅为品牌创建帮助中心，以了解相关信息。

如果您不想在退出 URL 中接收电邮和外部 ID 信息，请让您的 Zendesk 管理员在管理员界面的远程退出 URL 字段中指定空白参数。请参阅启用 SAML SSO。例如：https://www.yourdomain.com/user/signout/?email=&external_id=。

身份验证后使用 RelayState 重定向用户

RelayState 是一个参数，用于在整个 SSO 流程中维护原始请求的状态。它指定了 SSO 流程开始之前用户尝试访问的原始 URL。完成 SSO 流程后，您可以将用户转接到 RelayState URL 以提供无缝衔接的用户体验。

RelayState 参数在 SAML 中是可选的。如果您未将其包含在请求中，用户将被定向到根据其用户类型决定的默认位置。

• 对于专员，默认位置是 Zendesk Support 中的专员面板。
• 对于终端用户，默认位置是您默认品牌的帮助中心主页。

当用户访问需要登录的 Zendesk 链接，而您正在使用 SAML 时，Zendesk 会将用户重定向到您设置的 SSO 配置，并在 RelayState 参数中发送该用户来自的 URL。

例如：

https://zendesk.okta.com/app/zendesk/exladafgzkYLwtYra2r7/sso/saml?RelayState=https%3A%2F%2Fyoursubdomain.zendesk.com%2Fagent%2Ffilters%2F253389123456&brand_id=361234566920&SAMLRequest=[samlloginrequesthere]

当设置 SAML 身份验证请求时，添加 RelayState 参数，并将其值设置为在 SAML 响应中从 Zendesk 发送的 URL。

例如，RelayState 参数将用户重定向到 https://yoursubdomain.zendesk.com/agent/filters/253389123456：

SAMLResponse=[SAMLpayloadhere]&RelayState=https%3A%2F%2Fyoursubdomain.zendesk.com%2Fagent%2Ffilters%2F253389123456

Zendesk 的 SAML 配置故障排除

Zendesk 的 SAML 2.0 元数据如下所示：

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<EntityDescriptor entityID="https://yoursubdomain.zendesk.com" xmlns="urn:oasis:names:tc:SAML:2.0:metadata">
    <SPSSODescriptor AuthnRequestsSigned="false" WantAssertionsSigned="true" protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
        <NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress</NameIDFormat>
        <AssertionConsumerService index="1" Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://yoursubdomain.zendesk.com/access/saml"/> <!-- Note: replace 'accountname' with your Zendesk subdomain -->
    </SPSSODescriptor>
</EntityDescriptor>

Zendesk 需要一个如下所示的 SAML 断言：

<samlp:Response xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol" ID="s2202bbbb
afa9d270d1c15990b738f4ab36139d463" InResponseTo="_e4a78780-35da-012e-8ea7-005056
9200d8" Version="2.0" IssueInstant="2011-03-21T11:22:02Z" Destination="https://yoursubdomain.zendesk.com/access/saml">
    <saml:Issuer xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion">myidp.entity.id
    </saml:Issuer>
    <samlp:Status xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol">
        <samlp:StatusCode  xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol"
Value="urn:oasis:names:tc:SAML:2.0:status:Success">

注意：将 Destination 属性中的“accountname”替换为 Zendesk 子域名。

Zendesk 希望在断言的属性语句中指定用户属性 ()，如以下示例所示：

<saml:AttributeStatement>
  <saml:Attribute Name="organization">
    <saml:AttributeValue xsi:type="xs:string">Acme Rockets</saml:AttributeValue>
  </saml:Attribute>
  <saml:Attribute Name="tags">
    <saml:AttributeValue xsi:type="xs:string">tag1 tag2</saml:AttributeValue>
  </saml:Attribute>
  <saml:Attribute Name="phone">
    <saml:AttributeValue xsi:type="xs:string">555-555-1234</saml:AttributeValue>
  </saml:Attribute>
  <saml:Attribute Name="role">
    <saml:AttributeValue xsi:type="xs:string">agent</saml:AttributeValue>
  </saml:Attribute>
  <saml:Attribute Name="custom_role_id">
    <saml:AttributeValue xsi:type="xs:string">12345</saml:AttributeValue>
  </saml:Attribute>
 </saml:AttributeStatement>

有关 Zendesk 支持的用户属性的名称和描述，请参阅上面的获取更多用户数据中的表格。请注意，可选用户属性不支持完整的命名空间。