创建单点登录配置

SSO配置增删改查创建新全局SSO配置。

POST/api/v1/sso/configurations

操作 ID

CreateSSOConfig

起始版本

1.0.0

执行模式

同步

认证信息

需要认证

认证信息

调用该 API 时需要在请求头中携带以下认证信息。

Authorizationstring必填

Bearer 令牌

X-Tenant-IDstring

X-Tenant-ID

请求参数

application/json

请求体字段

tenantUuid
String必填
租户UUID。
示例： deprecated-tenant-uuid
displayName
String必填
显示名称。用于界面展示。
示例： Corporate SSO
providerType
String必填
身份提供方类型。
示例： OIDC
protocol
String必填
认证协议。
示例： oidc
oidcConfig
Object必填
OIDC配置信息。
- clientId
  String
  客户端ID。
  示例： my-client-id
- clientSecret
  String
  客户端密钥。
  示例： s3cr3t
- wellKnownUrl
  String
  OIDC发现端点地址。
  示例： https://idp.example.com/.well-known/openid-configuration
- redirectUri
  String
  重定向地址。
  示例： https://zcf.example.com/sso/callback
- scope
  String
  作用范围。
  示例： openid profile email
- configName
  String
  配置名称。
  示例： Corporate OIDC

响应状态

200 OK

该 API 成功时返回以下响应结构。

uuid
String
资源的UUID，唯一标识该资源。
示例： sso-cfg-001
tenantUuid
String
租户UUID。
示例： deprecated-tenant-uuid
issuer
String
签发方。
示例： https://idp.example.com
displayName
String
显示名称。用于界面展示。
示例： Corporate SSO
providerType
String
身份提供方类型。
示例： OIDC
protocol
String
认证协议。
示例： oidc
oidcConfig
Object
OIDC配置信息。
- clientId
  String
  客户端ID。
  示例： my-client-id
- clientSecret
  String
  客户端密钥。
  示例： s3cr3t
- wellKnownUrl
  String
  OIDC发现端点地址。
  示例： https://idp.example.com/.well-known/openid-configuration
- redirectUri
  String
  重定向地址。
  示例： https://zcf.example.com/sso/callback
- scope
  String
  作用范围。
  示例： openid profile email
- configName
  String
  配置名称。
  示例： Corporate OIDC
samlConfig
Object
SAML配置信息。
- idpEntityId
  String
  身份提供方实体ID。
  示例： https://idp.example.com/saml/metadata
- idpSsoUrl
  String
  身份提供方单点登录地址。
  示例： https://idp.example.com/saml/sso
- idpSloUrl
  String
  身份提供方单点登出地址。
  示例： https://idp.example.com/saml/slo
- idpCertificate
  String
  身份提供方证书。
  示例： -----BEGIN CERTIFICATE----- ...
- idpMetadataUrl
  String
  身份提供方元数据地址。
  示例： https://idp.example.com/saml/metadata.xml
- spEntityId
  String
  服务提供方实体ID。
  示例： https://zcf.example.com/saml/sp
- nameIdFormat
  String
  用户标识格式。
  示例： urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
- signRequests
  Boolean
  是否对请求签名。
  示例： true
- forceAuthn
  Boolean
  是否强制重新认证。
  示例： false
- spCertificatePem
  String
  服务提供方证书内容。
  示例： -----BEGIN CERTIFICATE----- ...
ldapConfig
Object
LDAP配置信息。
- serverAddress
  String
  服务地址。
  示例： ldap.example.com
- port
  Integer
  端口号。
  示例： 389
- baseDn
  String
  LDAP搜索基础路径。
  示例： dc=example,dc=com
- bindDn
  String
  连接LDAP服务器使用的绑定路径。
  示例： cn=admin,dc=example,dc=com
- bindPassword
  String
  LDAP绑定密码。
  示例： bindP@ssw0rd
- userSearchBase
  String
  用户搜索基础路径。
  示例： ou=users,dc=example,dc=com
- userSearchFilter
  String
  用户搜索过滤条件。
  示例： (uid=%s)
- useSsl
  Boolean
  是否使用加密连接。
  示例： true
