{ "swagger": "2.0", "info": { "description": "SAML 2.0服务，提供企业级SAML SSO认证", "title": "SAML 服务 API", "contact": {}, "version": "1.0.0" }, "basePath": "/bff/saml/api/v1", "paths": { "/admin/saml/providers": { "get": { "security": [ { "bearerAuth": [] } ], "description": "获取当前租户的所有SAML身份提供商列表", "produces": [ "application/json" ], "tags": [ "SAML 管理" ], "summary": "列出SAML IdP", "parameters": [ { "type": "integer", "default": 1, "description": "页码", "name": "page", "in": "query" }, { "type": "integer", "default": 20, "description": "每页数量", "name": "page_size", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/gitee_com_autional_service-saml_internal_handler_dto.SamlProviderListDetailResponse" } } } }, "post": { "security": [ { "bearerAuth": [] } ], "description": "注册一个新的SAML身份提供商配置", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "SAML 管理" ], "summary": "注册SAML IdP", "parameters": [ { "description": "SAML IdP配置", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/gitee_com_autional_service-saml_internal_handler_dto.SamlProviderRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/gitee_com_autional_service-saml_internal_handler_dto.SamlProviderItemDetailResponse" } } } } }, "/admin/saml/providers/{provider_id}": { "get": { "security": [ { "bearerAuth": [] } ], "description": "根据ID获取SAML身份提供商详情", "produces": [ "application/json" ], "tags": [ "SAML 管理" ], "summary": "获取SAML IdP详情", "parameters": [ { "type": "string", "description": "SAML IdP ID", "name": "provider_id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/gitee_com_autional_service-saml_internal_handler_dto.SamlProviderItemDetailResponse" } } } }, "put": { "security": [ { "bearerAuth": [] } ], "description": "更新SAML身份提供商配置", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "SAML 管理" ], "summary": "更新SAML IdP", "parameters": [ { "type": "string", "description": "SAML IdP ID", "name": "provider_id", "in": "path", "required": true }, { "description": "SAML IdP更新配置", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/gitee_com_autional_service-saml_internal_handler_dto.SamlProviderRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/gitee_com_autional_service-saml_internal_handler_dto.SamlProviderItemDetailResponse" } } } }, "delete": { "security": [ { "bearerAuth": [] } ], "description": "删除SAML身份提供商配置", "produces": [ "application/json" ], "tags": [ "SAML 管理" ], "summary": "删除SAML IdP", "parameters": [ { "type": "string", "description": "SAML IdP ID", "name": "provider_id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/dto.SimpleResponse" } } } } }, "/admin/saml/providers/{provider_id}/attribute-mapping": { "put": { "security": [ { "bearerAuth": [] } ], "description": "更新SAML IdP的属性映射配置", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "SAML 管理" ], "summary": "更新属性映射", "parameters": [ { "type": "string", "description": "SAML IdP ID", "name": "provider_id", "in": "path", "required": true }, { "description": "属性映射", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/gitee_com_autional_service-saml_internal_handler_dto.UpdateAttributeMappingRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/dto.SimpleResponse" } } } } }, "/admin/saml/sessions": { "get": { "security": [ { "bearerAuth": [] } ], "description": "管理端：分页查询租户内SAML会话", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "SAML - Admin" ], "summary": "查询SAML会话列表（管理端）", "parameters": [ { "type": "integer", "description": "页码", "name": "page", "in": "query" }, { "type": "integer", "description": "每页数量", "name": "page_size", "in": "query" }, { "type": "string", "description": "排序字段", "name": "sort_by", "in": "query" }, { "type": "string", "description": "排序方向 (asc/desc)", "name": "sort_order", "in": "query" } ], "responses": { "200": { "description": "会话列表", "schema": { "$ref": "#/definitions/dto.ListResponse-gitee_com_autional_service-saml_internal_handler_dto_SamlSessionItem" } }, "400": { "description": "参数错误", "schema": { "$ref": "#/definitions/dto.SimpleResponse" } }, "401": { "description": "未认证", "schema": { "$ref": "#/definitions/dto.SimpleResponse" } }, "403": { "description": "权限不足", "schema": { "$ref": "#/definitions/dto.SimpleResponse" } } } } }, "/admin/saml/user-links": { "get": { "security": [ { "bearerAuth": [] } ], "description": "管理端：分页查询租户内用户SAML关联账户", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "SAML - Admin" ], "summary": "查询用户SAML绑定列表（管理端）", "parameters": [ { "type": "integer", "description": "页码", "name": "page", "in": "query" }, { "type": "integer", "description": "每页数量", "name": "page_size", "in": "query" }, { "type": "string", "description": "排序字段", "name": "sort_by", "in": "query" }, { "type": "string", "description": "排序方向 (asc/desc)", "name": "sort_order", "in": "query" } ], "responses": { "200": { "description": "绑定列表", "schema": { "$ref": "#/definitions/dto.ListResponse-gitee_com_autional_service-saml_internal_handler_dto_SamlUserLinkItem" } }, "400": { "description": "参数错误", "schema": { "$ref": "#/definitions/dto.SimpleResponse" } }, "401": { "description": "未认证", "schema": { "$ref": "#/definitions/dto.SimpleResponse" } }, "403": { "description": "权限不足", "schema": { "$ref": "#/definitions/dto.SimpleResponse" } } } } }, "/admin/saml/user-links/{user_link_id}": { "delete": { "security": [ { "bearerAuth": [] } ], "description": "管理端：删除指定ID的用户SAML关联账户", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "SAML - Admin" ], "summary": "删除用户SAML绑定（管理端）", "parameters": [ { "type": "string", "description": "绑定记录ID", "name": "user_link_id", "in": "path", "required": true } ], "responses": { "200": { "description": "删除成功", "schema": { "$ref": "#/definitions/dto.SimpleResponse" } }, "400": { "description": "参数错误", "schema": { "$ref": "#/definitions/dto.SimpleResponse" } }, "401": { "description": "未认证", "schema": { "$ref": "#/definitions/dto.SimpleResponse" } }, "403": { "description": "权限不足", "schema": { "$ref": "#/definitions/dto.SimpleResponse" } } } } }, "/internal/saml/erase-user-links": { "post": { "description": "内部API：删除用户的所有SAML绑定（GDPR擦除，compliance-service 调用）。需InternalAPIKeyAuth认证。", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "SAML - 内部接口" ], "summary": "擦除用户SAML绑定", "parameters": [ { "description": "擦除请求", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/gitee_com_autional_service-saml_internal_handler_dto.EraseUserSamlLinksRequest" } } ], "responses": { "200": { "description": "擦除成功", "schema": { "$ref": "#/definitions/dto.SimpleResponse" } } } } }, "/internal/saml/user-links": { "get": { "description": "内部API：按 user_id + tenant_id 查询用户的SAML关联账户（identity-service 调用）。需InternalAPIKeyAuth认证。", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "SAML - 内部接口" ], "summary": "查询用户SAML绑定列表", "parameters": [ { "type": "string", "description": "用户ID", "name": "user_id", "in": "query", "required": true }, { "type": "string", "description": "租户ID", "name": "tenant_id", "in": "query", "required": true } ], "responses": { "200": { "description": "绑定列表", "schema": { "$ref": "#/definitions/gitee_com_autional_service-saml_internal_handler_dto.SamlLinkedAccountsResponse" } }, "400": { "description": "参数错误", "schema": { "$ref": "#/definitions/dto.SimpleResponse" } }, "401": { "description": "未认证", "schema": { "$ref": "#/definitions/dto.SimpleResponse" } } } } }, "/internal/saml/user-links/{user_link_id}": { "delete": { "description": "内部API：按 id + user_id + tenant_id 删除用户的SAML关联账户（identity-service 调用）。需InternalAPIKeyAuth认证。", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "SAML - 内部接口" ], "summary": "删除用户SAML绑定", "parameters": [ { "type": "string", "description": "绑定ID", "name": "user_link_id", "in": "path", "required": true }, { "type": "string", "description": "用户ID", "name": "user_id", "in": "query", "required": true }, { "type": "string", "description": "租户ID", "name": "tenant_id", "in": "query", "required": true } ], "responses": { "200": { "description": "删除成功", "schema": { "$ref": "#/definitions/dto.SimpleResponse" } }, "400": { "description": "参数错误", "schema": { "$ref": "#/definitions/dto.SimpleResponse" } }, "401": { "description": "未认证", "schema": { "$ref": "#/definitions/dto.SimpleResponse" } } } } }, "/saml/{provider_id}/acs": { "post": { "description": "接收SAML IdP的断言响应，验证并返回访问令牌", "consumes": [ "application/x-www-form-urlencoded" ], "produces": [ "application/json" ], "tags": [ "SAML" ], "summary": "断言消费服务", "parameters": [ { "type": "string", "description": "SAML IdP ID", "name": "provider_id", "in": "path", "required": true }, { "type": "string", "description": "Base64编码的SAML响应", "name": "SAMLResponse", "in": "formData", "required": true }, { "type": "string", "description": "RelayState", "name": "RelayState", "in": "formData" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/gitee_com_autional_service-saml_internal_handler_dto.SAMLTokenDetailResponse" } } } } }, "/saml/{provider_id}/login": { "get": { "description": "发起SAML SSO登录，重定向到IdP", "produces": [ "application/json" ], "tags": [ "SAML" ], "summary": "SP-initiated SSO", "parameters": [ { "type": "string", "description": "SAML IdP ID", "name": "provider_id", "in": "path", "required": true } ], "responses": { "302": { "description": "Redirect to IdP SSO URL", "schema": { "type": "string" } } } } }, "/saml/{provider_id}/metadata": { "get": { "description": "获取SAML服务提供商的元数据XML", "produces": [ "application/xml" ], "tags": [ "SAML" ], "summary": "获取SP元数据", "parameters": [ { "type": "string", "description": "SAML IdP ID", "name": "provider_id", "in": "path", "required": true } ], "responses": { "200": { "description": "SAML metadata XML", "schema": { "type": "string" } } } } }, "/saml/{provider_id}/slo": { "get": { "description": "处理SAML单点登出请求", "consumes": [ "application/x-www-form-urlencoded" ], "produces": [ "application/json" ], "tags": [ "SAML" ], "summary": "单点登出", "parameters": [ { "type": "string", "description": "SAML IdP ID", "name": "provider_id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/gitee_com_autional_service-saml_internal_handler_dto.SAMLSLODetailResponse" } } } } }, "/saml/{provider_id}/slo/sp": { "get": { "description": "构建SAML LogoutRequest并重定向至IdP的SLO端点", "produces": [ "application/json" ], "tags": [ "SAML" ], "summary": "SP发起的SAML单点登出", "parameters": [ { "type": "string", "description": "SAML Provider ID", "name": "provider_id", "in": "path", "required": true }, { "type": "string", "description": "User ID", "name": "user_id", "in": "query", "required": true }, { "type": "string", "description": "Session Index", "name": "session_index", "in": "query" } ], "responses": { "302": { "description": "重定向至IdP SLO端点" }, "400": { "description": "缺少user_id", "schema": { "$ref": "#/definitions/gitee_com_autional_service-saml_internal_handler_dto.SAMLSLOResponse" } }, "404": { "description": "Provider未找到", "schema": { "$ref": "#/definitions/gitee_com_autional_service-saml_internal_handler_dto.SAMLSLOResponse" } } } } } }, "definitions": { "dto.DataResponse-string": { "type": "object", "properties": { "code": { "type": "integer" }, "data": { "type": "string" }, "message": { "type": "string" }, "timestamp": { "type": "string" } } }, "dto.ListResponse-gitee_com_autional_service-saml_internal_handler_dto_SamlSessionItem": { "type": "object", "properties": { "code": { "type": "integer" }, "items": { "description": "统一使用 items", "type": "array", "items": { "$ref": "#/definitions/gitee_com_autional_service-saml_internal_handler_dto.SamlSessionItem" } }, "message": { "type": "string" }, "pagination": { "description": "分页信息（嵌套对象）", "allOf": [ { "$ref": "#/definitions/dto.PageInfo" } ] }, "timestamp": { "type": "string" }, "total": { "description": "总条数（平铺，便于直接读取）", "type": "integer" } } }, "dto.ListResponse-gitee_com_autional_service-saml_internal_handler_dto_SamlUserLinkItem": { "type": "object", "properties": { "code": { "type": "integer" }, "items": { "description": "统一使用 items", "type": "array", "items": { "$ref": "#/definitions/gitee_com_autional_service-saml_internal_handler_dto.SamlUserLinkItem" } }, "message": { "type": "string" }, "pagination": { "description": "分页信息（嵌套对象）", "allOf": [ { "$ref": "#/definitions/dto.PageInfo" } ] }, "timestamp": { "type": "string" }, "total": { "description": "总条数（平铺，便于直接读取）", "type": "integer" } } }, "dto.PageInfo": { "type": "object", "properties": { "has_next": { "description": "HasNext indicates whether there is a next page", "type": "boolean" }, "has_prev": { "description": "HasPrev indicates whether there is a previous page", "type": "boolean" }, "page": { "description": "Page is the current page number (1-based)", "type": "integer" }, "page_size": { "description": "PageSize is the number of items per page", "type": "integer" }, "total": { "description": "Total is the total number of items across all pages", "type": "integer" }, "total_pages": { "description": "TotalPages is the total number of pages", "type": "integer" } } }, "dto.SimpleResponse": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" }, "timestamp": { "type": "string" } } }, "gitee_com_autional_service-saml_internal_handler_dto.EraseUserSamlLinksRequest": { "type": "object", "required": [ "tenant_id", "user_id" ], "properties": { "tenant_id": { "type": "string" }, "user_id": { "type": "string" } } }, "gitee_com_autional_service-saml_internal_handler_dto.SAMLSLODetailResponse": { "type": "object", "properties": { "code": { "type": "integer" }, "data": { "$ref": "#/definitions/gitee_com_autional_service-saml_internal_handler_dto.SAMLSLOResponse" }, "message": { "type": "string" }, "timestamp": { "type": "string" } } }, "gitee_com_autional_service-saml_internal_handler_dto.SAMLSLOResponse": { "type": "object", "properties": { "logout_count": { "type": "integer" }, "message": { "type": "string" }, "name_id": { "type": "string" }, "status": { "type": "string", "example": "success" } } }, "gitee_com_autional_service-saml_internal_handler_dto.SAMLTokenDetailResponse": { "type": "object", "properties": { "code": { "type": "integer" }, "data": { "$ref": "#/definitions/gitee_com_autional_service-saml_internal_handler_dto.SAMLTokenResponse" }, "message": { "type": "string" }, "timestamp": { "type": "string" } } }, "gitee_com_autional_service-saml_internal_handler_dto.SAMLTokenResponse": { "type": "object", "properties": { "access_token": { "type": "string" }, "expires_in": { "type": "integer", "example": 3600 }, "relay_state": { "type": "string" }, "token_type": { "type": "string", "example": "Bearer" } } }, "gitee_com_autional_service-saml_internal_handler_dto.SamlLinkedAccountItem": { "type": "object", "properties": { "email": { "type": "string", "example": "user@example.com" }, "id": { "type": "string", "example": "01JNXXXXX..." }, "linked_at": { "type": "string", "example": "2026-05-31T10:00:00Z" }, "name_id": { "type": "string", "example": "user@idp.com" }, "provider_id": { "type": "string", "example": "01JNPPPPP..." }, "provider_name": { "type": "string", "example": "Azure AD" } } }, "gitee_com_autional_service-saml_internal_handler_dto.SamlLinkedAccountsResponse": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/definitions/gitee_com_autional_service-saml_internal_handler_dto.SamlLinkedAccountItem" } } } }, "gitee_com_autional_service-saml_internal_handler_dto.SamlProviderItem": { "type": "object", "properties": { "allow_idp_initiated": { "type": "boolean", "example": false }, "certificate_expiry": { "type": "string" }, "created_at": { "type": "string", "example": "2026-05-31T10:00:00Z" }, "default_redirect_uri": { "type": "string", "example": "https://app.example.com" }, "enabled": { "type": "boolean", "example": true }, "entity_id": { "type": "string", "example": "https://login.microsoftonline.com/example/saml2" }, "force_authn": { "type": "boolean", "example": false }, "has_backup_cert": { "type": "boolean", "example": false }, "id": { "type": "string", "example": "01JNXXXXX..." }, "name": { "type": "string", "example": "Azure AD" }, "name_id_format": { "type": "string", "example": "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress" }, "slo_url": { "type": "string", "example": "https://login.microsoftonline.com/example/saml2/slo" }, "sso_url": { "type": "string", "example": "https://login.microsoftonline.com/example/saml2" }, "tenant_id": { "type": "string", "example": "01JNYYYYY..." }, "updated_at": { "type": "string", "example": "2026-05-31T10:00:00Z" }, "want_authn_signed": { "type": "boolean", "example": true } } }, "gitee_com_autional_service-saml_internal_handler_dto.SamlProviderItemDetailResponse": { "type": "object", "properties": { "code": { "type": "integer" }, "data": { "$ref": "#/definitions/gitee_com_autional_service-saml_internal_handler_dto.SamlProviderItem" }, "message": { "type": "string" }, "timestamp": { "type": "string" } } }, "gitee_com_autional_service-saml_internal_handler_dto.SamlProviderListData": { "type": "object", "properties": { "providers": { "type": "array", "items": { "$ref": "#/definitions/gitee_com_autional_service-saml_internal_handler_dto.SamlProviderItem" } } } }, "gitee_com_autional_service-saml_internal_handler_dto.SamlProviderListDetailResponse": { "type": "object", "properties": { "code": { "type": "integer" }, "data": { "$ref": "#/definitions/gitee_com_autional_service-saml_internal_handler_dto.SamlProviderListData" }, "message": { "type": "string" }, "timestamp": { "type": "string" } } }, "gitee_com_autional_service-saml_internal_handler_dto.SamlProviderRequest": { "type": "object", "required": [ "certificate", "entity_id", "name", "sso_url" ], "properties": { "allow_idp_initiated": { "type": "boolean", "example": false }, "certificate": { "type": "string", "example": "-----BEGIN CERTIFICATE-----\nMIID\n-----END CERTIFICATE-----" }, "certificate_backup": { "type": "string", "example": "-----BEGIN CERTIFICATE-----\nMIID\n-----END CERTIFICATE-----" }, "default_redirect_uri": { "type": "string", "example": "https://app.example.com" }, "enabled": { "type": "boolean", "example": true }, "entity_id": { "type": "string", "example": "https://login.microsoftonline.com/example/saml2" }, "force_authn": { "type": "boolean", "example": false }, "name": { "type": "string", "example": "Azure AD" }, "name_id_format": { "type": "string", "example": "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress" }, "should_clear_backup": { "type": "boolean", "example": false }, "slo_url": { "type": "string", "example": "https://login.microsoftonline.com/example/saml2/slo" }, "sso_url": { "type": "string", "example": "https://login.microsoftonline.com/example/saml2" }, "want_authn_signed": { "type": "boolean", "example": true } } }, "gitee_com_autional_service-saml_internal_handler_dto.SamlSessionItem": { "type": "object", "properties": { "created_at": { "type": "string", "example": "2026-05-31T10:00:00Z" }, "expires_at": { "type": "string", "example": "2026-06-01T10:00:00Z" }, "id": { "type": "string", "example": "01JNXXXXX..." }, "name_id": { "type": "string", "example": "user@idp.com" }, "provider_id": { "type": "string", "example": "01JNPPPPP..." }, "session_index": { "type": "string", "example": "session-abc123" }, "tenant_id": { "type": "string", "example": "01JNYYYYY..." }, "user_id": { "type": "string", "example": "01JNZZZZZ..." } } }, "gitee_com_autional_service-saml_internal_handler_dto.SamlUserLinkItem": { "type": "object", "properties": { "created_at": { "type": "string", "example": "2026-05-31T10:00:00Z" }, "email": { "type": "string", "example": "user@example.com" }, "id": { "type": "string", "example": "01JNXXXXX..." }, "name_id": { "type": "string", "example": "user@idp.com" }, "provider_id": { "type": "string", "example": "01JNPPPPP..." }, "tenant_id": { "type": "string", "example": "01JNYYYYY..." }, "updated_at": { "type": "string", "example": "2026-05-31T10:00:00Z" }, "user_id": { "type": "string", "example": "01JNZZZZZ..." } } }, "gitee_com_autional_service-saml_internal_handler_dto.UpdateAttributeMappingRequest": { "type": "object", "required": [ "mappings" ], "properties": { "mappings": { "type": "object", "additionalProperties": { "type": "string" } } } } }, "securityDefinitions": { "bearerAuth": { "description": "Type \"Bearer\" followed by a space and JWT token.", "type": "apiKey", "name": "Authorization", "in": "header" } }, "tags": [ { "description": "SAML 2.0 认证接口", "name": "SAML" }, { "description": "SAML 管理接口：IdP/SP 配置", "name": "SAML Admin" } ], "host": "api.autional.cn", "schemes": [ "https" ] }