docs(identity): 发布统一认证管理契约

为配对、策略、验证、激活、回滚、禁用和公开运行时接口补充 OpenAPI 注解,并将通用 Identity 类型加入生成范围。生成契约不包含 Exchange Token、Machine Secret 或 Secret 引用。\n\n验证:pnpm openapi;OpenAPI 敏感字段扫描通过
This commit is contained in:
2026-07-17 12:31:11 +08:00
parent a767dc42c0
commit cdfca61304
4 changed files with 1626 additions and 1 deletions
+905
View File
@@ -2868,6 +2868,575 @@
}
}
},
"/api/admin/system/identity/configuration": {
"get": {
"security": [
{
"BearerAuth": []
}
],
"description": "返回 Active、Draft、Previous Revision、配对进度和脱敏运行时健康状态。",
"produces": [
"application/json"
],
"tags": [
"identity"
],
"summary": "获取统一认证配置",
"responses": {
"200": {
"description": "OK",
"schema": {
"$ref": "#/definitions/httpapi.identityConfigurationView"
}
},
"401": {
"description": "Unauthorized",
"schema": {
"$ref": "#/definitions/httpapi.ErrorEnvelope"
}
},
"403": {
"description": "Forbidden",
"schema": {
"$ref": "#/definitions/httpapi.ErrorEnvelope"
}
},
"503": {
"description": "Service Unavailable",
"schema": {
"$ref": "#/definitions/httpapi.ErrorEnvelope"
}
}
}
}
},
"/api/admin/system/identity/disable": {
"post": {
"security": [
{
"BearerAuth": []
}
],
"description": "保留 Superseded Revision 供回滚,清理 BFF Session,并继续允许本地管理登录。",
"produces": [
"application/json"
],
"tags": [
"identity"
],
"summary": "禁用统一认证",
"parameters": [
{
"type": "string",
"description": "幂等键",
"name": "Idempotency-Key",
"in": "header",
"required": true
},
{
"type": "string",
"description": "当前 Active Revision ETag",
"name": "If-Match",
"in": "header",
"required": true
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"$ref": "#/definitions/identity.Revision"
}
},
"401": {
"description": "Unauthorized",
"schema": {
"$ref": "#/definitions/httpapi.ErrorEnvelope"
}
},
"403": {
"description": "Forbidden",
"schema": {
"$ref": "#/definitions/httpapi.ErrorEnvelope"
}
},
"409": {
"description": "Conflict",
"schema": {
"$ref": "#/definitions/httpapi.ErrorEnvelope"
}
},
"412": {
"description": "Precondition Failed",
"schema": {
"$ref": "#/definitions/httpapi.ErrorEnvelope"
}
},
"428": {
"description": "Precondition Required",
"schema": {
"$ref": "#/definitions/httpapi.ErrorEnvelope"
}
}
}
}
},
"/api/admin/system/identity/pairings": {
"post": {
"security": [
{
"BearerAuth": []
}
],
"description": "使用一次性接入码创建 Draft 和异步 Exchange。接入码仅允许出现在请求 Body。",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"tags": [
"identity"
],
"summary": "启动统一认证配对",
"parameters": [
{
"type": "string",
"description": "幂等键",
"name": "Idempotency-Key",
"in": "header",
"required": true
},
{
"type": "string",
"description": "首次配对固定为 W/\\",
"name": "If-Match",
"in": "header",
"required": true
},
{
"description": "配对参数",
"name": "body",
"in": "body",
"required": true,
"schema": {
"$ref": "#/definitions/identity.PairingInput"
}
}
],
"responses": {
"202": {
"description": "Accepted",
"schema": {
"$ref": "#/definitions/identity.PairingExchange"
}
},
"400": {
"description": "Bad Request",
"schema": {
"$ref": "#/definitions/httpapi.ErrorEnvelope"
}
},
"401": {
"description": "Unauthorized",
"schema": {
"$ref": "#/definitions/httpapi.ErrorEnvelope"
}
},
"403": {
"description": "Forbidden",
"schema": {
"$ref": "#/definitions/httpapi.ErrorEnvelope"
}
},
"409": {
"description": "Conflict",
"schema": {
"$ref": "#/definitions/httpapi.ErrorEnvelope"
}
},
"428": {
"description": "Precondition Required",
"schema": {
"$ref": "#/definitions/httpapi.ErrorEnvelope"
}
}
}
}
},
"/api/admin/system/identity/pairings/{pairingID}": {
"get": {
"security": [
{
"BearerAuth": []
}
],
"produces": [
"application/json"
],
"tags": [
"identity"
],
"summary": "查询统一认证配对状态",
"parameters": [
{
"type": "string",
"description": "配对 ID",
"name": "pairingID",
"in": "path",
"required": true
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"$ref": "#/definitions/identity.PairingExchange"
}
},
"401": {
"description": "Unauthorized",
"schema": {
"$ref": "#/definitions/httpapi.ErrorEnvelope"
}
},
"403": {
"description": "Forbidden",
"schema": {
"$ref": "#/definitions/httpapi.ErrorEnvelope"
}
},
"404": {
"description": "Not Found",
"schema": {
"$ref": "#/definitions/httpapi.ErrorEnvelope"
}
}
}
}
},
"/api/admin/system/identity/revisions/{revisionID}": {
"patch": {
"security": [
{
"BearerAuth": []
}
],
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"tags": [
"identity"
],
"summary": "修改统一认证 Draft 策略",
"parameters": [
{
"type": "string",
"description": "Revision ID",
"name": "revisionID",
"in": "path",
"required": true
},
{
"type": "string",
"description": "幂等键",
"name": "Idempotency-Key",
"in": "header",
"required": true
},
{
"type": "string",
"description": "当前 Revision ETag",
"name": "If-Match",
"in": "header",
"required": true
},
{
"description": "Gateway 本地策略",
"name": "body",
"in": "body",
"required": true,
"schema": {
"$ref": "#/definitions/httpapi.identityPolicyPatch"
}
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"$ref": "#/definitions/identity.Revision"
}
},
"400": {
"description": "Bad Request",
"schema": {
"$ref": "#/definitions/httpapi.ErrorEnvelope"
}
},
"401": {
"description": "Unauthorized",
"schema": {
"$ref": "#/definitions/httpapi.ErrorEnvelope"
}
},
"403": {
"description": "Forbidden",
"schema": {
"$ref": "#/definitions/httpapi.ErrorEnvelope"
}
},
"412": {
"description": "Precondition Failed",
"schema": {
"$ref": "#/definitions/httpapi.ErrorEnvelope"
}
},
"428": {
"description": "Precondition Required",
"schema": {
"$ref": "#/definitions/httpapi.ErrorEnvelope"
}
}
}
}
},
"/api/admin/system/identity/revisions/{revisionID}/activate": {
"post": {
"security": [
{
"BearerAuth": []
}
],
"description": "在完整候选 Runtime 验证成功且本地 Break-glass Manager 可用后原子热切换。",
"produces": [
"application/json"
],
"tags": [
"identity"
],
"summary": "激活统一认证 Revision",
"parameters": [
{
"type": "string",
"description": "Revision ID",
"name": "revisionID",
"in": "path",
"required": true
},
{
"type": "string",
"description": "幂等键",
"name": "Idempotency-Key",
"in": "header",
"required": true
},
{
"type": "string",
"description": "当前 Revision ETag",
"name": "If-Match",
"in": "header",
"required": true
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"$ref": "#/definitions/identity.Revision"
}
},
"401": {
"description": "Unauthorized",
"schema": {
"$ref": "#/definitions/httpapi.ErrorEnvelope"
}
},
"403": {
"description": "Forbidden",
"schema": {
"$ref": "#/definitions/httpapi.ErrorEnvelope"
}
},
"409": {
"description": "Conflict",
"schema": {
"$ref": "#/definitions/httpapi.ErrorEnvelope"
}
},
"412": {
"description": "Precondition Failed",
"schema": {
"$ref": "#/definitions/httpapi.ErrorEnvelope"
}
},
"428": {
"description": "Precondition Required",
"schema": {
"$ref": "#/definitions/httpapi.ErrorEnvelope"
}
}
}
}
},
"/api/admin/system/identity/revisions/{revisionID}/rollback": {
"post": {
"security": [
{
"BearerAuth": []
}
],
"produces": [
"application/json"
],
"tags": [
"identity"
],
"summary": "回滚统一认证 Revision",
"parameters": [
{
"type": "string",
"description": "Revision ID",
"name": "revisionID",
"in": "path",
"required": true
},
{
"type": "string",
"description": "幂等键",
"name": "Idempotency-Key",
"in": "header",
"required": true
},
{
"type": "string",
"description": "当前 Revision ETag",
"name": "If-Match",
"in": "header",
"required": true
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"$ref": "#/definitions/identity.Revision"
}
},
"401": {
"description": "Unauthorized",
"schema": {
"$ref": "#/definitions/httpapi.ErrorEnvelope"
}
},
"403": {
"description": "Forbidden",
"schema": {
"$ref": "#/definitions/httpapi.ErrorEnvelope"
}
},
"409": {
"description": "Conflict",
"schema": {
"$ref": "#/definitions/httpapi.ErrorEnvelope"
}
},
"412": {
"description": "Precondition Failed",
"schema": {
"$ref": "#/definitions/httpapi.ErrorEnvelope"
}
},
"428": {
"description": "Precondition Required",
"schema": {
"$ref": "#/definitions/httpapi.ErrorEnvelope"
}
}
}
}
},
"/api/admin/system/identity/revisions/{revisionID}/validate": {
"post": {
"security": [
{
"BearerAuth": []
}
],
"produces": [
"application/json"
],
"tags": [
"identity"
],
"summary": "验证统一认证 Revision",
"parameters": [
{
"type": "string",
"description": "Revision ID",
"name": "revisionID",
"in": "path",
"required": true
},
{
"type": "string",
"description": "幂等键",
"name": "Idempotency-Key",
"in": "header",
"required": true
},
{
"type": "string",
"description": "当前 Revision ETag",
"name": "If-Match",
"in": "header",
"required": true
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"$ref": "#/definitions/identity.Revision"
}
},
"401": {
"description": "Unauthorized",
"schema": {
"$ref": "#/definitions/httpapi.ErrorEnvelope"
}
},
"403": {
"description": "Forbidden",
"schema": {
"$ref": "#/definitions/httpapi.ErrorEnvelope"
}
},
"412": {
"description": "Precondition Failed",
"schema": {
"$ref": "#/definitions/httpapi.ErrorEnvelope"
}
},
"428": {
"description": "Precondition Required",
"schema": {
"$ref": "#/definitions/httpapi.ErrorEnvelope"
}
},
"502": {
"description": "Bad Gateway",
"schema": {
"$ref": "#/definitions/httpapi.ErrorEnvelope"
}
}
}
}
},
"/api/admin/tenants": {
"get": {
"security": [
@@ -5320,6 +5889,26 @@
}
}
},
"/api/v1/public/identity": {
"get": {
"description": "返回 Web 运行时需要的启用状态和非敏感登录、退出入口,不返回 Client、Secret 或内部标识。",
"produces": [
"application/json"
],
"tags": [
"identity"
],
"summary": "获取公开统一认证状态",
"responses": {
"200": {
"description": "OK",
"schema": {
"$ref": "#/definitions/httpapi.publicIdentityConfiguration"
}
}
}
}
},
"/api/v1/reranks": {
"post": {
"security": [
@@ -10742,6 +11331,104 @@
}
}
},
"httpapi.identityConfigurationView": {
"type": "object",
"properties": {
"active": {
"$ref": "#/definitions/identity.Revision"
},
"draft": {
"$ref": "#/definitions/identity.Revision"
},
"pairing": {
"$ref": "#/definitions/identity.PairingExchange"
},
"previous": {
"$ref": "#/definitions/identity.Revision"
},
"runtime": {
"$ref": "#/definitions/httpapi.identityRuntimeStatus"
}
}
},
"httpapi.identityPolicyPatch": {
"type": "object",
"properties": {
"jitEnabled": {
"type": "boolean"
},
"legacyJwtEnabled": {
"type": "boolean"
},
"localTenantKey": {
"type": "string"
},
"rolePrefix": {
"type": "string"
},
"sessionAbsoluteSeconds": {
"type": "integer"
},
"sessionIdleSeconds": {
"type": "integer"
},
"sessionRefreshSeconds": {
"type": "integer"
}
}
},
"httpapi.identityRuntimeStatus": {
"type": "object",
"properties": {
"enabled": {
"type": "boolean"
},
"jit": {
"type": "string"
},
"lastAuditId": {
"type": "string"
},
"lastErrorCategory": {
"type": "string"
},
"lastTraceId": {
"type": "string"
},
"login": {
"type": "string"
},
"revisionId": {
"type": "string"
},
"sessionRevocation": {
"type": "string"
},
"tokenIntrospection": {
"type": "string"
}
}
},
"httpapi.publicIdentityConfiguration": {
"type": "object",
"properties": {
"enabled": {
"type": "boolean"
},
"loginUrl": {
"type": "string"
},
"logoutUrl": {
"type": "string"
},
"oidcLogin": {
"type": "boolean"
},
"status": {
"type": "string"
}
}
},
"httpapi.updatePlatformDynamicPriorityRequest": {
"type": "object",
"properties": {
@@ -10805,6 +11492,224 @@
}
}
},
"identity.PairingExchange": {
"type": "object",
"properties": {
"authCenterAuditId": {
"type": "string"
},
"createdAt": {
"type": "string"
},
"expiresAt": {
"type": "string"
},
"id": {
"type": "string"
},
"lastErrorCategory": {
"type": "string"
},
"lastTraceId": {
"type": "string"
},
"remoteExchangeId": {
"type": "string"
},
"remoteVersion": {
"type": "integer"
},
"revisionId": {
"type": "string"
},
"status": {
"$ref": "#/definitions/identity.PairingStatus"
},
"updatedAt": {
"type": "string"
},
"version": {
"type": "integer"
}
}
},
"identity.PairingInput": {
"type": "object",
"properties": {
"authCenterUrl": {
"type": "string"
},
"legacyJwtEnabled": {
"type": "boolean"
},
"localTenantKey": {
"type": "string"
},
"onboardingCode": {
"type": "string"
},
"publicBaseUrl": {
"type": "string"
},
"webBaseUrl": {
"type": "string"
}
}
},
"identity.PairingStatus": {
"type": "string",
"enum": [
"metadata_pending",
"preparing",
"ready",
"credentials_saved",
"completed",
"failed",
"expired"
],
"x-enum-varnames": [
"PairingMetadataPending",
"PairingPreparing",
"PairingReady",
"PairingCredentialsSaved",
"PairingCompleted",
"PairingFailed",
"PairingExpired"
]
},
"identity.Revision": {
"type": "object",
"properties": {
"activatedAt": {
"type": "string"
},
"applicationId": {
"type": "string"
},
"audience": {
"type": "string"
},
"authCenterUrl": {
"type": "string"
},
"browserClientId": {
"type": "string"
},
"capabilities": {
"type": "array",
"items": {
"type": "string"
}
},
"createdAt": {
"type": "string"
},
"id": {
"type": "string"
},
"issuer": {
"type": "string"
},
"jitEnabled": {
"type": "boolean"
},
"lastAuditId": {
"type": "string"
},
"lastErrorCategory": {
"type": "string"
},
"lastTraceId": {
"type": "string"
},
"legacyJwtEnabled": {
"type": "boolean"
},
"localTenantKey": {
"type": "string"
},
"machineClientId": {
"type": "string"
},
"publicBaseUrl": {
"type": "string"
},
"rolePrefix": {
"type": "string"
},
"schemaVersion": {
"type": "integer"
},
"scopes": {
"type": "array",
"items": {
"type": "string"
}
},
"securityEventAudience": {
"type": "string"
},
"securityEventConfigurationUrl": {
"type": "string"
},
"securityEventIssuer": {
"type": "string"
},
"sessionAbsoluteSeconds": {
"type": "integer"
},
"sessionIdleSeconds": {
"type": "integer"
},
"sessionRefreshSeconds": {
"type": "integer"
},
"sessionRevocation": {
"type": "boolean"
},
"state": {
"$ref": "#/definitions/identity.RevisionState"
},
"supersededAt": {
"type": "string"
},
"tenantId": {
"type": "string"
},
"tokenIntrospection": {
"type": "boolean"
},
"updatedAt": {
"type": "string"
},
"validatedAt": {
"type": "string"
},
"version": {
"type": "integer"
},
"webBaseUrl": {
"type": "string"
}
}
},
"identity.RevisionState": {
"type": "string",
"enum": [
"draft",
"validated",
"active",
"superseded",
"failed"
],
"x-enum-varnames": [
"RevisionDraft",
"RevisionValidated",
"RevisionActive",
"RevisionSuperseded",
"RevisionFailed"
]
},
"store.APIKey": {
"type": "object",
"properties": {