SSO-Server 认证中心开放接口 ​

一、对接方式说明 ​

在前一章节，我们成功搭建了 SSO-Server 端。SSO-Server 可以为各个子系统提供中央认证服务。

在默认代码架构下，SSO-Server 将提供一套标准 HTTP 接口对外开放。要对接 SSO-Server，有两种方式：

• SDK 方式：在你的 SSO-Client 端，也引入 Sa-Token SSO 框架，通过框架提供的 API 方法完成对接。
• NoSDK 方式：在你的 SSO-Client 端，不引入 Sa-Token SSO 框架，通过工具库调用 Http 接口的方式完成对接。

如果你的 SSO-Client 端是 java 项目，且支持引入 sa-token-sso 框架，我们强烈推荐你使用 SDK 方式对接。你可以直接跳过本章，开始 SSO模式一 共享Cookie同步会话 的学习。

如果你的 SSO-Client 端是 非java 项目，或不支持引入 sa-token-sso 框架，那么你可以使用 NoSDK 方式进行对接。 在之后的 SSO整合 - NoSdk 模式对接 章节我们会详细介绍对接步骤，下面的 API 文档将给你的对接步骤做一份参考。

二、STS 协议 ​

Sa-Token SSO 模块的开放接口标准为 STS 协议。STS 协议的设计充分参考了 CAS、Spring Authorization Server、KeyClock、OAuth2 协议等经典框架/ 协议的授权流程。 定义了应用进行 单点登录、单点注销、消息推送 等动作的标准动作。 可解决：同域、跨域、共享Redis、跨Redis、前后端一体、前后端分离、纯 js、vue2、vue3、Sa-Token 项目、非 Sa-Token 项目、java 项目、非 java 项目 等架构下的 SSO 认证需求。

下面两节将介绍 STS 协议在 SSO-Server 端和 SSO-Client 端开放的接口标准。

三、SSO-Server 认证中心接口 ​

1、单点登录授权地址 ​

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

接收参数：

访问接口后有两种情况：

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

Ticket 码具有以下特点：

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

2、RestAPI 登录接口 ​

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

接收参数：

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

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

3、单点注销接口 ​

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

接收参数：

4、消息推送接口 ​

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

接收参数：

此接口可根据消息类型增加任意参数。新增加的参数要参与 sign 签名。

返回值示例：

• 推送成功时：

{
    "code": 200,
    "msg": "ok",
    "data": "10001",	// 返回的数据 
}

• 推送失败时：

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

• 也有可能消息推送成功了，但是处理消息失败，例如校验 ticket 时：

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

详细可参考：消息推送机制

四、SSO-Client 应用端开放接口 ​

1、登录地址 ​

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

接收参数：

此接口有两种访问方式：

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

2、注销地址 ​

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

接收参数：

此接口有两种访问方式：

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

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

3、单点注销回调接口 ​

此接口仅配置 (reg-logout-call=true) 时打开，且为框架回调，开发者无需关心

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

接收参数：

返回数据：

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

4、消息推送接口 ​

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

接收参数：

此接口可根据消息类型增加任意参数。新增加的参数要参与 sign 签名。

返回值示例：

• 推送成功时：

{
    "code": 200,
    "msg": "ok",
    "data": "10001",	// 返回的数据 
}

• 推送失败时：

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

详细可参考：消息推送机制