SCIM API
The System for Cross-domain Identity Management (SCIM) specifications are designed to make identity management between different systems easier. SCIM provides a defined schema and extension model for representing identity resources like users, and a standard application-level, REST protocol for provisioning and managing identity data on the web. This ensures that user data is stored in a consistent way, so that it can be shared with different applications.
The OneWelcome Identity Platform SCIM API includes inbound REST endpoints for SCIM. This means that you can connect a user repository that supports outbound SCIM directly to the OneWelcome Identity Platform, and use the SCIM protocol to provision your users into the platform.
The protocol supports the creation, modification, retrieval, and discovery of users. It includes an application-level REST API to run CRUD operations on your users.
For more information about the SCIM protocol, see SCIM:Protocol 1.
Authentication and authorization
Access to the OneWelcome Identity Platform SCIM API can be protected with one of the following mechanisms:
- OAuth2 bearer token (default)
- OAuth2 fine-grained bearer token with an operation scope and a specific SCIM schema scope.
OAuth scopes
When OAuth bearer tokens are used, the OAuth scopes that are associated wth the OAuth access token limit and control the the authorizations for the client.
-
OAuth2 scopes: The API grants access only when it receives a valid access token that contains the required scope to perform a specific operation, such as
SCIM:user:getorSCIM:user:POST. -
OAuth2 fine-grained scopes: The API grants access only when it receives a valid access token containing the required scopes for performing specific actions on specific attributes, such as
SCIM:user:get,SCIM:user:POSTand so on. The difference between OAuth2 scopes and OAuth2 fine-grained scopes protection is that fine-grained scopes offer the possibility to see parts of the SCIM schema based on the provided scope, such asurn:scim:schemas:extension:iwelcome:1.0.
The OneWelcome SCIM API uses the following scope values (shown in YAML):
SCIM:user:get: Retrieve user attributes
SCIM:user:post: Create a user
SCIM:user:delete: Delete a user
SCIM:user:put: Update a user's attributes
SCIM:user:patch: Partially update user with only the specified attributes
SCIM:user:query: Retrieve multiple users' attributes
When the request authenticates with OAuth2 fine-grained, the scope determines which parts of the SCIM schema are accessible. To view or change user attributes, you must have the OAuth2 scopes that are needed for the operation, and the scopes needed for the specific attribute’s schema.
The scope for filtering the requests based on the tenant is: "onewelcome:tenant" + tenantName
Scope examples
-
To see or change the emails (
urn:scim:schema:core:1.0:emails) attribute, the access token must contain theurn:scim:schema:core:1.0scope. -
To see or change the gender (
urn:scim:schemas:extension:iwelcome:1.0:gender) attribute, the access token must contain theurn:scim:schemas:extension:iwelcome:1.0scope.
SCIM resources
In SCIM, a resource is an artifact that that contains attributes and is managed by a service, such as the OneWelcome Identity Platform. The resource type, such as user, defines the resource name, endpoint URL, schemas, and other metadata. The schema is a collection of attributes that define the contents of the respective resource.
Path for resources
The following table shows the supported API versions and the paths for accessing the resources.
| API version | Path |
|---|---|
| V1.1 | /scim/v1.1/Users |
| V1/V2 | /scim/(v1/v2)/Users |
Resource components
Each SCIM resource is a JSON object that has the following components:
-
Resource type is user.
-
Schemas lists the SCIM schemas for the resources. It includes the core schema and any extensions.
-
Attributes:
-
Common attributes are part of every SCIM resource, but are not defined in any particular schema.
-
Core attributes are listed in the resource type's schema.
-
OneWelcome Identity Platform attributes are extensions for custom fields in the OneWelcome Identity Platform that are not found in the core SCIM schemas.
-
Tenant attributes are extensions for custom attributes that a tenant requires, and that are not found in the core SCIM schemas.
-
SCIM endpoints
The SCIM protocol specifies well-known endpoints and HTTP methods for managing resources defined in the core schema. For example, user resources correspond to /Users.
If you use multiple brands, your setup can have multiple endpoints per brand. If you use multiple tenant with multiple brands, your setup can have separate endpoints for each combination of tenant and brand.
SCIM API operations
The SCIM protocol uses REST-style architecture and JSON objects to communicate data about your users. The API provides CRUD operations that you run on your user resources:
-
GET Retrieves a user from the OneWelcome Identity Platform.
-
POST Creates a new user in the OneWelcome Identity Platform.
-
PUT Modifies a user by replacing the entire resource.
-
PATCH Modifies a user by updating only the specified attributes.
-
DELETE Deletes a user.
The OneWelcome Identity Platform supports the following SCIM operations:
| Resource | Endpoint | Supported operations | Unsupported operations |
|---|---|---|---|
| User | /Users | GET, POST, PUT, DELETE, PATCH | |
| Group | /Groups | GET, POST, PUT, PATCH, DELETE | |
| Service provider configuration | /ServiceProviderConfigs | GET | |
| Schema | /Schemas | GET (a preliminary non-compliant version) | |
| Bulk | /Bulk | POST |
SCIM requests and responses
All requests to the OneWelcome Identity Platform are made using HTTP operations on a URL that is derived from the base URL.
Responses are returned in the body of the HTTP response, formatted as JSON. Response and error codes are transmitted via the HTTP status code of the response, and are specified in the body of the response.
For examples of SCIM messages in JSON representation, see user management.
For details about the JSON representation, see SCIM: Core Schema 1.1 - JSON Representation.
Security considerations
The OneWelcome Identity Platform does not return password values in the responses.
For more information, see SCIM: Core Schema 1.1 - Security Considerations.
Filtering
You can use filters in your searches. However, the structural use of SCIM filtering as part of a regular flow in client applications can have a performance penalty. Before you implement this kind of filtering, ensure that the default indexes allow for sufficient performance.
Filtering using GET
Filtering is supported with some limitations. Filters can include multiple attribute operators concatenated with AND or OR operators. You can add filter attribute operators to a filter query param. You can also filter based on count, startIndex, sortOrder, and attributes.
The following example shows filtering with query parameter values, where attributes are separated by a comma:
filter=emails.value co "email" or username eq "username" and name.familyName eq "User_Family_Name" or name.middle eq "User_Middle_Name" and (age gt "16" and age lt "50")
-
count: 10
-
startIndex: 1
-
sortOrder: ascending
-
attributes: emails,phoneNumbers
Attribute operators for filtering
| Operator | Description | Behavior |
|---|---|---|
| eq | equal | The attribute and operator values must be identical for a match. |
| co | contains | The entire operator value must be a substring of the attribute value for a match. |
| sw | starts with | The entire operator value must be a substring of the attribute value, starting at the beginning of the attribute value. This criterion is satisfied if the two strings are identical. This does not work on DateTime fields. Filtering operators GT, GE, LT, and LE are suitable to filter on date ranges. |
| pr | present (has value) | If the attribute has a non-empty value, or if it contains a non-empty node for complex attributes, there is a match. |
| gt | greater than | If the attribute value is greater than the operator value, there is a match. The actual comparison is dependent on the attribute type. For string attribute types, this is a lexicographical comparison, and for DateTime types, it is a chronological comparison. |
| ge | greater than or equal | If the attribute value is greater than or equal to the operator value, there is a match. The actual comparison is dependent on the attribute type. For string attribute types, this is a lexicographical comparison, and for DateTime types, it is a chronological comparison. |
| lt | less than | If the attribute value is less than the operator value, there is a match. The actual comparison is dependent on the attribute type. For string attribute types, this is a lexicographical comparison, and for DateTime types, it is a chronological comparison. |
| le | less than or equal | If the attribute value is less than or equal to the operator value, there is a match. The actual comparison is dependent on the attribute type. For string attribute types, this is a lexicographical comparison, and for DateTime types, it is a chronological comparison. |
Unsupported SCIM features
-
Enterprise User Schema extension SCIM: Core Schema 1.1 - SCIM Enterprise User Schema Extension section.
-
Service Provider configuration schema SCIM: Core Schema 1.1 - Service Provider Configuration Schema section.
-
Resource schema: The resource endpoint is not compliant with SCIM specifications. Specifically, complex attributes are not presented according to the SCIM specifications. See user examples for an example. For further details, refer to SCIM: Core Schema 1.1 - Resource Schema section.
-
The OneWelcome Identity Platform does not support the optional XML representation. For further details, refer to SCIM: Core Schema 1.1 - XML Representation section.
