OAuth2.1 授权服务器配置
你好呀，我的老朋友！我是老寇，欢迎来到老寇IoT云平台！
本文档详细介绍了 OAuth2AuthorizationServerProperties 配置类的所有配置项，包括说明、类型、默认值和配置示例。
# 配置前缀
spring:
security:
oauth2:
authorization-server:
# 所有配置项都在此前缀下
# 1. 基础配置
# 配置项说明
| 配置项 | 类型 | 默认值 | 说明 |
|---|---|---|---|
enabled | boolean | true | 是否启用授权服务器 |
issuer | String | null | 授权服务器的 Issuer 标识符 URL |
multiple-issuers-allowed | boolean | false | 是否允许每个主机有多个 Issuer（用于多租户配置） |
# 配置示例
spring:
security:
oauth2:
authorization-server:
enabled: true
issuer: https://auth.example.com
multiple-issuers-allowed: false
# 2. 端点配置 (Endpoint)
# OAuth 2.0 端点
| 配置项 | 类型 | 默认值 | 说明 |
|---|---|---|---|
endpoint.authorization-uri | String | /v1/oauth2/authorize | OAuth 2.0 授权端点 |
endpoint.device-authorization-uri | String | /v1/oauth2/device_authorization | 设备授权端点 |
endpoint.device-verification-uri | String | /v1/oauth2/device_verification | 设备验证端点 |
endpoint.token-uri | String | /v1/oauth2/token | Token 端点 |
endpoint.jwk-set-uri | String | /v1/oauth2/jwks | JWK Set 端点 |
endpoint.token-revocation-uri | String | /v1/oauth2/revoke | Token 撤销端点 |
endpoint.token-introspection-uri | String | /v1/oauth2/introspect | Token 自省端点 |
endpoint.pushed-authorization-request-uri | String | /v1/oauth2/par | PAR（推送授权请求）端点 |
# OpenID Connect 1.0 端点
| 配置项 | 类型 | 默认值 | 说明 |
|---|---|---|---|
endpoint.oidc.logout-uri | String | /v1/oidc/connect/logout | OIDC 登出端点 |
endpoint.oidc.client-registration-uri | String | /v1/oidc/connect/register | OIDC 客户端注册端点 |
endpoint.oidc.user-info-uri | String | /v1/oidc/userinfo | OIDC 用户信息端点 |
# 配置示例
spring:
security:
oauth2:
authorization-server:
endpoint:
authorization-uri: /v1/oauth2/authorize
device-authorization-uri: /v1/oauth2/device_authorization
device-verification-uri: /v1/oauth2/device_verification
token-uri: /v1/oauth2/token
jwk-set-uri: /v1/oauth2/jwks
token-revocation-uri: /v1/oauth2/revoke
token-introspection-uri: /v1/oauth2/introspect
pushed-authorization-request-uri: /v1/oauth2/par
oidc:
logout-uri: /v1/oidc/connect/logout
client-registration-uri: /v1/oidc/connect/register
user-info-uri: /v1/oidc/userinfo
# 3. 客户端配置 (Client)
客户端配置使用 Map 结构，键为客户端标识名（如 default、pkce），值为客户端配置对象。
# 3.1 客户端基础配置
| 配置项 | 类型 | 默认值 | 说明 |
|---|---|---|---|
require-proof-key | boolean | false | 是否要求 PKCE（Proof Key for Code Exchange） |
require-authorization-consent | boolean | false | 是否要求用户授权同意 |
jwk-set-uri | String | null | 客户端的 JWK Set URL |
token-endpoint-authentication-signing-algorithm | String | null | Token 端点认证签名算法（用于 private_key_jwt 和 client_secret_jwt） |
# 3.2 客户端注册信息 (Registration)
| 配置项 | 类型 | 默认值 | 必填 | 说明 |
|---|---|---|---|---|
registration.client-id | String | null | ✅ | 客户端 ID |
registration.client-secret | String | null | ❌ | 客户端密钥（公开客户端可为空） |
registration.client-name | String | null | ❌ | 客户端名称 |
registration.client-authentication-methods | Set<String> | [] | ✅ | 客户端认证方式 |
registration.authorization-grant-types | Set<String> | [] | ✅ | 授权类型 |
registration.redirect-uris | Set<String> | [] | ❌ | 重定向 URI（授权码模式必需） |
registration.post-logout-redirect-uris | Set<String> | [] | ❌ | 登出后重定向 URI |
registration.scopes | Set<String> | [] | ❌ | 作用域 |
# 客户端认证方式可选值
| 值 | 说明 |
|---|---|
client_secret_basic | HTTP Basic 认证（推荐） |
client_secret_post | 请求体中传递密钥 |
client_secret_jwt | 使用 JWT 进行认证 |
private_key_jwt | 使用私钥签名的 JWT |
none | 公开客户端（无认证） |
# 授权类型可选值
| 值 | 说明 |
|---|---|
authorization_code | 授权码模式 |
refresh_token | 刷新令牌 |
client_credentials | 客户端凭证模式 |
username_password | 用户名密码模式（自定义扩展） |
mail | 邮箱模式（自定义扩展） |
mobile | 手机号模式（自定义扩展） |
test | 测试模式（自定义扩展） |
urn:ietf:params:oauth:grant-type:device_code | 设备授权码模式 |
urn:ietf:params:oauth:grant-type:jwt-bearer | JWT Bearer 模式 |
urn:ietf:params:oauth:grant-type:token-exchange | 令牌交换模式 |
# 3.3 Token 配置
| 配置项 | 类型 | 默认值 | 说明 |
|---|---|---|---|
token.authorization-code-time-to-live | Duration | 5m | 授权码有效期 |
token.access-token-time-to-live | Duration | 5m | 访问令牌有效期 |
token.access-token-format | String | self-contained | 访问令牌格式（self-contained 或 reference） |
token.device-code-time-to-live | Duration | 5m | 设备码有效期 |
token.refresh-token-time-to-live | Duration | 60m | 刷新令牌有效期 |
token.reuse-refresh-tokens | boolean | true | 是否重用刷新令牌 |
token.id-token-signature-algorithm | String | RS256 | ID Token 签名算法 |
# Duration 格式说明
| 格式 | 示例 | 说明 |
|---|---|---|
XS | 30s | 秒 |
XM | 5m | 分钟 |
XH | 1h | 小时 |
XD | 7d | 天 |
# 4. 完整配置示例
# 示例 1：默认客户端（多种认证方式）
spring:
security:
oauth2:
authorization-server:
enabled: true
multiple-issuers-allowed: false
client:
default:
token:
authorization-code-time-to-live: 5m
access-token-time-to-live: 5m
refresh-token-time-to-live: 1h
device-code-time-to-live: 5m
access-token-format: self-contained
reuse-refresh-tokens: true
id-token-signature-algorithm: RS256
registration:
# Base64编码: OTVUeFNzVFBGQTN0RjEyVEJTTW1VVkswZGE6RnBId0lmdzR3WTkyZE8=
client-id: 95TxSsTPFA3tF12TBSMmUVK0da
client-name: OAuth2.1认证【用户名密码/邮箱/手机号/测试/设备授权码/客户端】
# 原值: FpHwIfw4wY92dO（使用 BCrypt 加密）
client-secret: "{bcrypt}$2a$10$BDcxgmL3WYk7G.QEDTqlBeSudNlV3KUU/V6iC.hKlAbGAC.jbX2fO"
client-authentication-methods:
- client_secret_basic
authorization-grant-types:
- username_password
- mail
- mobile
- test
- refresh_token
- client_credentials
- urn:ietf:params:oauth:grant-type:device_code
- urn:ietf:params:oauth:grant-type:jwt-bearer
- urn:ietf:params:oauth:grant-type:token-exchange
scopes:
- read
- write
require-authorization-consent: false
require-proof-key: false
# 示例 2：PKCE 客户端（授权码模式）
spring:
security:
oauth2:
authorization-server:
client:
pkce:
token:
authorization-code-time-to-live: 5m
access-token-time-to-live: 5m
refresh-token-time-to-live: 1h
device-code-time-to-live: 5m
registration:
# Base64编码: ZWI3RGVkNWJiRmJkNzg5NmY4YTJjZmREYzk6RHBBa1BmejRlVzE4ZDI=
client-id: eb7Ded5bbFbd7896f8a2cfdDc9
client-name: OAuth2.1认证【授权码】
# 原值: DpAkPfz4eW18d2（使用 BCrypt 加密）
client-secret: "{bcrypt}$2a$10$i2Y4II7czKcLqwAxWLgHqeJaIczss4wHArWmthzn3QoLhpCZtdN0O"
client-authentication-methods:
- none
authorization-grant-types:
- authorization_code
- refresh_token
scopes:
- read
- write
redirect-uris:
- http://127.0.0.1:8000
- http://127.0.0.1:8001
- https://laokou.org.cn
post-logout-redirect-uris:
- http://127.0.0.1:8000
- http://127.0.0.1:8001
- https://laokou.org.cn
require-authorization-consent: true
require-proof-key: true
# 示例 3：自定义端点
spring:
security:
oauth2:
authorization-server:
endpoint:
authorization-uri: /api/v1/oauth2/authorize
token-uri: /api/v1/oauth2/token
jwk-set-uri: /api/v1/oauth2/jwks
token-revocation-uri: /api/v1/oauth2/revoke
token-introspection-uri: /api/v1/oauth2/introspect
device-authorization-uri: /api/v1/oauth2/device_authorization
device-verification-uri: /api/v1/oauth2/device_verification
pushed-authorization-request-uri: /api/v1/oauth2/par
oidc:
logout-uri: /api/v1/oidc/logout
client-registration-uri: /api/v1/oidc/register
user-info-uri: /api/v1/oidc/userinfo
# 5. 配置校验规则
启动时会自动校验以下规则:
| 规则 | 说明 |
|---|---|
client-id 不能为空 | 每个客户端必须设置唯一的客户端 ID |
client-authentication-methods 不能为空 | 必须至少设置一种认证方式 |
authorization-grant-types 不能为空 | 必须至少设置一种授权类型 |
# 6. 安全建议
[!IMPORTANT] 以下是一些重要的安全建议，请在生产环境中务必遵守。
# 密钥加密
客户端密钥建议使用 BCrypt 加密存储：
# 格式: {加密算法}加密后的值
client-secret: "{bcrypt}$2a$10$BDcxgmL3WYk7G.QEDTqlBeSudNlV3KUU/V6iC.hKlAbGAC.jbX2fO"
# Token 有效期
| 场景 | 建议值 |
|---|---|
| 访问令牌（access-token） | 5-15 分钟 |
| 刷新令牌（refresh-token） | 1-24 小时 |
| 授权码（authorization-code） | 5-10 分钟 |
| 设备码（device-code） | 5-10 分钟 |
# PKCE 使用
对于公开客户端（如 SPA、移动应用），强烈建议启用 PKCE：
spring:
security:
oauth2:
authorization-server:
client:
pkce:
require-authorization-consent: true
require-proof-key: true
# 7. 相关链接
- Spring Authorization Server 官方文档 (opens new window)
- OAuth 2.1 规范 (opens new window)
- RFC 7636 - PKCE (opens new window)
- OpenID Connect 1.0 (opens new window)
我是老寇，我们下次再见啦！
上次更新: 2/9/2026, 2:54:22 PM