README

此软件包的目标只有一个：通过使用 JSON Web 令牌，简化您的应用程序自动登录到您的 Zendesk 支持账户。第一次点击此软件包创建的特殊链接时，Zendesk 的单点登录功能将自动根据他们的电子邮件地址创建新用户，并在随后的访问中重新连接到现有账户。

此软件包不封装 Zendesk API，也不进行任何 API 调用。同时，Zendesk API 也没有提供生成 SSO JSON Web 令牌的方法或文档。此软件包可以独立使用，也可以与 Zendesk API 一起使用。

通过 Composer 安装

在 composer.json 文件中指定以下内容（如有必要，从 Packagist 中替换特定版本号）

{
  "require": {
    "fireproofsocks/zendesk-jwt-sso": "dev-master"
  }
}

不推荐使用其他安装方法：此软件包有依赖项。

示例

请参阅以下关于设置您的 Zendesk 账户的部分，了解如何以及在哪里获取您的子域和共享密钥。

完整示例，例如在控制器内或您的网站根目录下的专用 PHP 页面中

require_once 'vendor/autoload.php'

// Retrieve these from .env or config
$subdomain = 'your-zendesk-subdomain';
$shared_secret = 'xxxxxxxxxxxxxx';

$sso = new \ZendeskSso\ZendeskSso($subdomain, $shared_secret);

// Remember: SSO means that YOUR application is handling the login.  Only forward a user over to Zendesk when they are
// logged in on your site. 
if (is_logged_in()) {
    $name = 'Name of Logged in User'; // e.g. from $_SESSION
    $email = 'email.of@user.com';
    $external_id = 123; // user id in your app
    $return_to = 'http://my-domain.com/some/page';
    $options = ['external_id' => $external_id];
    $sso->redirectToUrl($name, $email, $return_to, $options);  // this will redirect and exit
}
else {
    print 'Sorry, you are not logged into our site.  You can visit our Zendesk portal as a guest (if enabled).';
}

或者更简单一些

require_once 'vendor/autoload.php'

// Retrieve these from .env or config
$subdomain = 'your-zendesk-subdomain';
$shared_secret = 'xxxxxxxxxxxxxx';

$sso = new \ZendeskSso\ZendeskSso($subdomain, $shared_secret);

// Remember: SSO means that YOUR application is handling the login.  Only forward a user over to Zendesk when they are
// logged in on your site. 
if (is_logged_in()) {
    $name = 'Name of Logged in User'; // e.g. from $_SESSION
    $email = 'email.of@user.com';
    $sso->redirectToUrl($name, $email);  // this will redirect and exit
}

如果您需要获取 SSO URL，可以使用 getUrl 方法，但请记住 JWT 有效期仅为几秒钟，所以您不希望在 HTML 模板或锚点标签中打印 URL，您希望生成后尽快重定向到该 URL。

require_once 'vendor/autoload.php'

// Retrieve these from .env or config
$subdomain = 'your-zendesk-subdomain';
$shared_secret = 'xxxxxxxxxxxxxx';

$sso = new \ZendeskSso\ZendeskSso($subdomain, $shared_secret);
 
if (is_logged_in()) {
    $name = 'Name of Logged in User'; // e.g. from $_SESSION
    $email = 'email.of@user.com';
    $url = $sso->getUrl($name, $email);
    header('Location: '.$url);
    exit();
}

自定义用户字段

如果您正在传递自定义 user_fields，您需要花费时间在您的 Zendesk 管理仪表板下“管理 > 用户字段”中设置用户字段。您在键/值关联数组中传递的名称必须与仪表板中定义的字段名称匹配。不支持更深的对象结构，例如。

$subdomain = 'your-zendesk-subdomain';
$shared_secret = 'xxxxxxxxxxxxxx';
$options = [
    'external_id' => 123,
    'user_fields' => [
        'first_name' => 'John',
        'last_name' => 'Doe',
        'profile_link' => 'http://yoursite.com/profile/john-doe',
    ]
];
$sso = new \ZendeskSso\ZendeskSso($subdomain, $shared_secret, $options);

您的 Zendesk 账户设置

您需要配置您的 Zendesk 账户才能使用 SSO 功能。要连接到现有的 Zendesk 账户，您的应用程序需要以下内容

• Zendesk 子域
• 共享密钥令牌

如果您的Zendesk账户已经配置好并且您已经拥有了这些信息，您可以跳过本节并继续测试您的实现。然而，如果您需要设置应用程序以测试沙盒环境（例如，开发人员无法访问实时生产令牌或数据），那么您需要创建一个沙盒并在沙盒上启用/配置SSO。不幸的是，沙盒环境仅在某些订阅计划上可用。有关沙盒的更多信息，请参阅下文“测试集成”部分。

请记住：每次沙盒环境重置时，您都需要重复设置！

自定义域名：如果您使用自定义域名（而非Zendesk子域名）来代替您的Zendesk帮助中心，例如help.yourdomain.com，您的登录URL仍然需要在子域名上进行！如果您尝试在自定义域名上执行SSO登录，Zendesk会显示一个相关的警告。

Zendesk需要的信息

在设置您的Zendesk账户以进行单点登录之前，您应该知道以下事项：

• 您应用程序的登录URL
• 您应用程序的注销URL （可选）
• 更新外部ID？ （可选） - external_id对于账户是唯一的，如果您的应用程序允许用户更新他们的电子邮件地址或如果您的应用程序使用除电子邮件地址之外的内容（例如用户名或主键）来唯一标识用户，这可以是一个有用的标识用户的方式。

