tencent cloud

Feedback

SCIM 2.0 API

Last updated: 2024-11-27 14:46:27
    If you need to integrate the SCIM protocol for a self-built IdP to synchronize users or user groups to the Identity Center - User Management, please refer to this document. When the SCIM synchronization capabilities provided by individual identity providers (such as Okta and Azure AD) are used, this document is usually not needed.

    Instructions

    The implementation of the SCIM API 2.0 follows RFC 7644. For specific request instructions, please refer to RFC Document.
    Endpoints for the SCIM service:
    Chinese: https://scim.tencentcloudsso.com/scim/v2
    International: https://scim.tencentcloudssointl.com/scim/v2

    SCIM API Protocol

    Discovery Endpoint

    /ServiceProviderConfig

    Feature overview
    Get the features supported by the server.
    Use limits
    No authentication required.
    Request example
    curl https://scim.tencentcloudsso.com/scim/v2/ServiceProviderConfig -H "Content-type:application/json"
    Return example
    {
    "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
    }
    }
    The returned result shows:
    Features supported: patch and filter.
    Features not supported: bulk, changePassword, sort, and etag.

    /ResourceTypes

    Feature overview
    Get the resource types supported by the server and return User and Group.
    Request example
    curl https://scim.tencentcloudsso.com/scim/v2/ResourceTypes --header 'Authorization: Bearer <your scim credential>' --header "content-type:application/json"
    Return example
    {
    "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

    Feature overview
    Get the Schema supported by the server and return the detailed Schema of User and Group.
    Use limits
    Queries by resource type are supported.
    Field names and field values specified in the protocol are case-insensitive.
    Only fields described in the following document are supported.
    Request example
    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"
    Return example
    User resource 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"
    ]
    }
    User group resource 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

    Feature overview
    Synchronize users.
    Use limits
    If there is a manually created user with the same name in the identity center, the creation will fail.
    Request example
    curl https://scim.tencentcloudsso.com/scim/v2/Users --header 'Authorization: Bearer <your scim credential>' --header "content-type:application/json" -X POST -d '<data>'
    The data structure example is as follows:
    {
        "displayName": "<user display name>",
        "emails": [
            {
                "primary": true,
                "type": "work",
                "value": "<user email>"
            }
        ],
        "name": {
            "familyName": "<user family name>",
            "givenName": "<user given name>"
        },
        "userName": "<user name>"
    }
    Return example
    {
        "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} and GET/Users

    Feature overview
    GET/Users/{id}: Query the user with the specified ID.
    GET/Users: Query user information based on conditions or query the list of all users.
    Use limits
    If /{id} is provided, the user corresponding to the ID will be returned. If {id} is not an existing user, the request will be rejected.
    If /{id} is not provided and a filter is present, the corresponding users will be filtered and returned. The filter will only support the userName field and the eq operator.
    If /{id} is not provided and no filter is present, the list of all users will be returned. The standard paging mode in the SCIM protocol will be supported, with a maximum of 100 records returned per page. If the record count exceeds 100 (count>100), it will be processed as 100.
    Only synchronized users can be queried.
    1. Example 1: Query the user with the specified ID.
    Request example
    curl https://scim.tencentcloudsso.com/scim/v2/Users/<userId> --header 'Authorization: Bearer <your scim credential>' --header "content-type:application/json" -X GET
    Return example
    {
        "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. Example 2: Query user information based on conditions or query the list of all users.
    Request example
    curl https://scim.tencentcloudsso.com/scim/v2/Users<?parameters> --header 'Authorization: Bearer <your scim credential>' --header "content-type:application/json" -X GET
    Return example
    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} and PATCH/Users/{id}

    Overview
    PUT/Users/{id}: Replace user information.
    PATCH/Users/{id}: Update user information.
    Use limits
    {id} is required. The scope of fields to be modified is defined in the Schema.
    PUT will overwrite the original attributes.
    Patch supports Add and Replace.
    Only synchronized users can be modified.
    Request example
    1. Replace user information (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>'
    The data structure example is as follows:
    {
        "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. Update user information (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>'
    The data structure example is as follows:
    // 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"
        ]
    }
    Return example
    //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}

    Feature overview
    Delete the user with the specified ID.
    Use limits
    {id} is required.
    Only synchronized users can be deleted.
    Request example
    curl https://scim.tencentcloudsso.com/scim/v2/Users/<userId> --header 'Authorization: Bearer <your scim credential>' --header "content-type:application/json" -X DELETE
    Return example
    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

    Feature overview
    Synchronize user groups.
    Use limits
    If there is a manually created user group with the same name in the identity center, the creation will fail.
    Request example
    curl https://scim.tencentcloudsso.com/scim/v2/Groups --header 'Authorization: Bearer <your scim credential>' --header "content-type:application/json" -X POST -d '<data>'
    The data structure example is as follows:
    {
        "displayName": "<group name>",
        "schemas": [
            "urn:ietf:params:scim:schemas:core:2.0:Group"
        ]
    }
    Return example
    {
        "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} and GET/Groups

    Feature overview
    GET/Groups/{id}: Query the user group with the specified ID.
    GET/Groups: Query user group information based on conditions or query the list of all user groups.
    Use limits
    Queries by ID and queries by filter are supported.
    The filter only supports the displayName field and the eq operator.
    If /{id} is provided, the user group corresponding to the ID will be returned and the members parameter value will be included. If {id} is not an existing user group, the request will be rejected.
    If /{id} is not provided and no filter is present, the list of all user groups will be returned and the value of members will be null (that is, the list method will not return members). The standard paging mode in the SCIM protocol will be supported, with a maximum of 100 records returned. If the record count exceeds 100 (count>100), it will be processed as 100.
    Only synchronized user groups can be queried.
    1. Example 1: Query the user group with the specified ID.
    Request example
    curl https://scim.tencentcloudsso.com/scim/v2/Groups/<groupId> --header 'Authorization: Bearer <your scim credential>' --header "content-type:application/json" -X GET
    Return example
    {
        "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. Example 2: Query user group information based on conditions or query the list of all user groups.
    Request example
    curl https://scim.tencentcloudsso.com/scim/v2/Groups<?parameters> --header 'Authorization: Bearer <your scim credential>' --header "content-type:application/json" -X GET
    Return example
    {
        "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} and PATCH/Groups/{id}

    Feature overview
    PUT/Groups/{id}: Replace user group information.
    PATCH/Groups/{id}: Update user group information.
    Use limits
    {id} is required. The scope of fields to be modified is defined in the Schema.
    PUT will overwrite the original attributes and support replacing member.
    Patch supports Add, Replace, and Remove.
    Only synchronized user groups can be modified.
    Request example
    Replace user group information (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>'
    The data structure example is as follows:
    {
        "displayName": "<group name>",
        "schemas": [
            "urn:ietf:params:scim:schemas:core:2.0:Group"
        ]
    }
    Update user group information (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>'
    The data structure example is as follows:
    //Remove the specified user <userId> from the group corresponding to <groupId>
    {
    "Operations": [
    {
    "op": "remove",
    "path": "members",
    "value": [
    {
    "value": "<userId>"
    }
    ]
    }
    ],
    "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:PatchOp"
    ]
    }
    //Remove all users from the group corresponding to <groupId>
    {
    "Operations": [
    {
    "op": "remove",
    "path": "members"
    }
    ],
    "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:PatchOp"
    ]
    }
    //Add 3 users to the group corresponding to <groupId>
    {
    "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"
    ]
    }
    Return example
    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}

    Feature overview
    Delete the user group with the specified ID.
    Use limits
    {id} is required.
    Deletion of a group is not allowed when a member exists.
    Only synchronized user groups can be deleted.
    Request example
    curl https://scim.tencentcloudsso.com/scim/v2/Groups/<groupId> --header 'Authorization: Bearer <your scim credential>' --header "content-type:application/json" -X DELETE
    Return example
    HTTP/1.1 204
    Date: Mon, 06 Apr 2020 22:21:24 GMT
    Content-Type: application/json
    x-RequestId: abbf9e53-9ecc-46d2-8efe-104a66ff128
    
    
    Contact Us

    Contact our sales team or business advisors to help your business.

    Technical Support

    Open a ticket if you're looking for further assistance. Our Ticket is 7x24 avaliable.

    7x24 Phone Support