开发者教程

本页提供：系统简介、业务站接入步骤、OAuth2/Token、WeCom 登录、常见错误排查。

一、系统简介

• 协议：OAuth2 授权码（/oauth/authorize → /oauth/token），签发 access_token / refresh_token；支持 /userinfo。
• 登录方式：验证码登录、企业微信扫码/静默。
• 数据库：核心表 sso_users / sso_applications / sso_auth_codes / sso_tokens / sso_sessions。

二、业务站接入（最小步骤）

1. 在“应用管理”创建应用，记下 client_id/client_secret，填写“主回调”和“允许回调”。
2. 业务站发起：

   GET /oauth/authorize?client_id=APP_xxx&redirect_uri={urlencode(回调)}&response_type=code&scope=basic&state=随机
   Host: SSO

3. 回调后，用授权码换令牌：

   POST /oauth/token
   Content-Type: application/x-www-form-urlencoded
   
   grant_type=authorization_code&code=xxx&redirect_uri=原回调&client_id=APP_xxx&client_secret=***

4. 验证 JWT（HS256，密钥=应用的 client_secret），再以 Authorization: Bearer {access_token} 调 /userinfo。

三、企业微信

• 扫码：使用企业微信开放平台 SSO 二维码，回调 /login/wecom/qr/callback。
• 静默：浏览器 UA 为企业微信时走 /login/wecom/silent。

四、错误排查

• invalid_redirect_uri：回调地址需在“允许回调”白名单（换行/逗号分隔）。
• 500 + SQL 列错误：检查表结构是否和控制器 SQL 名称一致。
• 扫码后不跳：确认 /login/wecom/status 接口能返回 {"ok":1}，以及回调域与 Cookie 域一致。

更多细节可查看 /debug 自检页。