sa-token/sa-token-doc/sso/sso-apidoc.md

SSO-Server 认证中心开放接口

如果你的 SSO-Server 端和 SSO-Client 端都使用 Sa-Token-SSO 搭建，那么你可以直接跳过本章，开始 SSO模式一 共享Cookie同步会话 的学习。

如果你仅在 SSO-Server 端使用 Sa-Token-SSO 搭建，而 SSO-Client 端使用其它框架的话，那么你就需要手动调用 http 请求来对接 SSO-Server 认证中心， 下面的 API 列表将给你的对接步骤做一份参考。

---

一、SSO-Server 认证中心接口

1、单点登录授权地址

http://{host}:{port}/sso/auth

接收参数：

参数	是否必填	说明
redirect	是	登录成功后的重定向地址，一般填写 location.href（从哪来回哪去）
mode	否	授权模式，取值 [simple, ticket]，simple=登录后直接重定向，ticket=带着ticket参数重定向，默认值为ticket
client	否	客户端标识，可不填，代表是一个匿名应用，若填写了，则校验 ticket 时也必须是这个 client 才可以校验成功

访问接口后有两种情况：

• 情况一：当前会话在 SSO 认证中心未登录，会进入登录页开始登录。
• 情况二：当前会话在 SSO 认证中心已登录，会被重定向至 redirect 地址，并携带 ticket 参数。

ticket 码具有以下特点：

1. 每次授权产生的 ticket 码都不一样。
2. ticket 码用完即废，不能二次使用。
3. 一个 ticket 的有效期默认为五分钟，超时自动作废。
4. 每次授权产生新 ticket 码，会导致旧 ticket 码立即作废，即使旧 ticket 码尚未使用。

2、RestAPI 登录接口

http://{host}:{port}/sso/doLogin

接收参数：

参数	是否必填	说明
name	是	用户名
pwd	是	密码

此接口属于 RestAPI (使用ajax访问)，会进入后端配置的 ssoServer.doLoginHandle 函数中，此函数的返回值即是此接口的响应值。

另外需要注意：此接口并非只能携带 name、pwd 参数，因为你可以在方法里通过 SaHolder.getRequest().getParam("xxx") 来获取前端提交的其它参数。

3、Ticket 校验接口

此接口仅配置模式三 (isHttp=true) 时打开

http://{host}:{port}/sso/checkTicket

接收参数：

参数	是否必填	说明
ticket	是	在步骤 1 中授权重定向时的 ticket 参数
ssoLogoutCall	否	单点注销时的回调通知地址，只在SSO模式三单点注销时需要携带此参数
client	否	客户端标识，可不填，代表是一个匿名应用，若填写了，则必须填写的和 /sso/auth 登录时填写的一致才可以校验成功
timestamp	是	当前时间戳，13位
nonce	是	随机字符串
sign	是	签名，生成算法：md5( [client={client值}&]nonce={随机字符串}&[ssoLogoutCall={单点注销回调地址}&]ticket={ticket值}&timestamp={13位时间戳}&key={secretkey秘钥} ) 注：[]内容代表可选

返回值场景：

• 校验成功时：

{
    "code": 200,
    "msg": "ok",
    "data": "10001",	// 此 ticket 指向的 loginId
	"remainSessionTimeout": 7200, // 此账号在 sso-server 端的会话剩余有效期（单位：s）
}

• 校验失败时：

{
    "code": 500,
    "msg": "无效ticket：vESj0MtqrtSoucz4DDHJnsqU3u7AKFzbj0KH57EfJvuhkX1uAH23DuNrMYSjTnEq",
    "data": null
}

4、单点注销接口

http://{host}:{port}/sso/signout

此接口有两种调用方式

4.1、方式一：在 Client 的前端页面引导用户直接跳转，并带有 back 参数

例如：

http://{host}:{port}/sso/signout?back=xxx

用户注销成功后将返回 back 地址

4.2、方式二：在 Client 的后端通过 http 工具来调用

接受参数：

参数	是否必填	说明
loginId	是	要注销的账号 id
timestamp	是	当前时间戳，13位
nonce	是	随机字符串
sign	是	签名，生成算法：md5( loginId={账号id}&nonce={随机字符串}&timestamp={13位时间戳}&key={secretkey秘钥} )
client	否	客户端标识，可不填，一般在帮助 “sso-server 端不同client不同秘钥” 的场景下找到对应秘钥时，才填写

例如：

http://{host}:{port}/sso/signout?loginId={value}&timestamp={value}&nonce={value}&sign={value}

将返回 json 数据结果，形如：

{
    "code": 200,    // 200表示请求成功，非200标识请求失败
    "msg": "单点注销成功",
    "data": null
}

如果单点注销失败，将返回：

{
    "code": 500,    // 200表示请求成功，非200标识请求失败
    "msg": "签名无效：xxx",	// 失败原因 
    "data": null
}

SSO 认证中心只有这四个接口，接下来让我一起来看一下 Client 端的对接流程：SSO模式一 共享Cookie同步会话

---

二、SSO-Client 应用端开放接口

1、登录地址

http://{host}:{port}/sso/login

接收参数：

参数	是否必填	说明
back	是	登录成功后的重定向地址，一般填写 location.href（从哪来回哪去）
ticket	否	授权 ticket 码

此接口有两种访问方式：

• 方式一：我们需要登录操作，所以带着 back 参数主动访问此接口，框架会拼接好参数后再次将用户重定向至认证中心。
• 方式二：用户在认证中心登录成功后，带着 ticket 参数重定向而来，此为框架自动处理的逻辑，开发者无需关心。

2、注销地址

http://{host}:{port}/sso/logout

接收参数：

参数	是否必填	说明
back	否	注销成功后的重定向地址，一般填写 location.href（从哪来回哪去），也可以填写 self 字符串，含义同上

此接口有两种访问方式：

• 方式一：直接 location.href 网页跳转，此时可携带 back 参数。
• 方式二：使用 Ajax 异步调用（此方式不可携带 back 参数，但是需要提交会话 Token ），注销成功将返回以下内容：

{
    "code": 200,    // 200表示请求成功，非200标识请求失败
    "msg": "单点注销成功",
    "data": null
}

3、单点注销回调接口

此接口仅配置模式三 (isHttp=true) 时打开，且为框架回调，开发者无需关心

http://{host}:{port}/sso/logoutCall

接受参数：

参数	是否必填	说明
loginId	是	要注销的账号 id
timestamp	是	当前时间戳，13位
nonce	是	随机字符串
sign	是	签名，生成算法：md5( loginId={账号id}&nonce={随机字符串}&timestamp={13位时间戳}&key={secretkey秘钥} )
client	否	客户端标识，如果你在登录时向 sso-server 端传递了 client 值，那么在此处 sso-server 也会给你回传过来，否则此参数无值。如果此参数有值，则此参数也要参与签名，放在 loginId 参数前面（字典顺序）
autoLogout	否	是否为“登录client超过最大数量”引起的自动注销（true=超限系统自动注销，false=用户主动发起注销）。如果此参数有值，则此参数也要参与签名，放在 client 参数前面（字典顺序）

返回数据：

{
    "code": 200,    // 200表示请求成功，非200标识请求失败
    "msg": "单点注销回调成功",
    "data": null
}