单点登录（SSO）

最后更新：2021-12-31

1. 概述

本文档主要覆盖一个WEB应用， 如何通过单点登录协议JWT， SAML等， 从IDP到这个应用的SSO操作。

如果是希望提供一个IDP的应用模版JAR, 不在本文档讨论范围内，请参考【 应用模版 】插件开发。

单点登录（SSO），英文全称为 Single Sign On。 SSO 是指在多个应用系统中，用户只需要登录一次，就可以访问所有相互信任的应用系统。IDaaS SSO 服务用于解决同一公司不同业务应用之间的身份认证问题，只需要登录一次，即可访问所有添加的应用。此服务可以涵盖用户在公有云和私有云中的双重需求。

本文档默认你已经拥有了开发者权限，并已经阅读了 准备开发 文档 和 应用管理 文档。如果需要分配新的开发者权限的话，请联系 IT 管理员进行授权操作。

2. 单点登录场景

在单点登录实现过程中，现已满足以下场景，包括：

  • IDP 发起

  • SP 发起

  • 接口后置

2.1. IDP 发起

通常政企有自己的门户， 希望能实现登录到门户后， 跳转到一个想去的SP应用，上述的流程即 IDaaS 发起。用户登录 IDaaS 平台，从 IDaaS 登录到 SP 应用场景，下面以 JWT 和 SAML 的实现为例来阐述 IDP 发起的单点登录流程：

以 JWT 协议 IDP 发起的单点登录为例 (SAML 的流程类似)：

  1. 用户访问 IDaaS 登录页面输入用户名和密码进行登录

  2. 浏览器携带用户名密码向 IDaaS 请求登录

  3. IDaaS 认证通过后，创建主 session ，并返回应用列表给浏览器

  4. IDaaS 登录成功，用户可以看到 IDaaS 展示的应用列表

  5. 用户点击应用列表中的 SP1 应用图标

  6. 浏览器携带 SP1 应用的应用 id，向 IDaaS 请求生成 SP1 应用子 token

  7. IDaaS 根据信息生成子 token 并返回给浏览器

  8. 浏览器携带子 token ，向 SP1 请求登录，如：http://idp/{applicationId}/public/sso/xxx?id_token=xxx&target_url=yyy

    • 如果是SAML，浏览器携带 SAMLResponse 跳转到 SP1 的 URL {locationURL}?SAMLResponse=xxx（如果应用配置了IDP发起登录地址则会向配置的地址 [idpSSOLocationURL] 发送 SAMLResponse）

  9. SP1 应用系统解析获取的子 token ，验证通过后，创建子 session 并返回登录后页面

  10. SP1 系统单点登录成功，浏览器显示 SP1 系统登录后页面

  11. （16）表示 SP2 系统的单点登录流程，与 SP1 系统步骤一致，即在主 session 创建后，任何一个可单点登录应用进行单点登录的流程只需重复（5） 即可

2.2. SP 发起

通常政企有自己的应用， 希望能实现跳转到这个指定的应用的某个页面后，能再跳转回IDP，登录后再回到这个指定的SP页面， 这个过程就是SP发起的SSO。 SP发起主要是跳转到一个想去的SP应用SP 发起主要应用于 SSO 后可以跳回发起 SSO 的应用页面，下面以 JWT 和 SAML 的实现为例来阐述 SP 发起的单点登录流程。
用户访问 SP 资源， SP 会重定向到 IDaaS 的登录地址，在 IDaaS 认证通过后，会回到 SP 并携带 id_Token 和 target_url 参数，SP 校验后会向浏览器返回并显示用户访问的资源页面，如下图所示：

