tencent cloud

文档反馈

SCIM2.0接口

最后更新时间:2024-11-27 14:46:27
    如果自建 IdP 需要集成 SCIM 协议,将用户或用户组同步到身份中心 - 用户管理时,需要关注本文档。使用各身份提供商(例如:Okta、Azure AD等)提供的 SCIM 同步能力时,通常不需要关注本文档。

    使用说明

    SCIM 2.0接口的实现遵循 RFC 7644,具体请求说明请参见 RFC文档
    SCIM服务对应的接入点(Endpoint):
    中国站:https://scim.tencentcloudsso.com/scim/v2
    国际站:https://scim.tencentcloudssointl.com/scim/v2

    SCIM 接口协议

    Discovery Endpoint

    /ServiceProviderConfig

    功能描述
    获取服务端支持的功能。
    使用约束
    不需要认证。
    请求示例
    curl https://scim.tencentcloudsso.com/scim/v2/ServiceProviderConfig -H "Content-type:application/json"
    返回示例
    {
    "authenticationSchemes": [
    {
    "description": "Authentication scheme using the OAuth Bearer Token Standard",
    "documentationUri": "",
    "name": "OAuth Bearer Token",
    "primary": true,
    "specUri": "",
    "type": "oauthbearertoken"
    }
    ],
    "bulk": {
    "maxOperations": 1000,
    "maxPayloadSize": 1048576,
    "supported": false
    },
    "changePassword": {
    "supported": false
    },
    "documentationUri": "",
    "etag": {
    "supported": false
    },
    "filter": {
    "maxResults": 100,
    "supported": true
    },
    "patch": {
    "supported": true
    },
    "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:ServiceProviderConfig"
    ],
    "sort": {
    "supported": false
    }
    }
    返回结果显示:
    支持的功能:patch, filter。
    不支持的功能:bulk、changePassword、sort、etag。

    /ResourceTypes

    功能描述
    获取服务端支持的资源类型,返回 User 和 Group。
    请求示例
    curl https://scim.tencentcloudsso.com/scim/v2/ResourceTypes --header 'Authorization: Bearer <your scim credential>' --header "content-type:application/json"
    返回示例
    {
    "Resources": [
    {
    "description": "User Account",
    "endpoint": "/Users",
    "id": "User",
    "name": "User",
    "schema": "urn:ietf:params:scim:schemas:core:2.0:User",
    "schemaExtensions": [],
    "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:ResourceType"
    ]
    },
    {
    "description": "Group",
    "endpoint": "/Groups",
    "id": "Group",
    "name": "Group",
    "schema": "urn:ietf:params:scim:schemas:core:2.0:Group",
    "schemaExtensions": [],
    "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:ResourceType"
    ]
    }
    ],
    "itemsPerPage": 100,
    "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:ListResponse"
    ],
    "startIndex": 1,
    "totalResults": 2
    }

    /Schemas

    功能描述
    获取服务端支持的 Schema,返回 User 和 Group 的详细 Schema。
    使用约束
    支持按资源类型查询。
    对协议中约定的字段名和字段值不区分大小写。
    只支持下文文档描述的字段。
    请求示例
    The schema to request all resources.
    curl https://scim.tencentcloudsso.com/scim/v2/Schemas --header 'Authorization: Bearer <your scim credential>' --header "content-type:application/json"
    The schema to request users.
    curl https://scim.tencentcloudsso.com/scim/v2/Schemas/urn:ietf:params:scim:schemas:core:2.0:User --header 'Authorization: Bearer <your scim credential>' --header "content-type:application/json"
    The schema to request user groups.
    curl https://scim.tencentcloudsso.com/scim/v2/Schemas/urn:ietf:params:scim:schemas:core:2.0:Group --header 'Authorization: Bearer <your scim credential>' --header "content-type:application/json"
    返回示例
    用户资源 Schema
    {
    "attributes": [
    {
    "caseExact": false,
    "description": "Unique identifier for the User, typically used by the user to directly authenticate to the service provider. Each User MUST include a non-empty userName value. This identifier MUST be unique across the service provider's entire set of Users. REQUIRED.",
    "multiValued": false,
    "mutability": "readWrite",
    "name": "userName",
    "required": true,
    "returned": "default",
    "type": "string",
    "uniqueness": "server"
    },
    {
    "description": "The components of the user's real name. Providers MAY return just the full name as a single string in the formatted sub-attribute, or they MAY return just the individual component attributes using the other sub-attributes, or they MAY return both. If both variants are returned, they SHOULD be describing the same name, with the formatted name indicating how the component attributes should be combined.",
    "multiValued": false,
    "mutability": "readWrite",
    "name": "name",
    "required": false,
    "returned": "default",
    "subAttributes": [
    {
    "caseExact": false,
    "description": "The family name of the User, or last name in most Western languages (e.g., 'Jensen' given the full name 'Ms. Barbara J Jensen, III').",
    "multiValued": false,
    "mutability": "readWrite",
    "name": "familyName",
    "required": false,
    "returned": "default",
    "type": "string",
    "uniqueness": "none"
    },
    {
    "caseExact": false,
    "description": "The given name of the User, or first name in most Western languages (e.g., 'Barbara' given the full name 'Ms. Barbara J Jensen, III').",
    "multiValued": false,
    "mutability": "readWrite",
    "name": "givenName",
    "required": false,
    "returned": "default",
    "type": "string",
    "uniqueness": "none"
    }
    ],
    "type": "complex"
    },
    {
    "caseExact": false,
    "description": "The name of the User, suitable for display to end-users. The name SHOULD be the full name of the User being described, if known.",
    "multiValued": false,
    "mutability": "readWrite",
    "name": "displayName",
    "required": false,
    "returned": "default",
    "type": "string",
    "uniqueness": "none"
    },
    {
    "description": "A Boolean value indicating the User's administrative status.",
    "multiValued": false,
    "mutability": "readWrite",
    "name": "active",
    "required": false,
    "returned": "default",
    "type": "boolean"
    },
    {
    "description": "Email addresses for the user. The value SHOULD be canonicalized by the service provider, e.g., 'bjensen@example.com' instead of 'bjensen@EXAMPLE.COM'. Canonical type values of 'work', 'home', and 'other'.",
    "multiValued": true,
    "mutability": "readWrite",
    "name": "emails",
    "required": false,
    "returned": "default",
    "subAttributes": [
    {
    "caseExact": false,
    "description": "Email addresses for the user. The value SHOULD be canonicalized by the service provider, e.g., 'bjensen@example.com' instead of 'bjensen@EXAMPLE.COM'. Canonical type values of 'work', 'home', and 'other'.",
    "multiValued": false,
    "mutability": "readWrite",
    "name": "value",
    "required": false,
    "returned": "default",
    "type": "string",
    "uniqueness": "none"
    },
    {
    "canonicalValues": [
    "work",
    "home",
    "other"
    ],
    "caseExact": false,
    "description": "A label indicating the attribute's function, e.g., 'work' or 'home'.",
    "multiValued": false,
    "mutability": "readWrite",
    "name": "type",
    "required": false,
    "returned": "default",
    "type": "string",
    "uniqueness": "none"
    },
    {
    "description": "A Boolean value indicating the 'primary' or preferred attribute value for this attribute, e.g., the preferred mailing address or primary email address. The primary attribute value 'true' MUST appear no more than once.",
    "multiValued": false,
    "mutability": "readWrite",
    "name": "primary",
    "required": false,
    "returned": "default",
    "type": "boolean"
    }
    ],
    "type": "complex"
    }
    ],
    "description": "User Account",
    "id": "urn:ietf:params:scim:schemas:core:2.0:User",
    "name": "User",
    "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:Schema"
    ]
    }
    用户组资源 Schema
    {
    "attributes": [
    {
    "caseExact": false,
    "description": "A human-readable name for the Group. REQUIRED.",
    "multiValued": false,
    "mutability": "readWrite",
    "name": "displayName",
    "required": true,
    "returned": "default",
    "type": "string",
    "uniqueness": "none"
    },
    {
    "description": "A list of members of the Group.",
    "multiValued": true,
    "mutability": "readWrite",
    "name": "members",
    "required": false,
    "returned": "default",
    "subAttributes": [
    {
    "caseExact": false,
    "description": "Identifier of the member of this Group.",
    "multiValued": false,
    "mutability": "immutable",
    "name": "value",
    "required": false,
    "returned": "default",
    "type": "string",
    "uniqueness": "none"
    },
    {
    "caseExact": false,
    "description": "A human-readable name for the group member, primarily used for display purposes.",
    "multiValued": false,
    "mutability": "immutable",
    "name": "display",
    "required": false,
    "returned": "default",
    "type": "string",
    "uniqueness": "none"
    }
    ],
    "type": "complex"
    }
    ],
    "description": "Group",
    "id": "urn:ietf:params:scim:schemas:core:2.0:Group",
    "name": "Group",
    "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:Schema"
    ]
    }

    Users

    POST /Users

    功能描述
    同步用户。
    使用约束
    如果身份中心中存在同名的手动方式创建的用户,则会创建失败。
    请求示例
    curl https://scim.tencentcloudsso.com/scim/v2/Users --header 'Authorization: Bearer <your scim credential>' --header "content-type:application/json" -X POST -d '<data>'
    其中,data 结构示例如下:
    {
        "displayName": "<user display name>",
        "emails": [
            {
                "primary": true,
                "type": "work",
                "value": "<user email>"
            }
        ],
        "name": {
            "familyName": "<user family name>",
            "givenName": "<user given name>"
        },
        "userName": "<user name>"
    }
    返回示例
    {
        "active": true,
        "displayName": "<user display name>",
        "emails":
        [
            {
                "primary": true,
                "type": "work",
                "value": "<user email>"
            }
        ],
        "id": "u-00vrs1l19d6gbsi5****",
        "meta":
        {
            "created": "2023-08-01T13:16:30.000Z",
            "lastModified": "2023-08-01T13:16:30.000Z",
            "resourceType": "User"
        },
        "name":
        {
            "familyName": "<user family name>",
            "givenName": "<user given name>"
        },
        "schemas":
        [
            "urn:ietf:params:scim:schemas:core:2.0:User"
        ],
        "userName": "<user name>"
    }

    GET /Users/{id} 和 GET /Users

    功能描述
    GET /Users/{id}:查询指定 ID 的用户。
    GET /Users:按条件查询用户信息或查询所有用户列表。
    使用约束
    如果带 /{id},则返回该 ID 对应的用户。如果 {id} 不是已存在的用户,则拒绝请求。
    如果不带 /{id} 且有 filter,则过滤相应的用户返回,filter 只支持 userName 字段,且只支持 eq 操作符。
    如果不带 /{id}且没有 filter,则返回所有用户列表,支持 SCIM 协议的标准分页方式,每页最多返回100条记录,如果记录条数大于100(count>100),则按100处理。
    仅能查询被同步的用户。
    1. 示例1:查询指定 ID 的用户。
    请求示例
    curl https://scim.tencentcloudsso.com/scim/v2/Users/<userId> --header 'Authorization: Bearer <your scim credential>' --header "content-type:application/json" -X GET
    返回示例
    {
        "active": true,
        "displayName": "<user display name>",
        "emails":
        [
            {
                "primary": true,
                "type": "work",
                "value": "<user email>"
            }
        ],
        "id": "u-00vrs1l19d6gbsi5****",
        "meta":
        {
            "created": "2023-08-01T13:16:30.000Z",
            "lastModified": "2023-08-01T13:16:30.000Z",
            "resourceType": "User"
        },
        "name":
        {
            "familyName": "<user family name>",
            "givenName": "<user given name>"
        },
        "schemas":
        [
            "urn:ietf:params:scim:schemas:core:2.0:User"
        ],
        "userName": "<user name>"
    }
    2. 示例2:按条件查询用户信息或查询所有用户列表。
    请求示例
    curl https://scim.tencentcloudsso.com/scim/v2/Users<?parameters> --header 'Authorization: Bearer <your scim credential>' --header "content-type:application/json" -X GET
    返回示例
    GET /Users?filter=userName eq "Test_User"
    {
        "Resources":
        [
            {
                "active": true,
                "displayName": "<user display name>",
                "emails":
                [
                    {
                        "primary": true,
                        "type": "work",
                        "value": "<user email>"
                    }
                ],
                "id": "u-0015b4962vrywtzb****",
                "meta":
                {
                    "created": "2023-07-07T17:21:07.000Z",
                    "lastModified": "2023-07-07T17:21:07.000Z",
                    "resourceType": "User"
                },
                "name":
                {
                    "familyName": "<user family name>",
                    "givenName": "<user given name>"
                },
                "schemas":
                [
                    "urn:ietf:params:scim:schemas:core:2.0:User"
                ],
                "userName": "<user name>"
            },
            {
                "active": true,
                "displayName": "<user display name>",
                "emails":
                [
                    {
                        "primary": true,
                        "type": "work",
                        "value": "<user email>"
                    }
                ],
                "id": "u-00vrs1l19d6gbsi5****",
                "meta":
                {
                    "created": "2023-08-01T13:16:30.000Z",
                    "lastModified": "2023-08-01T13:16:30.000Z",
                    "resourceType": "User"
                },
                "name":
                {
                    "familyName": "<user family name>",
                    "givenName": "<user given name>"
                },
                "schemas":
                [
                    "urn:ietf:params:scim:schemas:core:2.0:User"
                ],
                "userName": "<user name>"
            }
        ],
        "itemsPerPage": 10,
        "schemas":
        [
            "urn:ietf:params:scim:api:messages:2.0:ListResponse"
        ],
        "startIndex": 1,
        "totalResults": 2
    }
    {
    "Resources": [],
    "itemsPerPage": 10,
    "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:ListResponse"
    ],
    "startIndex": 1,
    "totalResults": 0
    }

    PUT /Users/{id} 和 PATCH /Users/{id}

    描述
    PUT /Users/{id}:替换用户信息。
    PATCH /Users/{id} :更新用户信息。
    使用约束
    {id} 必传,修改的字段范围为 Schema 中定义的字段。
    PUT 为覆盖原有属性。
    Patch 支持 Add、Replace.
    仅能修改被同步的用户。
    请求示例
    1. 替换用户信息(PUT)。
    curl https://scim.tencentcloudsso.com/scim/v2/Users/<userId> --header 'Authorization: Bearer <your scim credential>' --header "content-type:application/json" -X PUT -d '<data>'
    其中,data 结构示例如下:
    {
        "active": false,
    "displayName": "<user display name>",
    "emails":
    [
            {
                "primary": true,
                "type": "work",
                "value": "<user email>"
            }
        ],
        "name":
        {
            "familyName": "<user family name>",
            "givenName": "<user given name>"
        },
        "userName": "<user name>"
    }
    2. 更新用户信息(PATCH)。
    curl https://scim.tencentcloudsso.com/scim/v2/Users/<userId> --header 'Authorization: Bearer <your scim credential>' --header "content-type:application/json" -X PATCH -d '<data>'
    其中,data 结构示例如下:
    // replace操作
    {
        "Operations": [
            {
                "op": "replace",
                "path": "",
                "value": {
                    "active": false,
                    "displayName": "displayName",
                    "name": {
                        "familyName": "familyName",
                        "givenName": "givenName"
                    }
                }
            }
        ],
        "schemas": [
            "urn:ietf:params:scim:api:messages:2.0:PatchOp"
        ]
    }
    // add操作
    {
        "Operations": [
            {
                "op": "add",
                "path": "",
                "value": {
                    "displayName": "displayName",
                    "name": {
                        "familyName": "familyName",
                        "givenName": "givenName"
                    }
                }
            },
    {
    "op": "add",
    "path": "active",
    "value": true
    }
        ],
        "schemas": [
            "urn:ietf:params:scim:api:messages:2.0:PatchOp"
        ]
    }
    返回示例
    //replace
    {
        "active": false,
        "displayName": "displayName",
        "emails":
        [
            {
                "primary": true,
                "type": "work",
                "value": "<user email>"
            }
        ],
        "id": "u-00vrs1l19d6gbsi5****",
        "meta":
        {
            "created": "2023-08-01T13:16:30.000Z",
            "lastModified": "2023-08-01T13:16:30.000Z",
            "resourceType": "User"
        },
        "name":
        {
            "familyName": "<user family name>",
            "givenName": "<user given name>"
        },
        "schemas":
        [
            "urn:ietf:params:scim:schemas:core:2.0:User"
        ],
        "userName": "<user name>"
    }
    //add
    {
        "active": true,
        "displayName": "displayName",
        "emails":
        [
            {
                "primary": true,
                "type": "work",
                "value": "<user email>"
            }
        ],
        "id": "u-00vrs1l19d6gbsi5****",
        "meta":
        {
            "created": "2023-08-01T13:16:30.000Z",
            "lastModified": "2023-08-01T13:16:30.000Z",
            "resourceType": "User"
        },
        "name":
        {
            "familyName": "<user family name>",
            "givenName": "<user given name>"
        },
        "schemas":
        [
            "urn:ietf:params:scim:schemas:core:2.0:User"
        ],
        "userName": "<user name>"
    }

    DELETE /Users/{id}

    功能描述
    删除指定 ID 的用户。
    使用约束
    {id} 必传。
    仅能删除被同步的用户。
    请求示例
    curl https://scim.tencentcloudsso.com/scim/v2/Users/<userId> --header 'Authorization: Bearer <your scim credential>' --header "content-type:application/json" -X DELETE
    返回示例
    HTTP/1.1 204
    Date: Tue, 31 Mar 2020 02:36:15 GMT
    Content-Type: application/json
    x-RequestId: abbf9e53-9ecc-46d2-8efe-104a66ff128f

    /Group

    POST /Groups

    功能描述
    同步用户组。
    使用约束
    如果身份中心中存在同名的手动方式创建的用户组,则会创建失败。
    请求示例
    curl https://scim.tencentcloudsso.com/scim/v2/Groups --header 'Authorization: Bearer <your scim credential>' --header "content-type:application/json" -X POST -d '<data>'
    其中,data 结构示例如下:
    {
        "displayName": "<group name>",
        "schemas": [
            "urn:ietf:params:scim:schemas:core:2.0:Group"
        ]
    }
    返回示例
    {
        "displayName": "<group name>",
        "id": "g-00nqnd7hoevd1unv****",
        "members": [],
        "meta":
        {
            "created": "2023-08-01T13:30:23.000Z",
            "lastModified": "2023-08-01T13:30:23.000Z",
            "resourceType": "Group"
        },
        "schemas":
        [
            "urn:ietf:params:scim:schemas:core:2.0:Group"
        ]
    }

    GET /Groups/{id} 和 GET /Groups

    功能描述
    GET /Groups/{id}:查询指定 ID 的用户组。
    GET /Groups:按条件查询用户组信息或查询所有用户组列表。
    使用约束
    支持使用 id 查询和 filter 查询。
    filter 只支持 displayName 字段,且只支持 eq 操作符。
    如果带 /{id},则返回该 ID 对应的用户组,且包含 members 参数值,如果 {id} 不是已存在的用户组,则拒绝请求。
    如果不带 /{id} 且没有 filter,则返回所有用户组列表,且 members 的值为空(即列表方法不返回 members)。支持 SCIM 协议的标准分页方式,最多返回100条记录,如果记录条数大于100(count>100),按100处理。
    仅能查询被同步的用户组。
    1. 示例1:查询指定 ID 的用户组。
    请求示例
    curl https://scim.tencentcloudsso.com/scim/v2/Groups/<groupId> --header 'Authorization: Bearer <your scim credential>' --header "content-type:application/json" -X GET
    返回示例
    {
        "displayName": "<group name>",
        "id": "g-00nqnd7hoevd1unv****",
        "members":
        [
            {
                "display": "xxx",
                "value": "u-00vrs1l19d6gbsi5****"
            }
        ],
        "meta":
        {
            "created": "2023-08-01T13:30:23.000Z",
            "lastModified": "2023-08-01T13:30:23.000Z",
            "resourceType": "Group"
        },
        "schemas":
        [
            "urn:ietf:params:scim:schemas:core:2.0:Group"
        ]
    }
    2. 示例2:按条件查询用户组信息或查询所有用户组列表。
    请求示例
    curl https://scim.tencentcloudsso.com/scim/v2/Groups<?parameters> --header 'Authorization: Bearer <your scim credential>' --header "content-type:application/json" -X GET
    返回示例
    {
        "Resources":
        [
            {
                "displayName": "<group name>",
                "id": "g-00nqnd7hoevd1unv****",
                "members": [],
                "meta":
                {
                    "created": "2023-08-01T13:30:23.000Z",
                    "lastModified": "2023-08-01T13:30:23.000Z",
                    "resourceType": "Group"
                },
                "schemas":
                [
                    "urn:ietf:params:scim:schemas:core:2.0:Group"
                ]
            }
        ],
        "itemsPerPage": 10,
        "schemas":
        [
            "urn:ietf:params:scim:api:messages:2.0:ListResponse"
        ],
        "startIndex": 1,
        "totalResults": 1
    }

    PUT /Groups/{id} 和 PATCH /Groups/{id}

    功能描述
    PUT /Groups/{id}:替换用户组信息。
    PATCH /Groups/{id}:更新用户组信息。
    使用约束
    {id} 必传,修改的字段范围为 Schema 中定义的字段。
    PUT 为覆盖原有属性,支持替换 member。
    Patch 支持 Add、Replace 和 Remove。
    仅能修改被同步的用户组。
    请求示例
    替换用户组信息(PUT)
    curl https://scim.tencentcloudsso.com/scim/v2/Groups/<groupId> --header 'Authorization: Bearer <your scim credential>' --header "content-type:application/json" -X PUT -d '<data>'
    其中,data 结构示例如下:
    {
        "displayName": "<group name>",
        "schemas": [
            "urn:ietf:params:scim:schemas:core:2.0:Group"
        ]
    }
    更新用户组信息(PATCH)
    curl https://scim.tencentcloudsso.com/scim/v2/Groups/<groupId> --header 'Authorization: Bearer <your scim credential>' --header "content-type:application/json" -X PATCH -d '<data>'
    其中,data 结构示例如下:
    //从<groupId>对应的组内移除指定的用户<userId>
    {
    "Operations": [
    {
    "op": "remove",
    "path": "members",
    "value": [
    {
    "value": "<userId>"
    }
    ]
    }
    ],
    "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:PatchOp"
    ]
    }
    //从<groupId>对应的组内移除所有用户
    {
    "Operations": [
    {
    "op": "remove",
    "path": "members"
    }
    ],
    "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:PatchOp"
    ]
    }
    //向<groupId>对应的组内添加3个用户
    {
    "Operations": [
    {
    "op": "add",
    "path": "members",
    "value": [
    {
    "display": "<userName1>",
    "value": "<userId1>"
    },
    {
    "display": "<userName2>",
    "value": "<userId2>"
    },
    {
    "display": "<userName3>",
    "value": "<userId3>"
    }
    ]
    }
    ],
    "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:PatchOp"
    ]
    }
    返回示例
    HTTP/1.1 204 No Content
    HTTP/1.1 204
    Date: Tue, 07 Apr 2020 23:59:09 GMT
    Content-Type: application/json
    x-RequestId: dad0c91c-1ea8-4b36-9fdb-4f099b59c1c9

    DELETE /Groups/{id}

    功能描述
    删除指定 ID 的用户组。
    使用约束
    {id} 必传。
    存在 member 的时候不允许删除组。
    仅能删除被同步的用户组。
    请求示例
    curl https://scim.tencentcloudsso.com/scim/v2/Groups/<groupId> --header 'Authorization: Bearer <your scim credential>' --header "content-type:application/json" -X DELETE
    返回示例
    HTTP/1.1 204
    Date: Mon, 06 Apr 2020 22:21:24 GMT
    Content-Type: application/json
    x-RequestId: abbf9e53-9ecc-46d2-8efe-104a66ff128
    
    联系我们

    联系我们,为您的业务提供专属服务。

    技术支持

    如果你想寻求进一步的帮助,通过工单与我们进行联络。我们提供7x24的工单服务。

    7x24 电话支持