CreateIdentityProvider - 绑定外部身份提供商

更新时间:
复制 MD 格式

为工作空间绑定钉钉、飞书或 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代码示例。

调试

授权信息

下表是API对应的授权信息,可以在RAM权限策略语句的Action元素中使用,用来给RAM用户或RAM角色授予调用此API的权限。具体说明如下:

  • 操作:是指具体的权限点。

  • 访问级别:是指每个操作的访问级别,取值为写入(Write)、读取(Read)或列出(List)。

  • 资源类型:是指操作中支持授权的资源类型。具体说明如下:

    • 对于必选的资源类型,用前面加 * 表示。

    • 对于不支持资源级授权的操作,用全部资源表示。

  • 条件关键字:是指云产品自身定义的条件关键字。

  • 关联操作:是指成功执行操作所需要的其他权限。操作者必须同时具备关联操作的权限,操作才能成功。

操作

访问级别

资源类型

条件关键字

关联操作

agentcore:CreateIdentityProvider

create

*IdentityProvider

acs:agentcore:{#regionId}:{#accountId}:workspace/{#workspaceId}/identityProvider/{#identityProviderType}

无 无

请求语法

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
}

错误码

访问错误中心查看更多错误码。

变更历史

更多信息,参考变更详情。