以 JWT 协议 SP 发起的单点登录为例 (SAML 的流程类似)：

  1. 用户访问 SP 资源页面，如： http://sp/mail?id=1 （ JWT 中的 target_url，SAML 中的 RelayState ）

  2. 浏览器向 SP 请求资源数据

  3. SP 检测登录状态，若该用户已登录直接跳至步骤（10），未登录继续到（4）

  4. 携带 target_url 重定向到 IDaaS 登录页面，如：http://idp/enduser/sp/sso/xxx?enterpriseId=xxx&target_url=yyy

    • 如果是SAML，则 AuthnRequest 请求发送至 IDP 的 URL 是 http://idp/enduser/api/application/{applicationId}/xxx/sp_sso?SAMLRequest=xxx&RelayState=yyy 注：安全起见，不应该直接传递 URL，RelayState 应该是一个随机数，即使是一个 URL (http%3A%2F%2Fsp%2Fmail%3Fid%3D1）， 则SP应该先保存该 URL，生成一个随机数yyy，再传递到IDP。

  5. 用户输入 IDaaS 的账户和密码进行登录

  6. 浏览器携带账号密码请求登录 IDaaS

  7. IDaaS 对账户进行认证并通过

  8. 认证通过后，会生成 id_token，并 302 跳转到 SP 到 SSO URL 地址 redirect_uri

    • 如果是SAML，认证通过后，生成id_token，并 302 跳转到 SP 的 SSO 的地址 ACS URL。 注：ACS 是能校验解析 SAMLResponse 的一个 SP 提供的 SSO URL

  9. 浏览器携带 id_token 和 target_url 重定向到 SP，如：http://sp/public/sso/xxx?id_token=xxx&target_url=yyy

    • 如果是SAML，浏览器携带 SAMLResponse 和 RelayState 重定向到 SP，如： http://sp/public/sso/xxx?SAMLResponse=xxx&RelayState=yy

  10. 校验成功后，创建 session 会话，向浏览器返回用户访问的 target_url 地址并进行跳转

  11. 如果是SAML，校验成功后，创建 session 会话，向浏览器返回用户访问的 RelayState 地址，并取出 URL，并进行 302 跳转

  12. 最终，用户查看到之前访问的 SP 资源页面，如：http://sp/mail?id=1

2.3. 接口后置

通常政企有自己的应用， 希望能实现在这个应用登录后， 能把账户密码传递给IDP做比对， 成功后再打开这个应用的页面， 这个过程严格上讲不是一个SSO单点登录的过程，更多的是一个统一密码的过程。SP 登录时使用 IDaaS 进行接口后置认证登录场景，如下图所示：

  1. 用户访问 SP1 登录页面

  2. 浏览器请求 SP1 登录页面

  3. SP 1 返回其登录页面

  4. 用户看到 SP1 登录页面

  5. 用户输入用户名密码进行登录

  6. 浏览器携带用户名、密码向 SP1 发起登录请求

  7. SP 1 使用 IDaaS 接口进行认证，将用户名、密码传递给 IDaaS 进行认证登录

  8. IDaaS 进行认证后，生成主 token ，并返回主 token 和应用列表以及用户信息给 SP1

  9. 登录 SP1 成功，浏览器获取到 SP1 登录后页面

  10. 用户可看到 SP1 登录后页面，可看到显示的应用列表

  11. 用户在 SP1 显示的应用列表中点击 SP2 应用图标进行单点登录

  12. 浏览器携带主 token 和应用id，向 IDaaS 请求生成子 token

  13. IDaaS 返回 SP2 的子 token 以及 SP2 重定向地址

  14. 浏览器携带子 token 访问 SP2 重定向地址

  15. SP2 解析子 token ，验证成功，并返回 SP2 登录后页面

  16. 用户看到 SP2 登录后页面， SP2 应用系统登录成功

3. 开发者须知

文档中 IDaaS-Base-URL 需要替换为当前访问地址的主域，文中接口地址前也都需要替换主域地址；接口地址中的版本号以当前使用系统版本为准，也可以查看开发者文档中右侧菜单顶部的接口版本。

