---
description: 记录 OAuth2 授权码流程生成的授权码及对应的刷新令牌。
navTitle: REFRESH_TOKENS
---
# **REFRESH\_TOKENS OAuth2 授权码与刷新令牌表**

以 TOKEN 为主键存储 OAuth2 授权码和刷新令牌。凭证消费和轮换通过 将旧行ENABLED设置为0然后插入新行实现，
TOKEN 值永不更新，保持主键不可变，完整保留审计链路。

授权码和刷新令牌均属敏感凭证，不应导出或写入日志。

## 位置{#position}

模型路径：`/sysdata/data/tables/sec/REFRESH_TOKENS.tbl`

物理表名：`SZSYS_5_REFRESH_TOKENS`

## 表结构{#structure}

| 字段名 | 字段类型 | 字段描述 |
| :----  | :---- | :------ |
| TOKEN | VARCHAR(64) | 凭证值，主键。TOKEN\_TYPE=1 时为授权码，`/api/oauth2/authorize` 生成；TOKEN\_TYPE=2 时为刷新令牌，`/api/oauth2/token` 消费 code 后 INSERT 新行。刷新时旧行 ENABLED=0，INSERT 新行，TOKEN 永不更新 |
| TOKEN\_TYPE | NUMBER(1) | 凭证类型：`1` 授权码，`2` 刷新令牌 |
| ACCESS\_TOKEN | VARCHAR(64) | 关联的 access\_token |
| USER\_ID | VARCHAR(32) | 授权用户 ID |
| USER\_DIRECTORY | VARCHAR(16) | 用户目录，`sys` 系统用户、`external` 外部用户 |
| APP\_ID | VARCHAR(32) | 授信应用 ID |
| APP\_NAME | VARCHAR(128) | 授信应用名称 |
| ENABLED | NUMBER(1) | 是否启用。`1` 有效，`0` 已消费/失效 |
| CODE\_CHALLENGE | VARCHAR(128) | PKCE code challenge，仅授权码阶段写入，refresh\_token 行传 NULL |
| CODE\_CHALLENGE\_METHOD | VARCHAR(8) | PKCE 挑战方式，仅授权码阶段写入，refresh\_token 行传 NULL |
| NEW\_REFRESH\_TOKEN | VARCHAR(64) | 历史兼容字段。旧实现曾用于记录刷新后生成的新 refresh\_token，当前不再用于重放返回凭证 |
| REDIRECT\_URI | VARCHAR(1024) | 授权码对应的 redirect\_uri，仅授权码阶段写入，token 端点必须传入相同值 |
| CREATE\_TIME | TIMESTAMP | 创建时间 |
| EXPIRE\_TIME | TIMESTAMP | TOKEN 过期时间。取值见 [过期时间规范](#ttl-spec) |

## 凭证生命周期

1. `/api/oauth2/authorize` → 在 REFRESH\_TOKENS 中 INSERT 授权码行（TOKEN=code, TOKEN\_TYPE=1, ENABLED=1），同时记录 redirect\_uri 和 PKCE 参数
2. `/api/oauth2/token` → 校验 code、redirect\_uri 和 PKCE 后消费旧行（ENABLED=0） → 在 REFRESH\_TOKENS 中 INSERT refresh\_token 行（TOKEN\_TYPE=2） → 同时在 ACCESS\_TOKENS 中 INSERT 一行 access\_token
3. `/api/oauth2/token` (`grant_type=refresh_token`) → 乐观锁消费旧 refresh\_token 行（ENABLED=0） → INSERT 新 refresh\_token 行（TOKEN\_TYPE=2） → 更新 ACCESS\_TOKENS 中对应 access\_token 的值和过期时间

## 过期时间规范{#ttl-spec}

凭证有效期按 TOKEN\_TYPE 区分，创建时写入 `EXPIRE_TIME`，鉴权时校验 `EXPIRE_TIME` 判定过期。

| 凭证类型 | 有效期 | 说明 |
| :--- | :--- | :--- |
| 授权码（TOKEN\_TYPE=1） | 10 分钟（600 秒） | `/api/oauth2/authorize` 生成的 code 有效时间 10 分钟 |
| 刷新令牌（TOKEN\_TYPE=2） | 6 个月（按 30 天/月估算） | `/api/oauth2/token` 签发的 refresh\_token，刷新轮换时新行同样按此有效期写入 |

## 表索引{#indexes}

| 类型 | 名称 | 字段列表 | 是否唯一 | 说明 |
| :---- | :---- | :---- | :------ | :------ |
| 主键 | PRIMARY | TOKEN | 是 | TOKEN 为主键，不可变，配合 ENABLED 区分有效/消费状态 |