📝 前言

在企业和组织中，多应用、多系统的场景非常普遍。

如果每个应用都独立管理用户登录，用户体验差，安全性也难以保证。

青萍统一认证平台基于标准 OIDC（OpenID Connect）协议，实现集中身份管理和统一登录。

本文将以应用对接为核心，详细说明如何接入青萍统一认证平台，实现统一认证与单点登录。

🧭 背景介绍

在没有统一认证平台的情况下，每个应用都需要单独维护用户账户和密码：

• 用户需要记住多个账号和密码
• 企业难以统一管理权限和审计
• 系统间无法实现统一会话

青萍统一认证平台作为 集中式身份认证服务，支持多种外部身份源（如 GitHub、Notion、微信），通过标准 OIDC 协议向应用提供认证服务，使企业可以：

• 集中管理用户身份和权限
• 提升用户体验（统一登录、退出）
• 支持安全审计和访问控制

📌 最终目标

通过接入青萍统一认证平台，应用能够：

• 提供统一登录入口
• 使用 ID Token 验证用户身份
• 可选支持 Access Token 调用后端 API
• 支持刷新 Token 及单点登出

📋 前提条件

• 需要申请接入青萍商业平台

可添加V联系：lusyoe

🖼️ 接入流程图

🚀 详细接入步骤

1️⃣ 获取客户端信息

在审核通过后，平台会提供以下信息：

2️⃣ 应用发起登录请求

应用将用户浏览器重定向到青萍统一认证平台的 /auth：

1
2
3
4
5
6

GET https://auth.lusyoe.com/auth?
  client_id=myapp&
  redirect_uri=https://myapp.example.com/callback&
  response_type=code&
  scope=openid+profile+email&
  state=random123

参数说明：

• client_id：应用 ID
• redirect_uri：回调地址
• response_type=code：使用授权码模式
• scope：请求用户信息范围
• state：防止 CSRF 攻击的随机值

3️⃣ 用户登录与回调

用户在青萍统一认证平台完成登录后，浏览器被重定向回应用回调地址，并携带授权码：

1

https://myapp.example.com/callback?code=abc123&state=random123

应用后端需：

1. 校验 state 参数与请求时一致
2. 提取 code

PS：在登录成功后，平台会将 token 直接写入 cookie，因此也可以省去交换 token 这一步，直接校验 cookie 中的 token 即可。

4️⃣ 应用向统一认证平台交换 Token（可选）

在上一步平台已将token写入根域名的cookie中了，这里也可以省去。

应用后端使用授权码向青萍 /token 接口请求 Token：

1
2
3
4
5
6
7
8
9

POST https://auth.lusyoe.com/token
Content-Type: application/x-www-form-urlencoded

client_id=myapp&
client_secret=myapp-secret&
code=abc123&
grant_type=authorization_code&
redirect_uri=https://myapp.example.com/callback

返回示例：

1
2
3
4
5
6
7

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR...",
  "id_token": "eyJhbGciOiJSUzI1NiIsInR...",
  "refresh_token": "9sdfjsdf8dsf7sdf...",
  "token_type": "Bearer",
  "expires_in": 3600
}

5️⃣ 验证 token

可从cookie中读取id_token，ID Token 是 JWT，需要验证：

• 签名是否正确（使用JWKS接口：https://auth.lusyoe.com/keys）
• iss 是否为 https://auth.lusyoe.com
• aud 是否包含 Client ID
• exp 是否过期

示例（Python）：

1
2
3
4
5
6
7
8
9
10
11
12
13

import jwt
import requests

jwks = requests.get("https://auth.lusyoe.com/keys").json()
public_keys = {k["kid"]: jwt.algorithms.RSAAlgorithm.from_jwk(k) for k in jwks["keys"]}

token = "eyJhbGciOiJSUzI1NiIsInR..."
header = jwt.get_unverified_header(token)
key = public_keys[header["kid"]]

payload = jwt.decode(token, key=key, algorithms=["RS256"], audience="myapp")
print(payload)

6️⃣ 建立应用会话（可选）

验证 ID Token 成功后：

• 建立本地 session 或 JWT
• 将用户信息（email、username 等）存储到数据库/缓存
• 前端显示登录状态

也可以直接使用平台的 cookie token，不建立自己的会话和用户管理。

7️⃣ 获取用户信息

默认 token 中仅包含基础信息，若想获取更完整的用户信息可调用平台的/userinfo接口。

需要携带上 cookie 中的 access_token：

1
2

GET https://auth.lusyoe.com/userinfo
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR...

应用可以使用这些信息建立用户会话、设置权限和显示用户资料。

8️⃣ 统一退出处理

当应用想要退出登录时，如果有建立自己的会话可先清理自己的会话，然后重定向至统一认证平台的退出登录页面，进行统一退出处理，地址如下：

1
2
3
4

GET https://auth.lusyoe.com/logout?
  client_id=myapp&
  post_logout_redirect_uri=https://myapp.lusyoe.com&
  id_token_hint=eyJhbGciOiJ...

参数说明：

• client_id: 应用 ID
• post_logout_redirect_uri: 退出登录后跳转的页面，需在平台注册，与上面的redirect_uri 一致。
• id_token_hint: 用于校验 token 是否合法，需携带 cookie 中的 id_token。

PS：若 cookie 过期（24小时），token 不存在时（后端判断），无需跳转统一退出页面。

9️⃣ 页面查看用户详细信息

如想查看用户的详细信息如：订阅到期时间，修改密码，绑定第三方账户登录。

可以直接跳转至：https://auth.lusyoe.com/profile 页面

✅ 总结

通过本文的步骤，应用成功接入了青萍统一认证平台，实现了标准化的 OIDC 认证流程。

整个接入过程包括：

1. 注册应用：在申请审核通过后，平台提供 Client ID 和 Client Secret。
2. 发起登录请求：用户访问应用时重定向至青萍认证端点进行登录。
3. 授权码回调：用户完成认证后，应用接收授权码。
4. **交换 Token(可选)**：应用后端通过授权码获取 ID Token、Access Token 和可选 Refresh Token。
5. 验证 ID Token：确保 Token 来源可信、未过期，并包含正确的受众信息。
6. 获取用户信息：通过 /userinfo 接口获取详细用户数据，用于会话和权限管理。
7. 会话管理（可选）：建立本地会话或 JWT，实现应用登录状态。
8. 可选操作：包括刷新 Token 与单点登出，支持长期登录和安全退出。

通过接入青萍统一认证平台，应用能够实现：

• 统一身份认证：多个应用共享同一套用户管理体系
• 单点登录（SSO）：用户只需一次登录即可访问所有接入应用
• 安全与审计：统一管理 Token、权限和访问日志
• 用户体验优化：减少多账号密码的负担

总体而言，接入青萍统一认证平台不仅简化了应用的认证流程，还提升了系统安全性和用户体验，是企业多应用场景下的最佳实践。