河岸边通行证 OAuth2 / OIDC / SSO

Docs

接入文档

OAuth 2.1 / OpenID Connect 河岸边通行证 · 面向第三方应用的标准接入指南

Developer Guide

本文档说明如何将第三方应用接入河岸边通行证。协议实现遵循 OAuth 2.1 与 OpenID Connect Core 1.0；客户端由管理员开通（管理后台或 Admin API），不提供公网自助注册。

快速开始

  1. 阅读 授权码 + PKCE（推荐主路径）。
  2. 联系管理员创建客户端，获取 client_id / client_secret，并登记 redirect_uri。
  3. 使用 POST /api/v1/integration/validate-redirect 校验回调地址规则。
  4. 按文档完成授权、换票、UserInfo；按需配置 统一登出。
默认安全策略：新建客户端默认启用 PKCE（S256）与 Refresh Token 轮换；生产环境回调请使用 HTTPS。

服务发现

优先通过标准 Discovery 动态解析端点，避免硬编码：

用途 URL
Issuer https://login.heanbian.com
OIDC Discovery https://login.heanbian.com/.well-known/openid-configuration
AS Metadata https://login.heanbian.com/.well-known/oauth-authorization-server
接入元数据（本系统） /api/v1/integration/meta

端点一览

端点 地址
Authorization https://login.heanbian.com/oauth2/authorize
Token https://login.heanbian.com/oauth2/token
JWKS https://login.heanbian.com/oauth2/jwks
UserInfo https://login.heanbian.com/userinfo
UserInfo（兼容） https://login.heanbian.com/oauth2/userinfo
Revocation https://login.heanbian.com/oauth2/revoke
Introspection https://login.heanbian.com/oauth2/introspect
Device Authorization https://login.heanbian.com/oauth2/device_authorization
Device Verification https://login.heanbian.com/activate
End Session https://login.heanbian.com/oauth2/logout

支持的授权类型

流程 推荐 说明 文档
Web / 后端授权码 + PKCE 是 推荐主路径。机密客户端使用 client_secret，并强制 PKCE（S256）。 查看
设备码授权 否 适用于电视、CLI 等难以嵌入浏览器的设备。用户在 /activate 输入用户码完成授权。 查看
客户端凭证 否 服务间调用，无最终用户。需创建客户端时显式开启。 查看

支持的 grant： authorization_code, refresh_token, urn:ietf:params:oauth:grant-type:device_code, client_credentials

response_type： code ；PKCE： S256 ；Token 认证： client_secret_basic, client_secret_post

客户端开通

  • 管理后台：客户端管理。
  • Admin API：POST /api/v1/admin/clients（管理员会话 + CSRF）。
  • 明文 client_secret 仅在创建与重置时返回一次，请安全保存。

公开 / 管理 API

公开 Integration API

  • GET /api/v1/integration/meta — 端点与默认策略
  • GET /api/v1/integration/scopes — Scope 与声明映射
  • GET /api/v1/integration/flows — 推荐流程
  • POST /api/v1/integration/validate-redirect — 回调 / 登出回调 URI 校验

Admin API

  • GET/POST /api/v1/admin/clients
  • GET/PUT /api/v1/admin/clients/{registeredClientId}
  • POST /api/v1/admin/clients/{registeredClientId}/reset-secret
  • POST /api/v1/admin/clients/{registeredClientId}/toggle
  • POST /api/v1/admin/clients/{registeredClientId}/delete
下一步：授权码 + PKCE →