userProvisioning
String
用户自动开通配置。
示例： auto
groupProvisioning
String
用户组自动开通配置。
示例： sync
attributeMappings
LinkedHashMap
属性映射关系。
示例： (nested object)
groupMappings
List
用户组映射关系。
示例： (nested array)
- idpGroup
  String
  身份提供方用户组。
  示例： idp-admins
- zcfRole
  String
  分配给该身份源组的角色名称。
  示例： admin
source
String
来源信息。
示例： manual
status
String
状态信息。
示例： active
enabled
Boolean
是否启用。
示例： true
lastTestAt
String
最近一次测试时间。
示例： 2026-01-15T08:00:00Z
lastTestResult
String
最近一次连通性测试结果消息。
示例： success
createdAt
String
创建时间。
示例： 2026-01-15T08:00:00Z
updatedAt
String
更新时间。
示例： 2026-01-15T08:00:00Z
description
String
资源的详细描述。
示例： Corporate identity provider with SCIM provisioning
provisioningModes
List
预配模式。
示例： item1,item2
builtIn
Boolean
内置。
示例： true
associatedPlatformCount
Integer
关联平台数量。
示例： 2

请求示例

curl -X POST '{host}/api/v1/sso/configurations' \
  -H 'Authorization: Bearer {token}' \
  -H 'Content-Type: application/json' \
  -d '{
  "tenantUuid": "deprecated-tenant-uuid",
  "displayName": "Corporate SSO",
  "providerType": "OIDC",
  "protocol": "oidc",
  "oidcConfig": {
    "clientId": "my-client-id",
    "clientSecret": "s3cr3t",
    "wellKnownUrl": "https://idp.example.com/.well-known/openid-configuration",
    "redirectUri": "https://zcf.example.com/sso/callback",
    "scope": "openid profile email",
    "configName": "Corporate OIDC"
  },
  "samlConfig": {
    "idpEntityId": "https://idp.example.com/saml/metadata",
    "idpSsoUrl": "https://idp.example.com/saml/sso",
    "idpSloUrl": "https://idp.example.com/saml/slo",
    "idpCertificate": "-----BEGIN CERTIFICATE-----\n...",
    "idpMetadataUrl": "https://idp.example.com/saml/metadata.xml",
    "spEntityId": "https://zcf.example.com/saml/sp",
    "nameIdFormat": "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress",
    "signRequests": "true",
    "forceAuthn": "false",
    "spCertificatePem": "-----BEGIN CERTIFICATE-----\n..."
  },
  "ldapConfig": {
    "serverAddress": "ldap.example.com",
    "port": "389",
    "baseDn": "dc=example,dc=com",
    "bindDn": "cn=admin,dc=example,dc=com",
    "bindPassword": "bindP@ssw0rd",
    "userSearchBase": "ou=users,dc=example,dc=com",
    "userSearchFilter": "(uid=%s)",
    "useSsl": "true"
  },
  "userProvisioning": "auto",
  "groupProvisioning": "sync",
  "attributeMappings": {},
  "groupMappings": [
    {
      "idpGroup": "idp-admins",
      "zcfRole": "admin"
    }
  ],
  "description": "Corporate identity provider with SCIM provisioning",
  "provisioningModes": [
    "{provisioningModes}"
  ]
}'

响应示例

{
  "uuid": "sso-cfg-001",
  "issuer": "https://idp.example.com",
  "displayName": "Corporate SSO",
  "providerType": "OIDC",
  "protocol": "oidc",
  "oidcConfig": {},
  "samlConfig": {}
}

变更历史

查看全部变更历史

变更时间变更内容概要操作

变更时间
2026-06-26
新增请求体字段 description, provisioningModes新增响应字段 associatedPlatformCount, builtIn, description...
查看 API

Agent 插件

Agent 管理

资产

指标目录与保留策略

采集任务

基础设施综合

安装器

生命周期

OTA 升级计划

OTA 版本与策略

联邦与 SSO

变更管理

资源删除

生命周期升级

指标采集

监控缓存

监控查询与概览

自动修复

监控综合

Grafana 集成

Grafana 仪表盘

日志

性能剖析

Zaku

告警规则

告警模板

告警通道与集成

告警事件

告警路由与策略

值班

SLO

健康检查

凭证

ZIAM

安全

ZMetis 审计

平台管理

平台联邦

平台自监控

平台健康

平台综合

ZMetis 任务

认证信息

请求参数

请求体字段

响应状态

变更历史