启用SSO

要获取或创建您的Zendesk API密钥，您必须是您的Zendesk账户的管理员。如果您不是管理员，您需要向管理员提供上述详细信息（登录URL等）。他们可以阅读这些设置说明并将子域和共享密钥提供给您。

登录到您的Zendesk账户，例如，URL为 https://your-company-name.zendesk.com/login

在管理界面左下角是“管理”的齿轮图标。点击它，然后滚动左侧列到“设置”标题并查找“安全”链接。

注意！Zendesk管理网站的布局可能会让人困惑！有一个位于图标右侧的左侧列。这个列可以独立于主页区域上下滚动。

在 /agent/admin/security 的安全页面，有几个选项卡，您需要查看以正确配置您希望SSO如何运行。您不仅可以在常规和沙盒账户之间定义和配置不同的SSO，您还可以为两种主要用户类型分别启用和配置SSO：

• 管理员和代理
• 最终用户

通常您会想要为最终用户启用SSO，并且您可能还想为管理员和代理启用SSO功能。 请记住： 这是两个完全不同的功能！ 每个组的配置可以完全不同！

点击启用“单点登录（SSO）”功能，然后选择“JSON Web Token”选项。

• 输入您应用程序的登录URL（即“远程”登录URL）。
• 可选地输入您应用程序的注销URL
• 可选地启用外部ID的更新。
• 复制共享密钥并保存在安全位置。

推荐的安全设置

当您在 /agent/admin/security 的 Zendesk 管理员安全设置中时，您可能希望在全球选项卡下启用以下功能以提高安全性

• 自动遮蔽 -- 自动将信用卡号码 替换为 X。如果您的账户遭到入侵，如果您无法获取信用卡号码，将减少您的法律责任。您的支持人员仍然可以识别剩余数字（例如最后四位）来识别卡号。
• 双因素认证 -- 要求双因素认证是您为了提高安全性所能采取的最重要措施之一。当启用时，它几乎消除了恶意用户获取对您的 Zendesk 应用及其客户数据（以及信用卡号码）的访问权限的可能性（您已经勾选了“自动遮蔽”选项，不是吗？）

集成测试

设置沙盒账户

Zendesk 企业版提供了 沙盒环境，用于安全测试其 API，但可能不太明显的是沙盒也可以用于测试 SSO 登录。登录您的 Zendesk 管理仪表板，然后点击左下角的“管理”齿轮，然后选择 管理 > 沙盒。如果您尚未创建沙盒，请点击“创建我的沙盒”，或者如果您需要重置设置，则可以“重置我的沙盒”。

当您创建或刷新沙盒时，用户资料、工单和 SSO 设置不会被复制！ 您需要以管理员身份登录沙盒，然后配置/启用 JSON Web Token SSO。

遗憾的是，Zendesk 只使用一个沙盒，并且只能配置一个登录和注销 URL；如果您的应用程序使用多个开发环境，每个环境都有独特的域名和 URL，则可能存在问题。

一旦您设置了一个要测试的环境（无论是沙盒还是您的实际环境），您可以尝试创建 SSO URL 并访问它们。

更有经验的开发者可能希望将 phpunit.xml.dist 复制到 phpunit.xml，并添加凭据，然后尝试运行集成测试：phpunit tests/Integration/

支持的 JSON Web Token 属性

以下值包括作为参考。所有可选值都可以作为键包含在作为 getUrl 和 redirectToUrl 方法的第四个参数传递的 $options 数组中。

从 https://support.zendesk.com/hc/en-us/articles/203663816-Setting-up-single-sign-on-with-JWT-JSON-Web-Token-

如果用户字段键或值无效，则更新字段将静默失败，并且用户仍然可以成功登录。有关自定义用户字段的更多信息，请参阅“向用户添加自定义字段”。

注意：在 user_fields 属性中发送空值将删除相应字段中存在的任何现有值。

故障排除

登录问题

如果由于任何原因（例如，您错误地配置了 SSO 选项）陷入重定向循环，您可以通过“秘密”URL：https://your-company-name.zendesk.com/access/normal 来绕过 SSO 登录并“正常”登录。

如果您的“常规”登录是通过 OAuth（例如 Google Mail）完成的，则您可以请求重置密码以为自己生成密码。

测试用户

SSO 流程将自动创建用户。在您的设置和测试期间，您可能最终会创建测试用户帐户。如果您希望删除这些帐户，您可以从 Zendesk 管理门户中的“管理”-->“人员”页面在 /agent/admin/people 进行此操作。要删除单个用户，选择用户的姓名（您将获得用户及其工单的详细视图），然后从右上角的下拉箭头菜单中选择“删除”选项。要一次性删除多个用户，找到右侧列中的“批量最终用户删除”链接，这将带您转到 /people/bulk_delete。

失败的测试

单元测试可以在没有任何网络连接的情况下安全运行。然而，集成测试确实通过网络并且确实会触碰到您的账户。有时可能会遇到网络错误，例如 "php_network_getaddresses: getaddrinfo failed: nodename nor servname provided, or not known"，或者 "failed to open stream: Operation timed out"。这超出了我们的控制范围，因此您最好等待几分钟然后再试一次，看问题是否解决。我不确定这是否是因为 API 限制、防火墙或其他完全不同的原因。