用户通过登录 IDaaS 系统，能够在用户的主界面应用列表中看到自身有权限访问的应用列表。用户可以选择一个应用进行单点登录。
单点登录到第三方应用的过程，对于用户来说是透明过程。此过程无需用户填写第三方应用系统的账号信息，而是通过安全的协议交换令牌，直接验证身份进入应用系统。

4. 最佳实践-快速对接单点登录(JWT实现)

4.1. 简介

整个JWT SSO 的流程，是接收 IDaaS 平台向 callback url 发出的 id_token 参数（即 JWT 令牌），并使用我们提供的（或第三方提供的） JWT 解密库/方法对 JWT 进行解析，并验证身份。 你可以自己按照这个逻辑完成代码，也可以在我们提供的 代码/demo 的基础上进行修改。

4.2. 实现原理

image.png

  1. 通过浏览器登录集成的 IDaaS 系统后，确认要单点登录的应用，发起 SSO 请求到 IDaaS 系统。

  2. IDaaS 生成 token 令牌发送到业务应用。

  3. 你的应用获取到 token 令牌，用我们提供的插件或方法解析 token 令牌，解析成功获取到用户信息并验证后，重定向进行登录；如果解析失败则拒绝登录。


4.3. 申请 JWT 应用

本章节默认你已经创建了应用。如果还未创建一个应用并审核的话，请前往 【准备开发 - 创建应用】。
本章节讲解开发者身份创建应用,如果使用IT管理员身份,请切换到开发者身份,或者查看 jwt-标准应用

4.3.1. 第 1 步

应用创建成功后，会弹出提示弹窗，此时点击“新建 SSO 应用”，则可打开创建 JWT 服务弹窗，如下图： image.png

image.png

参数说明：

  1. 图标: 业务应用的 logo 图片。

  2. 应用服务 ID: 自动生成服务 ID，且唯一。

  3. 应用名称: 代表该业务应用的名称

  4. 所属领域: 代表区分该应用服务类型是哪一种服务类型。

  5. 设备类型: 代表该服务支持的设备类型，标记使用。

  6. JWT SSO 地址: 业务应用中的 JWT SSO 地址，在单点登录时 IDaaS 将向该地址用 GET 方式发送 id_token 信息，参数名为 id_token ，业务应用通过 id_token 与 PublicKey 可获取业务应用中的用户信息,应用可配置多个地址，如果在业务系统（SP）发起登录， 请求 SP 登录地址时如果携带 service 参数 IDaaS 会检验合法性，成功后会将浏览器会重定向到该地址，并携带 id_token 。

  7. Redirect URL: 业务应用中在 JWT SSO 成功后重定向的 URL，一般用于跳转到二级菜单或者自定义的动态地址等。 （若在添加应用时设置了该URL，在 JWT SSO 时会以参数 redirect_url 优先传递该值。 若添加应用的时候未设置该值，发起 SSO 也可以自定义参数 redirect_url 的值）

  8. token 包含应用列表: 配合 接口登录（RL）使用，是否在 JWT 的 token 中包含当前用户的授权应用列表。

  9. 账号关联方式：JWT 协议可以使用 账户关联 或 账户映射 方式进行单点登录。如果应用系统接收到的用户名希望和 IDaaS 系统中一致，可以使用账户映射；反之，若希望手动建立关联关系，则选择账户关联。

4.3.2. 第 2 步

新建 JWT 服务成功后，弹出弹窗，此时可发布应用进行测试。 image.png

4.3.3. 第 3 步

应用信息完成后，可以进行相对应的操作，发布按钮，确定操作，应用状态为已发布后即可开始进行集成开发。如下图： image.png

image.png

4.3.4. 第 4 步

导出公钥。点击查看应用->详细，在 PublicKey 字段下方有导出 PKCS8 公钥按钮。

PHP 或 Python：请点击导出该应用的专属公钥，导出后为一个 .pem 文件，将其放置在你的应用中安全并能够度读取到的位置，该公钥在集成中会被用来解密 JWT 信息；
Java 或 .NET: ，请直接复制 PublicKey 框内的内容（即 JWK， Json Web Key）并当做公钥进行解密，将其存储在安全的位置，调试时可以暂时直接存为字符串变量

