OAuth2 + OIDC 统一认证授权中心文档

项目概述 👇🏼

OAuth2 + OIDC 统一认证授权中心为您的应用提供安全的身份认证和API授权的IAM核心基础设施。本服务支持多种授权模式，包括授权码模式、客户端凭证模式、刷新令牌模式等，同时提供符合OpenID Connect标准的用户信息端点。

通过本认证授权中心，您可以轻松实现独立的用户管理中心、API访问控制、多系统单点登录(SSO)等功能，同时确保用户数据的安全性和隐私保护。

典型应用场景:
1. 企业内部统一身份门户、单点登录SSO与统一用户管理
2. 开放平台第三方应用授权
3. 多租户SaaS服务认证中心
4. 微服务架构API安全网关

安全可靠

采用行业标准协议，支持PKCE增强安全、JWT签名验证、加密传输、令牌吊销、多因素认证MFA等安全机制

多种模式

支持授权码模式、客户端凭证模式、刷新令牌模式模式、设备码授权等多种OAuth2认证授权流程

符合标准

完全兼容OAuth 2.0和OpenID Connect标准，易于与各种系统集成

高性能

分布式与持久化架构设计，支持高并发请求，毫秒级响应时间

OAuth2 标准API接口端点 🔍

统一认证授权域名: https://oauth2.pengbocloud.com

授权码模式端点

GET /oauth2/authorize

认证授权

单点登录SSO授权流程(未登录先跳转统一的登录页面授权)，重定向回客户端获取授权码code，再用code获取访问token

请求参数 (URL传参)

参数	类型	必填	描述说明	默认值	参考值	备注
response_type	string	是	授权码code	code
client_id	string	是	客户端ID
redirect_uri	string	是	客户端回调地址			#哈希路由不支持
scope	string	是	请求的权限范围		openid profile email phone	多个组合空号分隔
state	string	是	防CSRF攻击令牌			客户端唯一随机数
code_challenge_method	string	按需	客户端code算法		S256	PKCE安全模式建议SHA256算法
code_challenge	string	按需	客户端code		BASE64URL(SHA256(code_verifier))	PKCE安全模式(仅客户端保存)

响应示例

登录与授权同意后，浏览器重定向回调地址示例(附带code授权码): https://client.com/callback?code=一次性授权码&state=客户端生成的状态值

发放令牌端点

POST /oauth2/token

发放令牌

使用授权码交换访问令牌, 默认旧的token依然有效, 若要旧token立刻失效使用refresh_token接口

请求头 ( 二选一: client_secret_basic 与 client_secret_post )

Authorization: Basic base64(client_id:client_secret)

请求参数 (使用 application/x-www-form-urlencoded 编码)

参数	类型	必填	描述说明	参考值/备注
grant_type	string	是	授权类型	authorization_code 、client_credentials
code	string	按需	授权码
client_id	string	按需	客户端ID	client_secret_post方法必填
client_secret	string	按需	客户端明文密钥	client_secret_post方法必填
redirect_uri	string	按需	重定向定地址	authorization_code模式必填
code_verifier	string	按需	客户端原始code	PKCE安全模式

响应示例

{
  "access_token": "授权资源的访问令牌",
  "id_token": : "OIDC模式下返回的ID令牌 存储用户信息 sub是用户唯一标识",
  "token_type": "Bearer",
  "expires_in": 7200, // 令牌有效期 (秒)
  "refresh_token": "刷新令牌 用于获取新的访问令牌",
  "scope": "openid profile email phone"
}

刷新令牌端点

POST /oauth2/token

刷新令牌

使用刷新令牌获取新的访问令牌, SAS默认获取后旧的access_token与refresh_token立刻自动失效

请求头 ( 二选一: client_secret_basic 与 client_secret_post )

Authorization: Basic base64(client_id:client_secret)

请求参数 (使用 application/x-www-form-urlencoded 编码)

参数	类型	必填	描述说明	默认值	参考值/备注
grant_type	string	是	授权类型	refresh_token
refresh_token	string	是	刷新令牌
client_id	string	按需	客户端ID		client_secret_post方法必填
client_secret	string	按需	客户端明文密钥		client_secret_post方法必填
scope	string	否	请求权限范围		openid profile email phone

响应示例

{
  "access_token": "授权资源的访问令牌",
  "id_token": : "OIDC模式下返回的ID令牌 存储用户信息 sub是用户唯一标识",
  "token_type": "Bearer",
  "expires_in": 7200, // 令牌有效期 (秒)
  "refresh_token": "刷新令牌 用于获取新的访问令牌",
  "scope": "openid profile email phone"
}

用户信息端点

GET /userinfo

用户信息

获取当前认证用户的详细信息

