自定义接口配置
功能简介
SAML 2 是一个标准的 SSO 协议， 并受Windows AD支持, 因此在 SSO 领域有着广泛的应用，但其要求开发者具有一定的背景知识(建议阅读官方文档)，对接成本较高， 因此我们补充实现了自定义接口。
自定义接口是简化的SAML协议，企业客户可在现有SSO接口基础上进行修改，按照本系统的要求调用服务和返回参数，并将认证后的用户信息返回给本系统，完成账号关联。
IdP 配置说明
自定义接口的整体配置与 SAML 2 类似, 只是支持的加密算法与密钥的形式存在差异, 在 SAML 中我们支持 SHA 系列算法, 而自定义接口中我们支持 HMAC-SHA系列算法。在 SAML 中我们要求用户填写包含公钥的基于 X.509 格式的证书, 而在自定义接口中需要填写的是一个普通的密钥字符串, 长度最大为 128。
基于配置的 IdP 信息, 客户需要开发自己的 IdP来与本系统对接以实现单点登录. 用户 IdP 的作用可从下图中体现:
即 IdP 服务:
接受来自本系统的认证请求；
基于其在本系统的配置与本系统的开发文档中提到的规范, 验证请求的合法性；
从 Session 中获取当前成员的相关信息, 封装及签发 Token；
将 Token 作为参数, 将用户重定向回本系统。
参数
IdP 服务与本系统间的 Token 传递基于 JWT 标准, 关于 JWT 标准可以阅读这篇文档(英文)或阮一峰老师的这篇文章(中文)， 参数符合以下格式:
来自本系统的认证请求:
| 参数名 | 说明 |
|---|---|
| request | 认证请求 Token, 详见下文 |
| state | 状态值, 此值需要原封不动的返回本系统, 本系统通过此值来避免恶意的断言请求 |
返回本系统的认证断言:
| 参数名 | 说明 |
|---|---|
| response | 认证断言 Token, 详见下文 |
| state | 状态值, 来自认证请求 |
签名内容
认证请求
对于来自本系统的认证请求, IdP 需要自行验证(取决于您的安全级别, 开发环境可以跳过验证):
| 参数名 | 说明 |
|---|---|
| iss | 常量值 “com.XXX”, 意指此请求由本系统发起 |
| aud | 可选, 管理员在本系统配置的 Issuer |
| iat | 签名签发时间(通常 JWT 第三方库会包含此验证, 无需手动实现验证逻辑) |
| exp | 签名失效时间(通常 JWT 第三方库会包含此验证, 无需手动实现验证逻辑) |
| type | 常量值 “sso_req”, 意指此为一个单点登录认证请求 |
您实际收到的请求原文及其对应解码后的格式如下示例:
认证断言
本系统要求 IdP 在确认用户身份并将其重定向回本系统时, 携带的 response 参数解码后对应的内容如下:
| 参数名 | 说明 |
|---|---|
| aud | 常量值 “com.baibaoyun”, 意指此断言的接收方为本系统 |
| exp | 签名失效时间 |
| iat | 签名签发时间 |
| iss | 可选, 管理员在本系统配置的 Issuer |
| nbf | 可选, 签名生效时间 |
| type | 常量值 “sso_res”, 意指此为一个单点登录认证断言 |
| username | 成员的唯一标识, 此值应当与一个已经在本系统通讯录中激活的成员唯一标识相同 |
您实际发送的断言原文及其对应解码后的格式如下示例:
示例
绝大多数编程语言都有较为良好的 JWT算法实现, 第三方库列表可在这个页面中查找。
单点登出(可选)
如果用户配置了 SLO Endpoint, 当访问本系统的单点登出地址时,本系统不仅会登出当前成员, 同时还会将成员重定向至 IdP 并携带登出请求参数, IdP 可以销毁与此成员的会话以实现单点登出的效果. 单点登出请求参数格式与认证请求参数一致, 但不包含 state 字段, 在 Token 中的 type 为常量 “slo_req”.
| 参数名 | 说明 |
|---|---|
| iss | 常量值 “com.XXX”, 意指此请求由本系统发起 |
| aud | 可选, 管理员在本系统配置的 Issuer |
| iat | 签名签发时间(通常 JWT 第三方库会包含此验证, 无需手动实现验证逻辑) |
| exp | 签名失效时间(通常 JWT 第三方库会包含此验证, 无需手动实现验证逻辑) |
| type | 常量值 “slo_req”, 意指此为一个单点登出认证请求 |