The SCIM Protocol is an application level, REST protocol for provisioning and managing identity data on the web.

The protocol supports creation, modification, retrieval and discovery of core identity resources (e.g. users and groups, as well as custom resource extensions). For more details, refer to SCIM:Protocol 1.1.

Note: iWelcome’s SCIM interface supports the functional behavior as described below. Sensible queries can be used to incidentally search for users. Structural usage of SCIM filtering as a part of a regular flow in client applications may however have a performance penalty. Therefore this needs to be discussed with iWelcome to ensure the default indexes allow for sufficient performance and possibly to have iWelcome create additional indexes.

Caption:

  • compliance is indicated
  • βœ… indicates compliance
  • ✳️ indicates optional features that are supported
  • πŸ”† indicates optional features that are not supported
  • βœ–οΈ indicate non compliance
  • semantics for specific fields are described.

Authentication and Authorisation

The iWelcome SCIM API supports all the authentication methods as described in SCIM:Protocol 1.1 - Authentication and Authorization section.

Access to iWelcome’s SCIM API can be protected by using one of the following mechanisms:

  • OAuth2 bearer token (default).
  • Basic authentication using username and password is should be avoided.
    Note: Support will stop on April 2021.

In addition to each of these methods, iWelcome provides the following optional features that can be configured upon request:

  • Client certificate authentication;
  • IP-filtering to add another layer of security.

When basic authentication is used, the client is authorised to use all the methods on the SCIM user endpoint.
When OAuth bearer tokens are used, the authorisations for the client can be limited and are controlled by the OAuth scopes associated with the OAuth access token. The following scope values are used by the SCIM API:

  • SCIM:user:get
  • SCIM:user:post
  • SCIM:user:delete
  • SCIM:user:put
  • SCIM:user:patch
  • SCIM:user:query

Note: The scope value SCIM:user:get is needed to retrieve a known user as per Retrieving a known Resource.
The scope value SCIM:user:query is needed to query users as per List/Query Resources.

API

The following table indicates which operations are supported by iWelcome.

Resource Endpoint βœ… Operations Supported by iWelcome βœ–οΈ Operations not supported by iWelcome
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

Customers that choose to use iWelcome's 'multi-branding' capabilities, will be provided with multiple endpoints per brand. Often multi-branding is combined with using multiple segments case in which separate endpoints per required combination of segment and brand are set-up.

Creating Resources

Differences between a user POST-request and response:

  • An ID is added (this is required for updating and deleting the user).
  • Meta information is added (of particular interest is the version, which is discussed in the update section).
  • In case a User is created, the password value is not returned in the response.

For more details, refer to SCIM:Protocol 1.1 - Creating Resources section.

Retrieving Resources

For more details, refer to SCIM:Protocol 1.1 - Retrieving Resources section.

  • Retrieving a known Resource

    βœ… compliant

  • List/Query Resources

    βœ… compliant

  1. Filtering

βœ… Filtering is supported, with a few limitations.

Attribute operators

Operator Description Behavior iWelcome Support
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. βœ–οΈ Support of this operator is dropped because of indexing/performance reasons.
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, 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 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 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. βœ…


Logical and grouping operators

Operator Description Behavior iWelcome Support
and Logical And The filter is only a match if both expressions evaluate to true. βœ…
or Logical Or The filter is a match if either expression evaluates to true. βœ…
() Precedence grouping Boolean expressions may be grouped using parentheses to change the standard order of operations; i.e., evaluate OR logical operators before log βœ…

βœ… Filters are evaluated using standard order of operations.

βœ… Attribute names and operators are case insensitive.

βœ–οΈ Searches on string type attributes are case insensitive.

No additional operations are implemented.

  1. Sorting

βœ… Sorting is supported. Default values for SortBy is the resource's creationDate, default value for SortOrder is ASC.

  1. Pagination

βœ… Pagination is supported. Default value for number of results per page (count) is 100.

Modifying Resources

Please refer to the above table in this section to see which operations are supported for which resource types. In this section we indicate specifics for the operations that are supported. For more details, refer to SCIM:Protocol 1.1 - Modifying Resources section.

  • Modifying with PUT

    βœ… Compliant

  • Modifying with PATCH

    βœ… Compliant

Deleting Resources

βœ… Compliant

For more details, refer to SCIM:Protocol 1.1 - Deleting Resources section.

Bulk

πŸ”† BULK is optional and is not supported.

For more details, refer to SCIM:Protocol 1.1 - Bulk section.

Data Input/Output Formats

βœ… iWelcome only supports JSON encoded request/responses.

πŸ”† The optional XML encoding is not supported.

For more details, refer to SCIM:Protocol 1.1 - Data Input/Output Formats section.

Additional Retrieval Query Parameters

βœ… Compliant

iWelcome supports requesting a partial Resource representation. When the query parameter 'attributes' is specified on the request URL, iWelcome will return Resource representations containing only the explicitly requested attributes.

When partial Resources representations are requested this will not influence which resources are returned; possibly the partial representation of a resource that is returned, is 'empty' when the resource does not have any of the requested attributes.

Warning: iWelcome does not support any additional retrieval parameters.

For more details, refer to SCIM:Protocol 1.1 - Additional Retrieval Query Parameters section.

Attribute Notation

Attribute notation as specified here is not used.

iWelcome's Trust-extension uses a different way of referencing attributes, see SCIM - Core schema 1.1 compliance.

HTTP Response Codes

βœ… Compliant

For more details, refer to SCIM:Protocol 1.1 - HTTP Response Codes section.

API Versioning

iWelcome currently only supports v1.1 of the SCIM specification. iWelcome's endpoint's are compliant. For more details, refer to Endpoint Overview. iWelcome has an additional versioning mechanism on iWelcome's implementation of the SCIM v1.1.

To get the latest version of iWelcome SCIM API (such as v2.0), the following information needs to be part of the http-request headers:

Content-Type: application/vnd.iwelcome-v2.0+json

For more details, refer to SCIM:Protocol 1.1 - API Versioning section.

Versioning Resources

βœ… Compliant

For more details, refer to SCIM:Protocol 1.1 - Versioning Resources section.

HTTP Method Overloading

πŸ”† iWelcome does not support this.

For more details, refer to SCIM:Protocol 1.1 - HTTP Method Overloading section.

Security Considerations

βœ… iWelcome supports TLS v1, TLS v1.1, TLS v1.2

For a more detailed description, refer to SCIM:Protocol 1.1 - Security Considerations section.