CreateIdentityProvider - 绑定外部身份提供商
为工作空间绑定钉钉、飞书或 CustomSSO 身份源。CustomSSO 仅异步初始化共享用户池,SAML 登录与 SCIM 同步后续分别配置。
接口说明
功能与前提\nWAITING_CONFIGURATION(待配置)也占用 Workspace 唯一的外部身份源名额,CustomSSO(SAML/OIDC 与 SCIM)与 DingTalk、Feishu 互斥;SCIM 复用 CustomSSO 绑定,不创建第二个身份源。创建其他类型返回 409 IdentityProviderAlreadyBound;解绑完成并移除绑定后才可更换。\n 一个 Workspace 只有一个外部身份源绑定,identityProviderType 支持 DingTalk、Feishu、CustomSSO。CustomSSO 仅初始化共享用户池:不传非空 metadata,不传 true 的 loginEnabled、syncEnabled;默认两个开关均关闭。协议、SAML 配置通过 UpdateIdentityProvider 保存,SCIM 通过独立接口配置,不要求先保存 SAML。初始化完成但未保存 SAML Metadata 时返回 WAITING_CONFIGURATION(待配置);CONFIGURED、SYNCING 表示资源仍在初始化,可通过 GetIdentityProvider 查询。保存 Metadata 后返回 UPDATING,完成配置及内部 OIDC 发布后返回 READY;READY 不代表登录开关已开启。相同 CustomSSO 绑定在初始化受理或初始化完成后可返回已有绑定,不能将所有状态都视作可重复创建。\nDingTalk 的 metadata 必填 appKey、appSecret、corpId;Feishu 必填 appId、appSecret。厂商登录开关缺省开启,同步开关缺省关闭;同步开启时还要求 encryptKey、verificationToken。厂商 syncOnBind、syncScope 保持既有按部门同步定义;CustomSSO 初始化不要用这些厂商拉取参数替代 SCIM 配置。\n\n## 请求与示例\nPOST /workspaces/{workspaceId}/identity-providers\n 调用约定:按目标 Workspace 的地域调用,使用有相应 Workspace 身份源资源权限的 AK/STS 身份。下文示例中的 ws-example、URL、证书和 Token 均为占位值,需替换为真实值。请求体示例表示公开 API 的 body 参数内容,不是后端直连接口额外的 body 包装。返回示例只展示业务部分,外层还包括 requestId、success、code、message、httpStatusCode;排障请保留 requestId,不记录密钥。业务任务异步不意味着 HTTP 请求长连接等待完成。\ntext\nPOST /workspaces/ws-example/identity-providers\n{"identityProviderType": "CustomSSO"}\n\n\n## 返回示例\njson\n{\n "data": {\n "workspaceId": "ws-example",\n "identityProviderType": "CustomSSO",\n "loginEnabled": false,\n "syncEnabled": false,\n "status": "WAITING_CONFIGURATION"\n }\n}\n\n\n## 错误与处理\n 错误处理:400 InvalidParameter 表示参数或当前配置前提不满足;404 IdentityProviderNotFound 表示没有匹配类型的绑定。同步调用上游失败可能返回 503 IdentityProviderProvisioningUnavailable;保留请求 ID 排查,不把读取失败解释为未配置。实际鉴权和 Workspace 不存在错误沿用公共错误处理。\n409 IdentityProviderAlreadyBound:已有外部绑定,先查询并复用正确的绑定,不自动整体解绑。初始化请求失败时保留请求 ID 排查;已有绑定时先查询当前状态,避免重复创建。\n\n## 调用关系与使用边界\nCustomSSO 调用顺序:先创建绑定,初始化完成返回 WAITING_CONFIGURATION(待配置);如返回 CONFIGURED、SYNCING,可通过 GetIdentityProvider 查询;随后可分别配置 SAML 和 SCIM,二者不要求按固定先后顺序完成。SAML 使用 GetIdentityProviderServiceProvider 获取我方 SP 信息、UpdateIdentityProvider 保存外部 IdP 配置。SCIM 使用 PrepareIdentityProviderSCIM 获取预配地址和凭据,再用 UpdateIdentityProviderSCIM 确认同步。
调试
您可以在OpenAPI Explorer中直接运行该接口,免去您计算签名的困扰。运行成功后,OpenAPI Explorer可以自动生成SDK代码示例。
调试
授权信息
|
操作 |
访问级别 |
资源类型 |
条件关键字 |
关联操作 |
|
agentcore:CreateIdentityProvider |
create |
*IdentityProvider
|
无 | 无 |
请求语法
POST /workspaces/{workspaceId}/identity-providers HTTP/1.1
路径参数
|
名称 |
类型 |
必填 |
描述 |
示例值 |
| workspaceId |
string |
是 |
工作空间 ID。 |
ws-123456 |
请求参数
|
名称 |
类型 |
必填 |
描述 |
示例值 |
| body |
object |
否 |
绑定外部身份提供商的请求内容。 |
|
| identityProviderType |
string |
是 |
外部身份提供商类型。可选值:DingTalk、Feishu。 |
DingTalk |
| loginEnabled |
boolean |
否 |
是否允许工作空间用户通过该外部身份提供商登录。 |
|
| metadata |
object |
否 |
外部身份提供商的应用配置。绑定 DingTalk 时需要提供 appKey、appSecret 和 corpId,绑定 Feishu 时需要提供 appId 和 appSecret。 |
|
| appId |
string |
否 |
飞书应用的 App ID。绑定类型为 Feishu 时必填。 |
cli_exampleappid01 |
| appKey |
string |
否 |
钉钉应用的 AppKey。绑定类型为 DingTalk 时必填。 |
dingexampleappkey01 |
| appSecret |
string |
否 |
必填。外部身份提供商应用的密钥。仅用于写入,查询接口不返回该字段。 |
example-app-secret |
| corpId |
string |
否 |
钉钉企业的 CorpId。绑定类型为 DingTalk 时必填。 |
dingexamplecorpid01 |
| encryptKey |
string |
否 |
事件订阅的数据加密密钥,取值与外部身份提供商应用中配置的一致。仅用于写入,查询接口不返回该字段。 |
example-encrypt-key |
| verificationToken |
string |
否 |
事件订阅的校验令牌,取值与外部身份提供商应用中配置的一致。仅用于写入,查询接口不返回该字段。 |
example-verification-token |
| syncEnabled |
boolean |
否 |
是否开启组织成员同步。开启后由该外部身份提供商同步组织成员为工作空间用户。 |
|
| syncOnBind |
boolean |
否 |
DingTalk、Feishu 绑定时控制首次同步;省略或 null 默认 true,false 仅配置,后续显式触发同步。CustomSSO 不使用厂商拉取链路。 |
|
| syncScope |
object |
否 |
沿用按部门同步范围定义;创建省略默认 AllAuthorized,首次厂商同步由 syncOnBind 决定;更新省略或 null 保留原值,更新保存范围不自动执行全量同步。 |
|
| departmentIds |
array |
否 |
SelectedDepartments 时至少包含一个非空部门 ID,应取自 ListIdentityProviderDepartments;AllAuthorized 时传空数组或省略。 |
["10001"] |
|
string |
否 |
身份源返回的部门唯一标识,取自 ListIdentityProviderDepartments。 |
10001 |
|
| mode |
string |
否 |
AllAuthorized:全部授权范围,受应用通讯录授权限制;SelectedDepartments:选中部门及所有子部门。显式提交 syncScope 时必须提供有效 mode,由后端校验。 |
SelectedDepartments |
返回参数
|
名称 |
类型 |
描述 |
示例值 |
|
object |
|||
| code |
string |
业务状态码。 |
SUCCESS |
| data |
object |
外部身份提供商的绑定信息。 |
|
| configuration |
object |
SAML 实际配置只在 GetIdentityProvider 按需回读;SCIM 查询和准备返回实际接收状态及 URL。 |
|
| bindingType |
string |
HTTP-Redirect 或 HTTP-POST;手填时必填,查询返回短名称。 |
HTTP-Redirect |
| entityId |
string |
手填时必填,非空且不超过 2048 字符;已有配置不支持更换。与 SP 查询的我方 Entity ID 不同。 |
https://idp.example.com/entity |
| loginUrl |
string |
手填时必填,为绝对 HTTPS URL,不含用户凭据和片段。 |
https://idp.example.com/sso |
| ssoStatus |
string |
实际开关值 Enabled 或 Disabled,不等同 AC 保存的 loginEnabled 期望值。 |
Enabled |
| identityProviderType |
string |
外部身份提供商类型。可选值:DingTalk、Feishu。 |
DingTalk |
| loginEnabled |
boolean |
是否允许工作空间用户通过该外部身份提供商登录。 |
|
| protocol |
string |
当前仅支持 SAML;未保存有效配置时可不返回。不支持用 OIDC 占位初始化。 |
SAML |
| saml |
object |
输入支持 XML 与完整手填二选一。查询返回标准化配置,不回显原始 XML;未配置时可省略。 |
|
| bindingType |
string |
HTTP-Redirect 或 HTTP-POST;手填时必填,查询返回短名称。 |
HTTP-Redirect |
| entityId |
string |
手填时必填,非空且不超过 2048 字符;已有配置不支持更换。与 SP 查询的我方 Entity ID 不同。 |
https://idp.example.com/entity |
| loginUrl |
string |
手填时必填,为绝对 HTTPS URL,不含用户凭据和片段。 |
https://idp.example.com/sso |
| x509Certificates |
array |
手填时必填非空数组,使用 PEM X.509 证书文本;校验当前有效期,去重后最多 2 张。 |
["-----BEGIN CERTIFICATE-----\\nMIICwDCCAaigAwIBAgIULlsHLfcADyBax5ZtFlj+YGzZVo0wDQYJKoZIhvcNAQEL\\nBQAwGjEYMBYGA1UEAwwPaWRwLmV4YW1wbGUuY29tMB4XDTI2MDEwMTAwMDAwMFoX\\nDTM2MDEwMTAwMDAwMFowGjEYMBYGA1UEAwwPaWRwLmV4YW1wbGUuY29tMIIBIjAN\\nBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAto0DN0W1CrPRzK9QZ9A1aApb4Lg8\\noGlp2c0PbN3LokXe/HzwxCMXx65IDnrenttxzTwp9BgUnUN/3LRzWaOL2UQ/vNYN\\nW9LFLkI1T64UPyI7eyi28YlALhb41xkYhEp7rz+MjqifBzVZeTDUxBYtbK2hAhbY\\nEL1+udwsXEx0KB7xuQ/rbI2OKeqAEAD1tfYg7T/SM2wrXNYhx+o1HtchM4/0I8Ok\\nkk27JQ4y3ofzC5sTySmFF1Y7XcpSd+5WSyazedhkAieo8AB01DkJV6nnKfH8sH0E\\nBsnH3FP8FhqCLrIeEkjX9B9OcIRLGjiZqx4u/ryW1QhMldnv+pFfNjWy/wIDAQAB\\nMA0GCSqGSIb3DQEBCwUAA4IBAQC1hSQG8AwtGOoX2gKBK4Hi5XBrBreij8WlLTUW\\nld0FINQ0Rg84f/27CjDthywj6wgxCesCuOVFhpxQa1UacsP/Gcai1aKABtLWImca\\nWECRYK5gDkwhTMFKM9mXA26hH1l4v/UR2iTpEK9H78egC4W7bs2LDTpPryuaNKTq\\nP2O0tMbNkAHB8yecz5LxHXnxadL9Egow25g2RClvpifWqDnuS9TSbKkIWLcPLjoc\\nJj2K9ILpBwhXiXi/BiSgyYTLiYvVvih9vX4s+hKGZNJc0j92YLiOHDF0XH1oxgdV\\njfTmRiedeb2VZJZElptD92z0AqFR7z2d5B+OqpPA2gjuMLV5\\n-----END CERTIFICATE-----"] |
|
string |
一张有效 PEM X.509 签名证书;示例为 idp.example.com 的公开测试证书,实际接入须替换为外部 IdP 的证书。 |
-----BEGIN CERTIFICATE-----\nMIICwDCCAaigAwIBAgIULlsHLfcADyBax5ZtFlj+YGzZVo0wDQYJKoZIhvcNAQEL\nBQAwGjEYMBYGA1UEAwwPaWRwLmV4YW1wbGUuY29tMB4XDTI2MDEwMTAwMDAwMFoX\nDTM2MDEwMTAwMDAwMFowGjEYMBYGA1UEAwwPaWRwLmV4YW1wbGUuY29tMIIBIjAN\nBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAto0DN0W1CrPRzK9QZ9A1aApb4Lg8\noGlp2c0PbN3LokXe/HzwxCMXx65IDnrenttxzTwp9BgUnUN/3LRzWaOL2UQ/vNYN\nW9LFLkI1T64UPyI7eyi28YlALhb41xkYhEp7rz+MjqifBzVZeTDUxBYtbK2hAhbY\nEL1+udwsXEx0KB7xuQ/rbI2OKeqAEAD1tfYg7T/SM2wrXNYhx+o1HtchM4/0I8Ok\nkk27JQ4y3ofzC5sTySmFF1Y7XcpSd+5WSyazedhkAieo8AB01DkJV6nnKfH8sH0E\nBsnH3FP8FhqCLrIeEkjX9B9OcIRLGjiZqx4u/ryW1QhMldnv+pFfNjWy/wIDAQAB\nMA0GCSqGSIb3DQEBCwUAA4IBAQC1hSQG8AwtGOoX2gKBK4Hi5XBrBreij8WlLTUW\nld0FINQ0Rg84f/27CjDthywj6wgxCesCuOVFhpxQa1UacsP/Gcai1aKABtLWImca\nWECRYK5gDkwhTMFKM9mXA26hH1l4v/UR2iTpEK9H78egC4W7bs2LDTpPryuaNKTq\nP2O0tMbNkAHB8yecz5LxHXnxadL9Egow25g2RClvpifWqDnuS9TSbKkIWLcPLjoc\nJj2K9ILpBwhXiXi/BiSgyYTLiYvVvih9vX4s+hKGZNJc0j92YLiOHDF0XH1oxgdV\njfTmRiedeb2VZJZElptD92z0AqFR7z2d5B+OqpPA2gjuMLV5\n-----END CERTIFICATE----- |
|
| status |
string |
绑定状态。可选值:CONFIGURED(配置已受理,等待开通用户池)、SYNCING(正在同步组织成员)、SYNCED(组织成员同步完成)、READY(绑定已生效)、SYNC_FAILED(组织成员同步失败)、UPDATING(正在更新配置)、UPDATE_FAILED(更新配置失败)、DISCONNECTING(正在解绑)、DISCONNECT_FAILED(解绑失败)。 |
READY |
| syncEnabled |
boolean |
是否开启组织成员同步。开启后由该外部身份提供商同步组织成员为工作空间用户。 |
|
| syncScope |
object |
沿用按部门同步范围定义;创建省略默认 AllAuthorized,首次厂商同步由 syncOnBind 决定;更新省略或 null 保留原值,更新保存范围不自动执行全量同步。 |
|
| departmentIds |
array |
SelectedDepartments 时至少包含一个非空部门 ID,应取自 ListIdentityProviderDepartments;AllAuthorized 时传空数组或省略。 |
["10001"] |
|
string |
身份源返回的部门唯一标识,取自 ListIdentityProviderDepartments。 |
10001 |
|
| mode |
string |
AllAuthorized:全部授权范围,受应用通讯录授权限制;SelectedDepartments:选中部门及所有子部门。显式提交 syncScope 时必须提供有效 mode,由后端校验。 |
SelectedDepartments |
| workspaceId |
string |
工作空间 ID。 |
ws-123456 |
| httpStatusCode |
integer |
HTTP 状态码。 |
200 |
| message |
string |
响应消息。请求失败时返回错误描述。 |
success |
| requestId |
string |
请求 ID。 |
request-123456 |
| success |
boolean |
请求是否成功。 |
示例
正常返回示例
JSON格式
{
"code": "SUCCESS",
"data": {
"configuration": {
"bindingType": "HTTP-Redirect",
"entityId": "https://idp.example.com/entity",
"loginUrl": "https://idp.example.com/sso",
"ssoStatus": "Enabled"
},
"identityProviderType": "DingTalk",
"loginEnabled": true,
"protocol": "SAML",
"saml": {
"bindingType": "HTTP-Redirect",
"entityId": "https://idp.example.com/entity",
"loginUrl": "https://idp.example.com/sso",
"x509Certificates": [
"-----BEGIN CERTIFICATE-----\\nMIICwDCCAaigAwIBAgIULlsHLfcADyBax5ZtFlj+YGzZVo0wDQYJKoZIhvcNAQEL\\nBQAwGjEYMBYGA1UEAwwPaWRwLmV4YW1wbGUuY29tMB4XDTI2MDEwMTAwMDAwMFoX\\nDTM2MDEwMTAwMDAwMFowGjEYMBYGA1UEAwwPaWRwLmV4YW1wbGUuY29tMIIBIjAN\\nBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAto0DN0W1CrPRzK9QZ9A1aApb4Lg8\\noGlp2c0PbN3LokXe/HzwxCMXx65IDnrenttxzTwp9BgUnUN/3LRzWaOL2UQ/vNYN\\nW9LFLkI1T64UPyI7eyi28YlALhb41xkYhEp7rz+MjqifBzVZeTDUxBYtbK2hAhbY\\nEL1+udwsXEx0KB7xuQ/rbI2OKeqAEAD1tfYg7T/SM2wrXNYhx+o1HtchM4/0I8Ok\\nkk27JQ4y3ofzC5sTySmFF1Y7XcpSd+5WSyazedhkAieo8AB01DkJV6nnKfH8sH0E\\nBsnH3FP8FhqCLrIeEkjX9B9OcIRLGjiZqx4u/ryW1QhMldnv+pFfNjWy/wIDAQAB\\nMA0GCSqGSIb3DQEBCwUAA4IBAQC1hSQG8AwtGOoX2gKBK4Hi5XBrBreij8WlLTUW\\nld0FINQ0Rg84f/27CjDthywj6wgxCesCuOVFhpxQa1UacsP/Gcai1aKABtLWImca\\nWECRYK5gDkwhTMFKM9mXA26hH1l4v/UR2iTpEK9H78egC4W7bs2LDTpPryuaNKTq\\nP2O0tMbNkAHB8yecz5LxHXnxadL9Egow25g2RClvpifWqDnuS9TSbKkIWLcPLjoc\\nJj2K9ILpBwhXiXi/BiSgyYTLiYvVvih9vX4s+hKGZNJc0j92YLiOHDF0XH1oxgdV\\njfTmRiedeb2VZJZElptD92z0AqFR7z2d5B+OqpPA2gjuMLV5\\n-----END CERTIFICATE-----"
]
},
"status": "READY",
"syncEnabled": true,
"syncScope": {
"departmentIds": [
"10001"
],
"mode": "SelectedDepartments"
},
"workspaceId": "ws-123456"
},
"httpStatusCode": 200,
"message": "success",
"requestId": "request-123456",
"success": true
}
错误码
访问错误中心查看更多错误码。
变更历史
更多信息,参考变更详情。