智融集成平台文档

主题

04 — SSO 接入（门户作 IdP） ​

第三方应用信任门户签发的身份，实现单点登录。本文为实用端点清单；完整方案、安全与分期见 doc/07-单点登录方案.md。

前提：用户须已在门户 sys_user 开户；Client 已在 sys_sso_client 注册（见 01-接入准备.md）。

1. 协议选型 ​

协议门户角色Client protocol典型用途
OAuth 2.0授权服务端OAUTH2（默认）授权码换 opaque access_token，调 userinfo / 开放 API
OIDC同上 + Discovery / JWKS / id_tokenOIDC需要标准 OIDC 客户端、JWT id_token（RS256）
CAS 3.0CAS ServerCAS传统 CAS Client；须部署授权功能码 sso.cas
SAML 2.0IdPSAMLSP 对接 AD FS 等；配置 entity_id / acs_urls

access_token 为 Sa-Token opaque（存 Redis），不是 JWT。OIDC 时仅额外的 id_token 为 JWT。

不支持：grant_type=client_credentials（Discovery grant_types_supported 仅为 authorization_code、refresh_token）。

2. OAuth2 / OIDC 端点 ​

方法路径说明
GET/.well-known/openid-configurationOIDC Discovery（issuer、authorize/token/userinfo/jwks、scopes 等）
GET/oauth2/jwksJWKS 公钥（验 id_token）
GET/oauth2/authorize授权码入口；须已登录门户会话
POST/oauth2/doConfirm用户同意授权（consent_mode 需要时）
POST/oauth2/tokencode 换 token（application/x-www-form-urlencoded）
POST/oauth2/refresh刷新 access_token
POST/oauth2/revoke回收 token
GET/oauth2/userinfo用户信息；Token 须含 profile
POST/oauth2/introspectToken 自省；含 permissions 时返回权限快照

授权码流程（摘要） ​

  1. 浏览器访问
    GET /oauth2/authorize?response_type=code&client_id=...&redirect_uri=...&scope=...&state=...
    （OIDC 建议带 nonce；scope 含 openid）
  2. 未登录 → 302 门户登录；需确认 → /oauth2/consent.html
  3. 成功 → 302 redirect_uri?code=...&state=...
  4. 服务端 POST /oauth2/token：
    grant_type=authorization_code&code=...&redirect_uri=...&client_id=...&client_secret=...
    （或 Basic：Authorization: Basic base64(client_id:client_secret)）
  5. redirect_uri 须与 authorize 时完全一致，且在 Client 白名单 + 授权域内。

Scope（开放 API 相关） ​

scope可访问
profile/oauth2/userinfo
permissionsintrospect 扩展 roleCodes / permissions
api:read/api/open/** 只读（当前主要为任务查询）
api:write/api/open/** 写（任务创建等；蕴含读）
openidOIDC：Token 响应含 JWT id_token

OAuth2 Token 禁止访问 /api/system/* 等门户业务管理 API。任务中心细节见 03-任务中心-OAuth2.md；设计表见 doc/07 §4.6。

Token 换票 curl 示意 ​

bash
curl -sS -X POST "https://portal.example.com/oauth2/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "code=AUTHORIZATION_CODE" \
  -d "redirect_uri=https://app.example.com/oauth/callback" \
  -d "client_id=demo-client" \
  -d "client_secret=YOUR_SECRET"

3. CAS 端点 ​

方法路径说明
GET/POST/cas/login?service={url}登录并签发 ST，302 至 service?ticket=ST-...
GET/POST/cas/logout销毁门户会话；可选 service 回跳
GET/cas/p3/serviceValidate?service=...&ticket=...校验 ST，返回 CAS XML（一次性）

Client 侧登记允许的 service URL（协议扩展 / redirect 配置）。未授权功能码时 validate 返回 LICENSE 失败 XML。

4. SAML IdP 端点 ​

方法路径说明
GET/saml/idp/metadataIdP 元数据 XML
GET/POST/saml/idp/ssoSSO（携带 SAMLRequest）
GET/POST/saml/idp/slo单点登出

Client protocol=SAML 时配置 entity_id、acs_urls 等（见创建 Client 请求字段）。默认 EntityID 形态：{issuer}/saml/idp。

5. 与开放 API / 出向的关系 ​

能力是否用本 Token
/api/open/tasks/**是（需 api:* scope）
/api/open/matters/**否（HMAC，见 02）
接收组织用户出向推送无 Token；你方暴露 HTTP，见 05

管理端配置 Client / 出向：/api/sso/clients、/api/sync/** 仍属门户运维面，第三方不直接调用。

6. 对接检查清单 ​

  1. Client：redirect_uris / 授权域 / scopes / protocol 正确；生产 HTTPS。
  2. OIDC：拉取 Discovery 与 JWKS；校验 id_token 的 iss/aud/nonce。
  3. CAS：service URL 与 validate 时一致。
  4. SAML：交换元数据，ACS 与门户配置一致。
  5. 需要调任务开放 API：authorize 时申请 api:write（或 api:read）。

细节与分期以 doc/07-单点登录方案.md 为准；若与本文冲突，以代码与 Knife4j 为准，并提请更新本目录。

7. 下载 Demo ​