docs(identity): 发布统一认证管理契约
为配对、策略、验证、激活、回滚、禁用和公开运行时接口补充 OpenAPI 注解，并将通用 Identity 类型加入生成范围。生成契约不包含 Exchange Token、Machine Secret 或 Secret 引用。\n\n验证：pnpm openapi；OpenAPI 敏感字段扫描通过
This commit is contained in:
@@ -74,6 +74,13 @@ func (operation *identityWriteOperation) close() {
|
||||
}
|
||||
}
|
||||
|
||||
// getPublicIdentityConfiguration godoc
|
||||
// @Summary 获取公开统一认证状态
|
||||
// @Description 返回 Web 运行时需要的启用状态和非敏感登录、退出入口，不返回 Client、Secret 或内部标识。
|
||||
// @Tags identity
|
||||
// @Produce json
|
||||
// @Success 200 {object} publicIdentityConfiguration
|
||||
// @Router /api/v1/public/identity [get]
|
||||
func (s *Server) getPublicIdentityConfiguration(w http.ResponseWriter, _ *http.Request) {
|
||||
w.Header().Set("Cache-Control", "no-store")
|
||||
runtime := s.currentIdentityRuntime()
|
||||
@@ -90,6 +97,17 @@ func (s *Server) getPublicIdentityConfiguration(w http.ResponseWriter, _ *http.R
|
||||
writeJSON(w, http.StatusOK, view)
|
||||
}
|
||||
|
||||
// getIdentityConfiguration godoc
|
||||
// @Summary 获取统一认证配置
|
||||
// @Description 返回 Active、Draft、Previous Revision、配对进度和脱敏运行时健康状态。
|
||||
// @Tags identity
|
||||
// @Produce json
|
||||
// @Security BearerAuth
|
||||
// @Success 200 {object} identityConfigurationView
|
||||
// @Failure 401 {object} ErrorEnvelope
|
||||
// @Failure 403 {object} ErrorEnvelope
|
||||
// @Failure 503 {object} ErrorEnvelope
|
||||
// @Router /api/admin/system/identity/configuration [get]
|
||||
func (s *Server) getIdentityConfiguration(w http.ResponseWriter, r *http.Request) {
|
||||
w.Header().Set("Cache-Control", "no-store")
|
||||
view := identityConfigurationView{Runtime: s.identityRuntimeStatus(r)}
|
||||
@@ -117,6 +135,23 @@ func (s *Server) getIdentityConfiguration(w http.ResponseWriter, r *http.Request
|
||||
writeJSON(w, http.StatusOK, view)
|
||||
}
|
||||
|
||||
// startIdentityPairing godoc
|
||||
// @Summary 启动统一认证配对
|
||||
// @Description 使用一次性接入码创建 Draft 和异步 Exchange。接入码仅允许出现在请求 Body。
|
||||
// @Tags identity
|
||||
// @Accept json
|
||||
// @Produce json
|
||||
// @Security BearerAuth
|
||||
// @Param Idempotency-Key header string true "幂等键"
|
||||
// @Param If-Match header string true "首次配对固定为 W/\"0\""
|
||||
// @Param body body identity.PairingInput true "配对参数"
|
||||
// @Success 202 {object} identity.PairingExchange
|
||||
// @Failure 400 {object} ErrorEnvelope
|
||||
// @Failure 401 {object} ErrorEnvelope
|
||||
// @Failure 403 {object} ErrorEnvelope
|
||||
// @Failure 409 {object} ErrorEnvelope
|
||||
// @Failure 428 {object} ErrorEnvelope
|
||||
// @Router /api/admin/system/identity/pairings [post]
|
||||
func (s *Server) startIdentityPairing(w http.ResponseWriter, r *http.Request) {
|
||||
var input identity.PairingInput
|
||||
if !decodeIdentityRequest(w, r, &input) {
|
||||
@@ -139,6 +174,17 @@ func (s *Server) startIdentityPairing(w http.ResponseWriter, r *http.Request) {
|
||||
s.startIdentityPairingWorker(pairing.ID)
|
||||
}
|
||||
|
||||
// getIdentityPairing godoc
|
||||
// @Summary 查询统一认证配对状态
|
||||
// @Tags identity
|
||||
// @Produce json
|
||||
// @Security BearerAuth
|
||||
// @Param pairingID path string true "配对 ID"
|
||||
// @Success 200 {object} identity.PairingExchange
|
||||
// @Failure 401 {object} ErrorEnvelope
|
||||
// @Failure 403 {object} ErrorEnvelope
|
||||
// @Failure 404 {object} ErrorEnvelope
|
||||
// @Router /api/admin/system/identity/pairings/{pairingID} [get]
|
||||
func (s *Server) getIdentityPairing(w http.ResponseWriter, r *http.Request) {
|
||||
w.Header().Set("Cache-Control", "no-store")
|
||||
pairing, err := s.store.IdentityPairingExchange(r.Context(), r.PathValue("pairingID"))
|
||||
@@ -150,6 +196,23 @@ func (s *Server) getIdentityPairing(w http.ResponseWriter, r *http.Request) {
|
||||
writeJSON(w, http.StatusOK, pairing)
|
||||
}
|
||||
|
||||
// updateIdentityDraftPolicy godoc
|
||||
// @Summary 修改统一认证 Draft 策略
|
||||
// @Tags identity
|
||||
// @Accept json
|
||||
// @Produce json
|
||||
// @Security BearerAuth
|
||||
// @Param revisionID path string true "Revision ID"
|
||||
// @Param Idempotency-Key header string true "幂等键"
|
||||
// @Param If-Match header string true "当前 Revision ETag"
|
||||
// @Param body body identityPolicyPatch true "Gateway 本地策略"
|
||||
// @Success 200 {object} identity.Revision
|
||||
// @Failure 400 {object} ErrorEnvelope
|
||||
// @Failure 401 {object} ErrorEnvelope
|
||||
// @Failure 403 {object} ErrorEnvelope
|
||||
// @Failure 412 {object} ErrorEnvelope
|
||||
// @Failure 428 {object} ErrorEnvelope
|
||||
// @Router /api/admin/system/identity/revisions/{revisionID} [patch]
|
||||
func (s *Server) updateIdentityDraftPolicy(w http.ResponseWriter, r *http.Request) {
|
||||
var patch identityPolicyPatch
|
||||
if !decodeIdentityRequest(w, r, &patch) {
|
||||
@@ -185,24 +248,85 @@ func (s *Server) updateIdentityDraftPolicy(w http.ResponseWriter, r *http.Reques
|
||||
s.completeIdentityWrite(w, r, operation, http.StatusOK, updated, updated.Version, auditID)
|
||||
}
|
||||
|
||||
// validateIdentityRevision godoc
|
||||
// @Summary 验证统一认证 Revision
|
||||
// @Tags identity
|
||||
// @Produce json
|
||||
// @Security BearerAuth
|
||||
// @Param revisionID path string true "Revision ID"
|
||||
// @Param Idempotency-Key header string true "幂等键"
|
||||
// @Param If-Match header string true "当前 Revision ETag"
|
||||
// @Success 200 {object} identity.Revision
|
||||
// @Failure 401 {object} ErrorEnvelope
|
||||
// @Failure 403 {object} ErrorEnvelope
|
||||
// @Failure 412 {object} ErrorEnvelope
|
||||
// @Failure 428 {object} ErrorEnvelope
|
||||
// @Failure 502 {object} ErrorEnvelope
|
||||
// @Router /api/admin/system/identity/revisions/{revisionID}/validate [post]
|
||||
func (s *Server) validateIdentityRevision(w http.ResponseWriter, r *http.Request) {
|
||||
s.runIdentityRevisionAction(w, r, "revision.validate", func(expected int64, traceID, auditID string) (identity.Revision, error) {
|
||||
return s.identityRuntime.Validate(r.Context(), r.PathValue("revisionID"), expected, traceID, auditID)
|
||||
})
|
||||
}
|
||||
|
||||
// activateIdentityRevision godoc
|
||||
// @Summary 激活统一认证 Revision
|
||||
// @Description 在完整候选 Runtime 验证成功且本地 Break-glass Manager 可用后原子热切换。
|
||||
// @Tags identity
|
||||
// @Produce json
|
||||
// @Security BearerAuth
|
||||
// @Param revisionID path string true "Revision ID"
|
||||
// @Param Idempotency-Key header string true "幂等键"
|
||||
// @Param If-Match header string true "当前 Revision ETag"
|
||||
// @Success 200 {object} identity.Revision
|
||||
// @Failure 401 {object} ErrorEnvelope
|
||||
// @Failure 403 {object} ErrorEnvelope
|
||||
// @Failure 409 {object} ErrorEnvelope
|
||||
// @Failure 412 {object} ErrorEnvelope
|
||||
// @Failure 428 {object} ErrorEnvelope
|
||||
// @Router /api/admin/system/identity/revisions/{revisionID}/activate [post]
|
||||
func (s *Server) activateIdentityRevision(w http.ResponseWriter, r *http.Request) {
|
||||
s.runIdentityRevisionAction(w, r, "revision.activate", func(expected int64, traceID, auditID string) (identity.Revision, error) {
|
||||
return s.identityRuntime.Activate(r.Context(), r.PathValue("revisionID"), expected, traceID, auditID)
|
||||
})
|
||||
}
|
||||
|
||||
// rollbackIdentityRevision godoc
|
||||
// @Summary 回滚统一认证 Revision
|
||||
// @Tags identity
|
||||
// @Produce json
|
||||
// @Security BearerAuth
|
||||
// @Param revisionID path string true "Revision ID"
|
||||
// @Param Idempotency-Key header string true "幂等键"
|
||||
// @Param If-Match header string true "当前 Revision ETag"
|
||||
// @Success 200 {object} identity.Revision
|
||||
// @Failure 401 {object} ErrorEnvelope
|
||||
// @Failure 403 {object} ErrorEnvelope
|
||||
// @Failure 409 {object} ErrorEnvelope
|
||||
// @Failure 412 {object} ErrorEnvelope
|
||||
// @Failure 428 {object} ErrorEnvelope
|
||||
// @Router /api/admin/system/identity/revisions/{revisionID}/rollback [post]
|
||||
func (s *Server) rollbackIdentityRevision(w http.ResponseWriter, r *http.Request) {
|
||||
s.runIdentityRevisionAction(w, r, "revision.rollback", func(expected int64, traceID, auditID string) (identity.Revision, error) {
|
||||
return s.identityRuntime.Rollback(r.Context(), r.PathValue("revisionID"), expected, traceID, auditID)
|
||||
})
|
||||
}
|
||||
|
||||
// disableIdentityConfiguration godoc
|
||||
// @Summary 禁用统一认证
|
||||
// @Description 保留 Superseded Revision 供回滚，清理 BFF Session，并继续允许本地管理登录。
|
||||
// @Tags identity
|
||||
// @Produce json
|
||||
// @Security BearerAuth
|
||||
// @Param Idempotency-Key header string true "幂等键"
|
||||
// @Param If-Match header string true "当前 Active Revision ETag"
|
||||
// @Success 200 {object} identity.Revision
|
||||
// @Failure 401 {object} ErrorEnvelope
|
||||
// @Failure 403 {object} ErrorEnvelope
|
||||
// @Failure 409 {object} ErrorEnvelope
|
||||
// @Failure 412 {object} ErrorEnvelope
|
||||
// @Failure 428 {object} ErrorEnvelope
|
||||
// @Router /api/admin/system/identity/disable [post]
|
||||
func (s *Server) disableIdentityConfiguration(w http.ResponseWriter, r *http.Request) {
|
||||
expectedVersion, ok := requiredIdentityVersion(w, r)
|
||||
if !ok {
|
||||
|
||||
Reference in New Issue
Block a user