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
Was this page helpful?