OptimusX
/
OneAuth
mirror of https://github.com/veypi/OneAuth.git
3
0
Fork 0
Code Issues Projects Releases Wiki Activity
You cannot select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
master
v3
v2
v1.0.0
v0.1.0
Branches Tags
${ item.name }
Create tag ${ searchTerm }
Create branch ${ searchTerm }
from '809bba7417'
${ noResults }
OneAuth/doc/api.md

12 KiB
Raw Blame History Unescape Escape

VBase API 文档

概述

VBase 是一个多租户身份认证与访问管理(IAM)系统，支持用户管理、组织管理、RBAC权限控制和OAuth2.0服务。

基础信息

  • 基础URL: https://api.example.com
  • 请求格式: application/json
  • 响应格式: application/json
  • 认证方式: Bearer Token (JWT)

通用响应格式

{
  "code": 200,
  "message": "success",
  "data": {}
}

错误响应

{
  "code": 400,
  "message": "error message",
  "data": null
}

认证相关

用户登录

POST /auth/login

用户登录获取访问令牌。

请求参数

字段 类型 必填 说明
username string 是 用户名/邮箱/手机号
password string 是 密码
remember bool 否 记住登录

响应示例

{
  "code": 200,
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIs...",
    "refresh_token": "eyJhbGciOiJIUzI1NiIs...",
    "token_type": "Bearer",
    "expires_in": 3600,
    "user": {
      "id": "user-id",
      "username": "admin",
      "nickname": "管理员",
      "email": "admin@example.com",
      "avatar": "https://..."
    }
  }
}

用户注册

POST /auth/register

注册新用户。

请求参数

字段 类型 必填 说明
username string 是 用户名(2-50字符)
password string 是 密码(至少8位)
email string 否 邮箱
phone string 否 手机号
nickname string 否 昵称

刷新Token

POST /auth/refresh

使用刷新令牌获取新的访问令牌。

请求参数

字段 类型 必填 说明
refresh_token string 是 刷新令牌

用户登出

POST /auth/logout

用户登出，使当前Token失效。

请求头

  • Authorization: Bearer {access_token}

支持的第三方登录提供商

GET /auth/providers

获取系统支持的第三方登录提供商列表。

响应示例

{
  "code": 200,
  "data": [
    {
      "name": "google",
      "display_name": "Google",
      "icon": "google",
      "enabled": true
    },
    {
      "name": "github",
      "display_name": "GitHub",
      "icon": "github",
      "enabled": true
    }
  ]
}

第三方登录授权

GET /auth/authorize/thirdparty

获取第三方登录授权URL。

请求参数

字段 类型 必填 说明
provider string 是 提供商: google/github/wechat
redirect string 否 登录成功后重定向地址
bind_mode bool 否 是否为绑定模式

响应示例

{
  "code": 200,
  "data": {
    "auth_url": "https://github.com/login/oauth/authorize?...",
    "state": "random-state-string"
  }
}

第三方登录回调

GET /auth/callback/{provider}

处理第三方登录回调。

路径参数

  • provider: 提供商名称

查询参数

  • code: 授权码
  • state: 状态值

响应示例（已绑定）

{
  "code": 200,
  "data": {
    "need_bind": false,
    "access_token": "eyJhbGciOiJIUzI1NiIs...",
    "refresh_token": "eyJhbGciOiJIUzI1NiIs...",
    "token_type": "Bearer",
    "expires_in": 3600,
    "user": {...}
  }
}

响应示例（未绑定）

{
  "code": 200,
  "data": {
    "need_bind": true,
    "provider": "github",
    "provider_id": "12345",
    "auth_url": "/auth/bind?token=xxx"
  }
}

绑定第三方账号

POST /auth/bind

将第三方账号绑定到已有账号。

请求参数

字段 类型 必填 说明
temp_token string 是 临时绑定令牌
username string 是 用户名/邮箱/手机号
password string 是 密码

当前用户

获取当前用户信息

GET /me

获取当前登录用户的信息。

请求头

  • Authorization: Bearer {access_token}

响应示例

{
  "code": 200,
  "data": {
    "id": "user-id",
    "username": "admin",
    "nickname": "管理员",
    "email": "admin@example.com",
    "avatar": "https://...",
    "status": 1,
    "email_verified": true
  }
}

更新当前用户信息

PATCH /me

更新当前用户的基本信息。

请求参数

字段 类型 必填 说明
nickname string 否 昵称
avatar string 否 头像URL
email string 否 邮箱

修改密码

POST /me/change-password

修改当前用户密码。

请求参数

字段 类型 必填 说明
old_password string 是 旧密码
new_password string 是 新密码(至少8位)

获取第三方绑定列表

GET /me/bindings

获取当前用户绑定的第三方账号列表。

响应示例

{
  "code": 200,
  "data": [
    {
      "provider": "github",
      "provider_name": "GitHub User",
      "avatar": "https://...",
      "email": "user@example.com",
      "created_at": "2024-01-01 10:00:00"
    }
  ]
}

解绑第三方账号

DELETE /me/bindings/{provider}

解除指定提供商的账号绑定。

路径参数

  • provider: 提供商名称 (google/github/wechat)

用户管理

用户列表

GET /users

获取用户列表（需要权限）。

请求参数

字段 类型 必填 说明
page int 否 页码，默认1
page_size int 否 每页数量，默认10
keyword string 否 搜索关键词
status int 否 状态筛选

