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();