接入文档

SilkPortal 基于 OAuth 2.0 + OpenID Connect 标准协议，提供统一的身份认证服务。

一、概述

SilkPortal 是一个轻量级 SSO（单点登录）系统，支持以下标准协议：

OAuth 2.0 Authorization Code 流程 — 授权码模式，最安全的授权方式
PKCE（Proof Key for Code Exchange） — 增强安全性，防止授权码拦截攻击
OpenID Connect — 基于 OAuth 2.0 的身份认证层，提供 ID Token
Refresh Token — 支持令牌刷新，延长会话有效期

二、创建应用

登录后进入我的应用页面创建应用，获取以下凭据：

client_id — 应用唯一标识
client_secret — 应用密钥（请妥善保存）
redirect_uri — 授权回调地址，需提前配置

三、认证流程

1. 构造授权链接

GET http://auth.qaqan.cn/authorize?
  response_type=code
  client_id=<your_client_id>
  redirect_uri=<your_redirect_uri>
  scope=openid%20email
  state=<random_state>
  code_challenge=<S256_challenge>&code_challenge_method=S256

2. 用户登录并授权

用户将被重定向到 SilkPortal 登录页面，登录后用户确认授权，浏览器将重定向回您的应用：

GET <your_redirect_uri>?code=<auth_code>&state=<original_state>

3. 换取令牌

使用授权码向令牌端点发起 POST 请求：

POST http://auth.qaqan.cn/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
code=<auth_code>
redirect_uri=<your_redirect_uri>
client_id=<your_client_id>
client_secret=<your_client_secret>
code_verifier=<original_code_verifier>

4. 获取用户信息

使用 access_token 调用 UserInfo 端点：

GET http://auth.qaqan.cn/userinfo
Authorization: Bearer <access_token>

返回示例：

{
  "sub": "user_xxx",
  "email": "user@example.com",
  "name": "用户名"
}

四、端点列表

端点	说明	方法
`/authorize`	OAuth 授权端点	GET
`/token`	OAuth 令牌端点	POST
`/userinfo`	用户信息端点	GET
`/.well-known/jwks.json`	JWK 公钥端点	GET
`/login`	用户登录页面	GET/POST
`/logout`	退出登录	GET

五、curl 示例

获取 JWK 公钥

curl -s http://auth.qaqan.cn/.well-known/jwks.json | jq

验证 ID Token

ID Token 是 RS256 签名的 JWT，可使用 JWK 端点获取公钥进行验证。
Token 中包含 iss、sub、aud、exp、email、name 等声明。