请求头

Authorization: Bearer ACCESS_TOKEN

响应示例


{
    "sub": "用户唯一标识",
    "name": "admin", // 登录用户名
    "preferred_username": "张三", // 首选用户名
    "gender": "1", //  性别 1:男 2:女
    "updated_at": "2025-09-02 16:12:35",
    "roles": "ADMIN,USER",
    "email": "zhangsan@example.com",
    "email_verified": true,
    "phone_number": "18888888888",
    "phone_number_verified": true
}

客户端凭证授权端点

POST /oauth2/token

客户端凭证

获取客户端凭证信息适用于服务器与服务器之间的软件互信交互

请求头 ( 二选一: client_secret_basic 与 client_secret_post )

Authorization: Basic base64(client_id:client_secret)

请求参数 (使用 application/x-www-form-urlencoded 编码)

参数	类型	必填	描述说明	默认值	备注
grant_type	string	是	授权类型	client_credentials
client_id	string	按需	客户端ID		client_secret_post方法必填
client_secret	string	按需	客户端明文密钥		client_secret_post方法必填

响应示例

{
    "access_token": "访问授权令牌",
    "token_type": "Bearer",
    "expires_in": 7200 // 令牌有效期 (秒)
}

令牌校验内省端点

POST /oauth2/introspect

令牌校验

验证当前访问token信息如是否有效签发用户过期时间等

请求头 ( 二选一: client_secret_basic 与 client_secret_post )

Authorization: Basic base64(client_id:client_secret)

请求参数 (使用 application/x-www-form-urlencoded 编码)

参数	类型	必填	描述说明	备注
token	string	是	access_token或refresh_token或id_token
client_id	string	按需	客户端ID	client_secret_post方法必填
client_secret	string	按需	客户端明文密钥	client_secret_post方法必填

响应示例

{
    "active": true, // 是否有效 失效只返回这一个字段 为false
    "sub": "admin",
    "aud": [
        "oidc-client"
    ],
    "nbf": 1756350268,
    "scope": "address phone openid profile email",
    "iss": "http://127.0.0.1:9000",
    "exp": 1756357468, // 令牌过期时间 (秒)
    "iat": 1756350268, // 令牌签发时间 (秒)
    "jti": "602df3fe-2c2b-410b-8ca7-6955a271e907",
    "client_id": "oidc-client",
    "token_type": "Bearer"
}

令牌撤销端点

POST /oauth2/revoke

令牌撤销

撤销access token 或 refresh token令牌有效性立刻生效

请求头 ( 二选一: client_secret_basic 与 client_secret_post )

Authorization: Basic base64(client_id:client_secret)

请求参数 (使用 application/x-www-form-urlencoded 编码)

参数	类型	必填	描述说明	参考值	备注
token	string	是	要撤销访问token或刷新token
token_type_hint	string	否	令牌类型提示	access_token、refresh_token
client_id	string	按需	客户端ID		client_secret_post方法必填
client_secret	string	按需	客户端明文密钥		client_secret_post方法必填

响应示例


HTTP 200状态码, 表示撤销成功 (无正文或空JSON)

前端通道登出端点

GET /logout/connect

前端通道登出

OIDC注销 RP-Initiated Logout前端通道单点登出SLO 浏览器调用访问销毁登录Session与Token

请求头

无

请求参数 (使用 application/x-www-form-urlencoded 编码)

参数	类型	必填	描述说明	备注
id_token_hint	string	是	用户id_token值	参考/connect/logout设计
post_logout_redirect_uri	string	否	登出回调地址	默认统一登录页

响应示例


浏览器重定向回调配置的登出地址

后端通道登出端点

POST /logout/oidc

后端通道登出

OIDC注销 OP-Initiated Logout后端通道单点登出SLO 调用API请求销毁登录Session与Token

请求头

Authorization: Bearer ACCESS_TOKEN

响应示例


{
    "code": 200, // 200状态码代表成功 其它代表失败 参考HTTP状态码设计
    "data": null,
    "msg": "退出登录成功"
}

JWKS公钥端点

GET /oauth2/jwks

JWKS公钥

JSON Web Key Set公钥集合作用是安全地分发用于验证JWT和ID Token等有效性签名的公钥

响应示例

{
    "keys": [
        {
        "kty": "RSA",
        "e": "AQAB",
        "kid": "02cf8312-7934-4ade-a91c-1d57f4a7360c",
        "n": "ux_2cBGDm7hGQhBetopncf_GsLAET70tn9LjQI-EFsPoOZyYHLLaSocdyu1-W-tAFkx1jfjSmwHXEK0lpNXpwDGHMx9FX8B2TrxTLTiyvHRm05HiyW9-2R4mA_qxgeBwZvDkXaZQyGix2s_g6mmAlmRlAiORFUwNAMWqguGaRL5YsishZXLsDEMNpm_g7ypM5ApljhEwsdlnBRoABg7Hbaob9TVuDgSOlVEGP3jwWkz5UceUk-ItFtROzQ086kNP8GuEHCXw5u-YBFkrIc3xQUafGqTi95cHEi45zH0oINKI7_6NxP"
        }
    ]
}

