openapi

IAM API 契约

api/ 是 IAM 的机器契约层。字段、路径、RPC、兼容性和错误语义以这里的 OpenAPI 与 proto 为准；docs/ 只解释设计和接入方式。

目录

api/
├── rest/
│   ├── authn.v2.yaml
│   ├── authz.v2.yaml
│   ├── identity.v2.yaml
│   ├── idp.v2.yaml
│   └── suggest.v2.yaml
└── grpc/
    └── iam/{authn,authz,identity,idp}/v2/*.proto

REST 能力

常用端点示例：

POST /api/v2/authn/login
POST /api/v2/authn/refresh_token
POST /api/v2/authn/logout
GET  /.well-known/jwks.json
POST /api/v2/authz/check
GET  /api/v2/identity/me
POST /api/v2/identity/profiles
GET  /api/v2/identity/profile-links
GET  /api/v2/suggest/profile

实际注册位置在 internal/apiserver/transport/rest，路由矩阵由 internal/apiserver/transport/rest/router_matrix_test.go 保护。

gRPC 能力

服务注册位置在 internal/apiserver/transport/grpc/registry.go，proto 与注册关系由 internal/apiserver/transport/grpc/proto_contract_test.go 保护。

安全约定

• REST 受保护路由使用 Authorization: Bearer <JWT>；公开面包括健康检查、登录、JWKS 和部分 public/info 路由。
• gRPC 由 process 层配置 mTLS、service token、ACL 和 audit interceptor。
• 离线 JWKS 验签只证明签名、issuer/audience 和过期时间；撤销、会话、用户或账号状态以在线 Verify 能力为准。

验证

make api-validate
go test ./internal/apiserver/transport/rest ./internal/apiserver/transport/grpc

make api-validate 需要 Docker daemon；它会运行 scripts/validate-openapi.sh、scripts/check-openapi-contracts.py 和 scripts/check-route-contracts.py。