响应示例

{
  "code": 200,
  "data": {
    "items": [...],
    "total": 100,
    "page": 1,
    "page_size": 10,
    "total_pages": 10
  }
}

创建用户

POST /users

创建新用户（需要权限）。

请求参数

字段 类型 必填 说明
username string 是 用户名
password string 是 密码
nickname string 否 昵称
email string 否 邮箱
phone string 否 手机号
status int 否 状态

获取用户详情

GET /users/{user_id}

获取指定用户的详细信息。

路径参数

  • user_id: 用户ID

更新用户

PATCH /users/{user_id}

更新指定用户的信息。

路径参数

  • user_id: 用户ID

请求参数

字段 类型 必填 说明
nickname string 否 昵称
avatar string 否 头像
email string 否 邮箱
phone string 否 手机号
status int 否 状态

删除用户

DELETE /users/{user_id}

删除指定用户（软删除）。

更新用户状态

PATCH /users/{user_id}/status

更新用户状态。

请求参数

字段 类型 必填 说明
status int 是 0:禁用 1:正常 2:未激活

组织管理

组织列表

GET /orgs

获取当前用户的组织列表。

请求参数

字段 类型 必填 说明
page int 否 页码
page_size int 否 每页数量
keyword string 否 搜索关键词

响应示例

{
  "code": 200,
  "data": {
    "items": [
      {
        "id": "org-id",
        "name": "技术部",
        "code": "tech",
        "owner_id": "user-id",
        "path": "/tech",
        "level": 0,
        "status": 1,
        "my_roles": ["admin"],
        "my_status": 1
      }
    ],
    "total": 10
  }
}

创建组织

POST /orgs

创建新组织。

请求参数

字段 类型 必填 说明
name string 是 组织名称
code string 是 组织编码(唯一)
parent_id string 否 父组织ID
description string 否 描述
max_members int 否 最大成员数

获取组织详情

GET /orgs/{org_id}

获取组织详细信息。

更新组织

PATCH /orgs/{org_id}

更新组织信息（仅所有者）。

删除组织

DELETE /orgs/{org_id}

删除组织（仅所有者，需无子组织）。

组织树

GET /orgs/tree

获取当前用户的组织树结构。

响应示例

{
  "code": 200,
  "data": [
    {
      "id": "org-id",
      "name": "总公司",
      "children": [
        {
          "id": "sub-org-id",
          "name": "技术部"
        }
      ]
    }
  ]
}

组织成员列表

GET /orgs/{org_id}/members

获取组织成员列表。

请求参数

字段 类型 必填 说明
page int 否 页码
page_size int 否 每页数量
status int 否 状态筛选

OAuth2.0 服务端

授权端点

GET /oauth/authorize

OAuth2.0 授权端点，获取授权码。

请求参数

字段 类型 必填 说明
response_type string 是 code/token
client_id string 是 客户端ID
redirect_uri string 是 回调地址
scope string 否 权限范围
state string 是 CSRF防护
code_challenge string 否 PKCE挑战码
code_challenge_method string 否 S256/plain

令牌端点

POST /oauth/token

OAuth2.0 令牌端点，交换授权码获取访问令牌。

请求参数

字段 类型 必填 说明
grant_type string 是 authorization_code/refresh_token/client_credentials
code string 条件 授权码
redirect_uri string 条件 回调地址
client_id string 是 客户端ID
client_secret string 是 客户端密钥
refresh_token string 条件 刷新令牌
code_verifier string 条件 PKCE验证器

撤销令牌

POST /oauth/revoke

撤销访问令牌或刷新令牌。

令牌内省

POST /oauth/introspect

查询令牌信息（RFC 7662）。

用户信息

GET /oauth/userinfo

OIDC 用户信息端点。

OIDC 发现文档

GET /.well-known/openid-configuration

获取 OIDC 配置信息。

JWKS

GET /oauth/jwks

获取 JWT 签名公钥。

OAuth 客户端管理

客户端列表

GET /oauth/clients

获取 OAuth 客户端列表。

创建客户端

POST /oauth/clients

创建新的 OAuth 客户端。

请求参数

字段 类型 必填 说明
name string 是 应用名称
description string 否 描述
redirect_uris []string 是 回调地址列表
grant_types []string 否 授权类型
allowed_scopes []string 否 允许的范围

响应示例

{
  "code": 200,
  "data": {
    "id": "client-id",
    "name": "My App",
    "client_id": "abc123...",
    "client_secret": "secret...",
    "redirect_uris": ["https://app.com/callback"],
    "grant_types": ["authorization_code", "refresh_token"]
  }
}

获取客户端详情

GET /oauth/clients/{client_id}

获取 OAuth 客户端详情。

更新客户端

PATCH /oauth/clients/{client_id}

更新 OAuth 客户端信息。

删除客户端

DELETE /oauth/clients/{client_id}

删除 OAuth 客户端。

重新生成密钥

POST /oauth/clients/{client_id}/regenerate-secret

重新生成客户端密钥。

请求头说明

认证头

Authorization: Bearer {access_token}

组织上下文

X-Org-ID: {organization_id}

用于指定当前操作的组织上下文。

状态码说明

状态码 说明
200 成功
400 请求参数错误
401 未认证
403 无权限
404 资源不存在
429 请求过于频繁
500 服务器内部错误