服务发现端点

GET /.well-known/openid-configuration

发现服务

获取授权服务器OpenID Connect配置信息

响应示例

{
  "issuer": "https://auth.example.com",
  "authorization_endpoint": "https://auth.example.com/oauth2/authorize",
  "token_endpoint": "https://auth.example.com/oauth2/token",
  "userinfo_endpoint": "https://auth.example.com/oauth2/userinfo",
  "jwks_uri": "https://auth.example.com/.well-known/jwks.json",
  "revocation_endpoint": "https://auth.example.com/oauth2/revoke",
  "introspection_endpoint": "https://auth.example.com/oauth2/introspect",
  "grant_types_supported": [
      "authorization_code"",
      "client_credentials",
      "refresh_token"
  ],
  "scopes_supported": [
      "openid",
      "profile",
      "email",
      "phone",
      "read",
      "write"
  ],
  "token_endpoint_auth_methods_supported": [
      "client_secret_basic",
      "client_secret_post",
  ]
  "subject_types_supported": ["public"],
  "id_token_signing_alg_values_supported": ["RS256"]
}

OAuth2统一认证授权流程图 💡

sequenceDiagram participant 用户 participant 客户端应用 participant 授权服务器 participant 资源服务器用户->>客户端应用: 1.请求访问资源客户端应用->>授权服务器: 2.重定向至授权页(含client_id/redirect_uri/scope) 用户->>授权服务器: 3.单点登录SSO并同意授权授权服务器->>客户端应用: 4.重定向回Client(携带授权码code) 客户端应用->>授权服务器: 5.传递授权码用code换取access_token(附client_secret) 授权服务器->>客户端应用: 6.返回access_token和id_token 客户端应用->>资源服务器: 7.用access_token请求资源(第三方软件服务) 资源服务器->>客户端应用: 8.返回受保护数据

第三方对接指南 🔑

注册客户端应用

在接入前，您需要注册您的客户端应用以获取 client_id 和 client_secret。

对接流程

选择适合的授权模式（Web应用推荐授权码模式）
配置重定向URI（必须与注册时一致）
实现授权流程（参考流程图）
处理令牌响应并存储
使用访问令牌请求受保护资源
实现令牌刷新逻辑

安全建议

使用HTTPS传输所有请求
安全存储client_secret（不要暴露在客户端）
使用PKCE增强移动端和SPA应用安全
验证state参数防止CSRF攻击
设置合理的令牌有效期
定期轮换客户端密钥
实施令牌吊销机制

⚠️ 重要提示

请勿将敏感数据（如client_secret）暴露在客户端代码中。对于单页应用(SPA)和移动应用，请使用PKCE扩展增强安全性。

项目概述 👇🏼

安全可靠

多种模式

符合标准

高性能

OAuth2 标准API接口端点 🔍

统一认证授权域名: https://oauth2.pengbocloud.com

授权码模式端点

请求参数 (URL传参)

响应示例

发放令牌端点

请求头 ( 二选一: client_secret_basic 与 client_secret_post )

请求参数 (使用 application/x-www-form-urlencoded 编码)

响应示例

刷新令牌端点

请求头 ( 二选一: client_secret_basic 与 client_secret_post )

请求参数 (使用 application/x-www-form-urlencoded 编码)

响应示例

用户信息端点

请求头

响应示例

客户端凭证授权端点

请求头 ( 二选一: client_secret_basic 与 client_secret_post )

请求参数 (使用 application/x-www-form-urlencoded 编码)

响应示例

令牌校验内省端点

请求头 ( 二选一: client_secret_basic 与 client_secret_post )

请求参数 (使用 application/x-www-form-urlencoded 编码)

响应示例

令牌撤销端点

请求头 ( 二选一: client_secret_basic 与 client_secret_post )

请求参数 (使用 application/x-www-form-urlencoded 编码)

响应示例

前端通道登出端点

请求头

请求参数 (使用 application/x-www-form-urlencoded 编码)

响应示例

后端通道登出端点

请求头

响应示例

密码管理端点

请求头

响应示例

JWKS公钥端点

响应示例

服务发现端点

响应示例

OAuth2统一认证授权流程图 💡

第三方对接指南 🔑

注册客户端应用

对接流程

安全建议

⚠️ 重要提示