image.png至此准备工作完成，我们开始进行服务器端的快速开发。

4.4. IDP发起

4.4.1. IDP SSO URL

复制应用详情中的IDaaS SSO URL即可,格式如下
http://idp/enduser/bff/sso/go_xxx?_enterprise_id=xx&purchaseId=xxx

4.4.2. 集成方式

用户登录 IDaaS 系统，点击应用列表中的 SP1 应用图标即可：

以 JWT 协议 IDP 发起的单点登录为例 ：

  1. 用户访问 IDaaS 登录页面输入用户名和密码进行登录

  2. 浏览器携带用户名密码向 IDaaS 请求登录

  3. IDaaS 认证通过后，创建主 session ，并返回应用列表给浏览器

  4. IDaaS 登录成功，用户可以看到 IDaaS 展示的应用列表

  5. 用户点击应用列表中的 SP1 应用图标

  6. 浏览器携带 SP1 应用的应用 id，向 IDaaS 请求生成 SP1 应用子 token

  7. IDaaS 根据信息生成子 token 并返回给浏览器

  8. 浏览器携带子 token ，向 SP1 请求登录，如：http://idp/{applicationId}/public/sso/xxx?id_token=xxx&target_url=yyy

  9. SP1 应用系统解析获取的子 token ，验证通过后，创建子 session 并返回登录后页面

  10. SP1 系统单点登录成功，浏览器显示 SP1 系统登录后页面

  11. （16）表示 SP2 系统的单点登录流程，与 SP1 系统步骤一致，即在主 session 创建后，任何一个可单点登录应用进行单点登录的流程只需重复（5）即可

4.5. SP发起

4.5.1. SP SSO URL

复制应用详情中的SP SSO URL即可,格式如下

http://idp/enduser/sp/sso/xxx?enterpriseId=xxx&target_url=yyy

4.5.2. 集成方式

用户访问SP系统资源,重定向到sp sso url即可:

以 JWT 协议 SP 发起的单点登录为例 ：

  1. 用户访问 SP 资源页面，如： http://sp/mail?id=1 （ JWT 中的 target_url）

  2. 浏览器向 SP 请求资源数据

  3. SP 检测登录状态，若该用户已登录直接跳至步骤（10），未登录继续到（4）

  4. 携带 target_url 重定向到 IDaaS 登录页面，如：http://idp/enduser/sp/sso/xxx?enterpriseId=xxx&target_url=http%3A%2F%2Fsp%2Fmail%3Fid%3D1

  5. 用户输入 IDaaS 的账户和密码进行登录

  6. 浏览器携带账号密码请求登录 IDaaS

  7. IDaaS 对账户进行认证并通过

  8. 认证通过后，会生成 id_token，并 302 跳转到 SP 到 SSO URL 地址 redirect_uri

  9. 浏览器携带 id_token 和 target_url 重定向到 SP，如：http://sp/public/sso/xxx?id_token=xxx&target_url=yyy

  10. 校验成功后，创建 session 会话，向浏览器返回用户访问的 target_url 地址并进行跳转

  11. 最终，用户查看到之前访问的 SP 资源页面，如：http://sp/mail?id=1


4.6. 快速集成

参考文档：

JWT对接 - SDK下载
JWT对接 - 业务系统研发

4.7. 更多协议

在IDP平台中，通过提供’应用’（Application）来实现单点登录功能。提供两种类型的应用实现：

  • 标准协议 应用，基于行业规范沉淀的与IDP平台沉淀的各类单点登录协议实现，包括：

  • 定制模板 应用，对于不支持标准协议的但有自己SSO实现逻辑的应用（如 阿里邮箱），IDP提供应用插件能力进行二次开发，扩展将各类应用的 SSO能力集成到IDP中来，统一属于定制模板。