单点登录 (SSO) 🔑

功能介绍 💡

INFO

SSO（Single Sign-On）过滤器用于实现单点登录功能，允许第三方应用通过临时 Token 安全地获取用户的登录凭证（Authorization）。

🎯 核心功能

• 🔄 生成临时 Token - 为第三方应用生成一次性的临时访问令牌
• ✅ 验证临时 Token - 验证令牌有效性并交换用户真实凭证
• 🛡️ 安全防护 - 支持客户端 ID/Secret 验证、回调地址校验、防 CSRF 攻击
• ⏱️ 时效控制 - 支持自定义 Token 过期时间

🛡️ 应用场景

• 第三方应用接入 - 允许合作伙伴系统无缝登录
• 多系统互联 - 集团内部不同系统间的用户免登跳转
• 临时授权 - 给予外部系统临时的资源访问权限

详细配置说明 ⚙️

核心参数说明

在 application.yml 中配置 gateway.filter.sso：

参数名	类型	必填	默认值	说明
enabled	boolean	否	false	是否启用 SSO 过滤器
rules	array[object]	是	-	SSO 规则配置列表

规则配置详解 (rules)

参数名	类型	必填	默认值	说明
name	string	否	-	规则名称，用于日志标识
generate-urls	array[string]	是	-	生成 Token 的接口路径列表（支持 AntPathMatcher）
verify-urls	array[string]	是	-	验证 Token 的接口路径列表（支持 AntPathMatcher）
business-key	string	否	bearer	业务 Key，用于区分不同业务线或 Token 前缀
client-id	string	是	-	客户端 ID，用于身份识别
client-secret	string	是	-	客户端密钥，用于验证 Token 时校验身份
redirect-uri	string	是	-	允许的回调地址，必须严格匹配
expire	string	否	10m	临时 Token 有效期，支持时间单位（如 5m, 1h）
response-data-authorization	boolean	否	false	验证响应中是否包含授权 Token
response-data-user	boolean	否	false	验证响应中是否包含用户信息（ID、昵称、头像）

配置示例 📝

基础配置示例

gateway:
  filter:
    sso:
      enabled: true
      rules:
        - name: "默认SSO规则"
          generate-urls:
            - "/auth/sso/generate"
          verify-urls:
            - "/auth/sso/verify"
          business-key: "bearer"
          client-id: "my-client-id"
          client-secret: "my-client-secret"
          redirect-uri: "http://localhost:8080/callback"
          expire: "5m"
          response-data-authorization: true
          response-data-user: true

使用流程 🚀

1. 生成 SSO Token 🎫

第三方应用引导用户访问生成 Token 的接口，需携带当前用户的登录态（Authorization Header）。

• 接口地址: 配置在 generate-urls 中的路径，例如 /auth/sso/generate
• 请求方式: GET

请求头 (Header):

• Authorization: 用户登录凭证（必填）

请求参数 (Query):

参数名	必选	说明
clientId	是	客户端 ID，必须与配置一致
redirectUri	是	回调地址，必须与配置一致
state	否	随机字符串，用于防止 CSRF 攻击，原样返回

响应结果:

成功时返回 JSON，包含拼接了 code 和 state 的回调 URL。

{
  "code": 0,
  "msg": "success",
  "data": {
    "uri": "http://localhost:8080/callback?code=bearer:uuid&state=xyz"
  }
}

2. 验证 SSO Token 🔐

第三方应用在回调地址接收到 code 后，调用验证接口换取用户的 Authorization。

• 接口地址: 配置在 verify-urls 中的路径，例如 /auth/sso/verify
• 请求方式: GET

请求参数 (Query):

参数名	必选	说明
clientId	是	客户端 ID
clientSecret	是	客户端密钥
code	是	第一步获取到的临时 Token

响应结果:

成功时返回用户的 Authorization 和用户信息（根据配置）。

{
  "code": 0,
  "msg": "success",
  "data": {
    "authorization": "Bearer eyJhbGciOiJIUzI1Ni...",
    "userId": "123456",
    "nickname": "Admin",
    "avatarUrl": "http://example.com/avatar.jpg"
  }
}

常见问题 ❓

1. 为什么验证 Token 失败？

   • 检查 clientSecret 是否正确。
   • 检查 code 是否已过期（默认 10 分钟）。
   • 检查 code 是否已被使用过（Token 是一次性的）。

2. redirectUri 报错？

   • 回调地址必须与配置文件中的 redirect-uri 完全一致（包括 http/https 协议和端口）。

3. state 参数的作用？

   • 建议始终携带 state 参数（如随机字符串），并在回调时验证，以防止跨站请求伪造（CSRF）攻击。