SCIM Playground

Appearance

Users ​

SCIM Users refer to individual entities that have access to a system or application. SCIM provides a standardized way to manage these users across various systems. This includes creating, reading, updating, and deleting user resources through a RESTful API. The user resources are represented as JSON objects, and include information such as the user's name, email address, and other relevant attributes. The SCIM protocol helps to simplify user management and promotes interoperability among different systems.

List Users ​

The SCIM list users endpoint is used to retrieve a list of all users in the system. It is accessed through a RESTful API using the HTTP GET method and the URL /users. The response will be a JSON object containing an array of user resources, each of which includes information such as the user's name, email address, and other attributes. The endpoint may also support pagination and filtering to limit the number of results returned.

Pagination is possible by leveraging query parameters size and startIndex. For example with the following request.

List Users Including Groups ​

SCIM allows for the retrieval of attributes only when they are explicitly requested. You can use the attributes parameter to define which attributes you want to be returned. Generally, the groups attribute is only returned if it is specifically requested.

Find User ​

In SCIM, filters are used to refine the list of resources returned by a SCIM service provider. They can be used in 'List' or 'Search' requests to limit the results based on specific attributes or conditions.

Here are some of the filter options you can use in SCIM:

  • Attribute Filter: You can filter resources based on their attributes. For example, userName eq "john" would return only the users whose userName is "john".

  • Comparison Operators: SCIM supports several comparison operators such as eq (equals), ne (not equals), co (contains), sw (starts with), ew (ends with), gt (greater than), lt (less than), ge (greater than or equal to), and le (less than or equal to).

  • Logical Operators: SCIM also supports logical operators like and and or to combine multiple conditions. For example, userName eq "john" and title co "manager" would return users named "john" who also have "manager" in their title.

  • Grouping: You can group conditions using parentheses. For example, (userName eq "john" or userName eq "jane") and title co "manager" would return users named either "john" or "jane" who have "manager" in their title.

  • Complex Attributes: SCIM allows filtering on complex attributes as well. For example, emails[type eq "work" and value co "@example.com"] would return users whose work email contains "@example.com".

Remember to properly encode the filter query when using it in a URL.

The following example finds all users who are a member of a certain group.

Get User ​

The SCIM endpoint for retrieving a known user resource is typically accessed through a RESTful API using the HTTP GET method. The URL for this endpoint is usually in the format /users/{id}, where {id} is replaced with the unique identifier of the user resource you wish to retrieve.

For example, if you wanted to retrieve the user resource with an id of 1, you would send a GET request to /users/1.

The response from this endpoint will be a JSON object containing the user resource's information, such as their name, email address, and other attributes.

Create User ​

To create a new user, you would send a POST request to /users with a JSON object in the request body containing the new user's information. This information might include attributes such as the user's name, email address, and other relevant details.

The server will respond with a JSON object representing the newly created user resource, including its unique identifier.

Create User (alternative) ​

Note that the above example doesn't explicitly define what attributes belong to the user schema and what attributes are so called common attributes, such as externalId.
In some cases, especially when using multiple schemas, it is preferable to explicitly specify the schema like in the example below.

Update Attribute ​

To update a specific attribute of a user, you can use the HTTP PATCH method. This allows you to modify only certain attributes of a user resource without needing to send the entire resource in your request.

The URL for this endpoint is in the format /users/{id}, where {id} is replaced with the unique identifier of the user resource you wish to update.

In the request body, you would include a JSON object that specifies the attribute you want to update and its new value.

Replace ​

The SCIM protocol provides a PUT operation to replace an existing user resource. This operation allows you to replace all attributes of a user resource with a new set of attributes.

In the request body, you would include a JSON object that specifies the new attributes for the user. This JSON object should include all attributes of the user resource, even those that are not changing, because the PUT operation replaces the entire user resource.

Delete ​

Delete users by sending an DELETE request to the endpoint /users/{id}.

Note that a succesful deletion request will return no content, and therefore the HTTP status code 204.

Cursor Pagination ​

Some databases do not support index pagination, which leverages startIndex for navigation to the next page. Additionally, for performance reasons, this is not the most optimal way to navigate through a large dataset. To address this, a new specification is being developed: Cursor-based Pagination of SCIM Resources.

SCIM Playground supports cursor navigation.

First, start by issuing a regular request to retrieve resources such as Users or Groups. However, ensure to send an empty cursor query parameter. By sending this parameter, the SCIM server is instructed to use cursor pagination and return nextCursor.

Note that the response now contains nextCursor.

Try to use it in the following request.

Note that this response includes previousCursor. This allows navigating back to the previous page.

Alternative object representation: null values ​

The SCIM specification permits the return of null values. SCIM Playground returns null-values with providing the for this implementation introduced query-parameter _with_null_values. The SCIM specification allows the use of extra query parameters: SCIM service providers MAY support additional query parameters.

Alternative object representation: core schema ​

A server can either explicitly scope attributes under the core schema, such as urn:ietf:params:scim:schemas:core:2.0:User for User resource types, or omit the schema identifier. In SCIM Playground, the core schema identifier is not explicitly mentioned for core schema attributes unless the special query parameter _with_main_schema is used.

Roles ​

The SCIM core schema includes a definition for the attribute roles. The core schema defines sub-attributes such as value, type, display, and primary for each role. Unlike groups, an assigned role does not refer to a SCIM-managed object: you cannot use SCIM to create, update, or list roles.

Remove roles by value ​

There are several ways to remove assigned roles. A common method is to remove roles by specifying the value to be removed.

Remove roles by path ​

Another way to remove items from a complex multi-valued attribute, such as roles, is by leveraging the path request attribute.

Clients can execute queries without including parameters in the URL by using the HTTP POST method combined with the /.search path suffix. The /.search extension at the end of a valid SCIM endpoint indicates that the HTTP POST method is intended for query operations.

This endpoint accepts the same parameters as the regular /Users endpoint, but the parameters are included in the JSON body of the POST request instead of the URL query parameters.