外观
OAuth2 客户端管理
2026-04-01
OAuth2 客户端是 OAuth2 授权流程的核心配置,每个需要接入 nebula-auth 进行 SSO 或 API 授权的应用,都需要在这里注册一个客户端。
目录
一、OAuth2 客户端字段说明
| 字段 | 类型 | 说明 |
|---|---|---|
id | Long | 主键(雪花算法) |
clientId | String | 客户端 ID(全局唯一标识,如 nebula-web) |
tenantCode | String | 所属租户编码(平台级客户端可为空) |
clientSecret | String | 客户端密钥(创建后只显示一次,保存后无法再查) |
clientName | String | 客户端名称(可读性好的展示名) |
grantTypes | String | 支持的授权模式(如 authorization_code,refresh_token) |
scopes | String | 授权范围(如 openid,profile) |
redirectUris | String | 允许的回调地址(多个用逗号分隔) |
accessTokenTtl | Integer | AccessToken 有效时长(秒) |
refreshTokenTtl | Integer | RefreshToken 有效时长(秒) |
status | Integer | 状态(0:正常 1:禁用) |
常用授权模式(grantTypes)
| 模式 | 值 | 适用场景 |
|---|---|---|
| 授权码模式 | authorization_code | Web 应用 SSO,最安全 |
| 刷新令牌 | refresh_token | 配合其他模式实现 Token 续签 |
| 客户端凭证 | client_credentials | 服务间调用,无用户参与 |
| 密码模式 | password | 受信任的内部系统(不推荐新系统使用) |
二、客户端管理接口
接口前缀:
/auth/oauth2-client
所有接口需要管理员权限
2.1 分页查询
接口: POST /auth/oauth2-client/page
请求体:
{
"pageNo": 1,
"pageSize": 10,
"clientId": "nebula",
"clientName": "",
"status": 0
}响应:
{
"code": 0,
"data": {
"records": [
{
"id": 1001,
"clientId": "nebula-web",
"clientName": "Nebula 主应用",
"grantTypes": "authorization_code,refresh_token",
"status": 0,
"createTime": "2026-01-01T10:00:00"
}
],
"total": 1,
"pageNo": 1,
"pageSize": 10
}
}2.2 查询详情
接口: GET /auth/oauth2-client/{id}
响应:
{
"code": 0,
"data": {
"id": 1001,
"clientId": "nebula-web",
"clientName": "Nebula 主应用",
"grantTypes": "authorization_code,refresh_token",
"scopes": "openid,profile",
"redirectUris": "http://localhost:5173/callback,https://app.yourdomain.com/callback",
"accessTokenTtl": 7200,
"refreshTokenTtl": 1209600,
"status": 0,
"remark": "主前端应用"
}
}2.3 创建客户端
接口: POST /auth/oauth2-client
请求体:
{
"clientId": "my-service",
"clientName": "我的业务服务",
"grantTypes": "client_credentials",
"scopes": "openid",
"redirectUris": "",
"accessTokenTtl": 7200,
"refreshTokenTtl": 1209600,
"remark": "内部微服务客户端"
}响应:
{
"code": 0,
"data": {
"id": 1002,
"clientId": "my-service",
"clientSecret": "abc123xyz..."
}
}重要:
clientSecret只在创建响应中返回一次,请立即妥善保存。后续若丢失,只能通过「重置密钥」接口重新生成。
2.4 修改客户端
接口: PUT /auth/oauth2-client/{id}
请求体(只传需要修改的字段):
{
"id": 1001,
"clientName": "Nebula 主应用(更新)",
"accessTokenTtl": 3600,
"remark": "更新备注"
}注意:
clientId和clientSecret不可通过此接口修改,密钥变更请使用「重置密钥」接口。
2.5 删除客户端
接口: DELETE /auth/oauth2-client
请求体:
[1001, 1002]2.6 启用 / 禁用
PATCH /auth/oauth2-client/{id}/v # 启用
PATCH /auth/oauth2-client/{id}/x # 禁用三、重置客户端密钥
当客户端密钥泄露或丢失时,可重置生成新密钥。
接口: PATCH /auth/oauth2-client/{id}/reset-secret
响应:
{
"code": 0,
"data": "新的 clientSecret(只返回一次,请立即保存)"
}注意: 重置后,旧密钥立即失效,使用旧密钥的应用需及时更新配置。
四、RPC 查询接口
业务服务可通过 RPC 接口按 clientId 查询 OAuth2 客户端信息(聚合部署时走 LocalStub,分布式部署时走 Feign HTTP)。
接口: GET /rpc/nebula/auth/oauth2-client/by-client-id?clientId={clientId}
Feign Client 调用示例:
// 注入 IAuth RpcService 后调用(框架已通过 Feign + LocalStub 处理)
@Autowired
private OAuth2ClientRpcService oauth2ClientRpcService;
R<OAuth2ClientDetailVO> result = oauth2ClientRpcService.getByClientId("nebula-web");
OAuth2ClientDetailVO client = result.getDataOrThrow();