SCIM in WSO2 Product IS 5.8.0

Over the past few years the world has been moving towards cloud-based environments. In our increasingly cloud-based world, Identity provisioning is a critical factor since safety and confidentiality of users’ data is a major concern.

This is where SCIM comes to the rescue. The System for Cross-domain Identity Management (SCIM) is an open standard for Identity Provisioning in cloud-based applications and services. WSO2 Identity Server supports SCIM 1.1 and SCIM 2.0 for identity provisioning via WSO2 Charon under Apache 2.0 license, which is an open source implementation of SCIM protocol.

The following is a high-level overview of the SCIM Service Provider architecture of the Identity Server.

Read more about SCIM implementation using WSO2 Charon

The newest release of WSO2 Identity Server 5.8.0 has enhanced SCIM functionalities compared to the previous versions of the Identity Server. The Identity Server has different SCIM endpoints and in this blog, I will be focusing on the improvements of the USERS endpoint and GROUPS endpoint. Before moving into new features, let’s look at the limitations of the previous versions.

In previous IS versions, one had two options to choose from when it comes to user retrieval from the USERS endpoint.

• Get users without a filter (user listing)
• Get users with a filter

Is listing and filtering confusing? Let me give a small real-world example. Go to google maps and search for restaurants. Then you’ll get a bunch of names. This is listing because you have not used any filter. Now search for KFC. So now you have filtered a restaurant name from all the restaurants. This is the difference between listing and filtering. Easy right?

• Getting users without a filter (user listing):

A user listing request [1] will retrieve all the users. When the domain is specified in the request, the response should include only users of that domain. In previous Identity Server versions, the sample request [2] retrieved all the users from all the user stores even though the domain parameter was specified as PRIMARY. Also, user listing requests did not support pagination. Therefore, all the users were retrieved even though the startIndex and count parameters were specified. Therefore, these became major limitations in user listing.

[1] -curl -v -k — user admin:admin ‘https://localhost:9443/scim2/Users?startIndex=1&count=10'
[2] -curl -v -k — user admin:admin ‘https://localhost:9443/scim2/Users?startIndex=1&count=10&domain=PRIMARY'

• Getting users with a filter:

A filtering request will be one of two flavors, single attribute filter or multi attribute filter. Let me explain the difference of multi attribute filtering. Let’s take the KFC example (Yes, I love KFC). So in the first example you searched for KFC. There is only one search attribute which is only the name of the restaurant. Now you search for KFC located in Colombo, Sri Lanka. In this case you have two attributes, the restaurant name “KFC” and the location “Colombo, Sri Lanka”.

Sample request [3] is an example of a single attribute filter and sample request [4] is an example of a multi attribute filter [4] that asks for users who match multiple attributes.

[3] -curl -v -k — user admin:admin ‘https://localhost:9443/scim2/Users?startIndex=1&count=10&domain=PRIMARY&filter=userName+sw+ki'
[4] -curl -v -k — user admin:admin ‘https://localhost:9443/scim2/Users?startIndex=1&count=10&domain=PRIMARY&filter=userName+sw+ki+and+name.familyName+co+ack'

In single attribute filtering, users are filtered from a user store when the domain parameter is populated. In previous IS versions, this feature worked perfectly except in the following scenario. When filtering users according to their groups (roles), the groups attribute did not support filtering in a given domain [5], instead it only retrieved users in the PRIMARY domain.

[5] -curl -v -k — user admin:admin ‘https://localhost:9443/scim2/Users?startIndex=1&count=10&domain=SECONDARY&filter=groups+sw+eng'

Similar to the USERS endpoint, the Identity Server provides two ways to retrieve groups (roles) at the GROUPS endpoint.

• Get groups without a filter (user listing).
• Get groups with a filter.

A real-world example of the groups endpoint listing is, list all the groups in the system and for filtering, display group names that contain the phrase “manager”.

Both listing and filtering in the groups endpoint, did not support the domain parameter. Therefore, sample requests [6] and [7] retrieved all the groups from all the user stores.

[6] -curl -v -k — user admin:admin ‘https://localhost:9443/scim2/Groups? &domain=PRIMARY ‘
[7] -curl -v -k — user admin:admin ‘https://localhost:9443/scim2/Groups? domain=PRIMARY&filter=displayName+sw+eng’

These are a few limitations of the USERS and GROUPS endpoints of previous IS version. The next section is the best part; the enhancements of IS 5.8.0.

SCIM enhancements in Identity Server 5.8.0

With IS 5.8.0, user listing (GET user without filter) supports both domain filtering and pagination. Therefore, for sample request [2], the response will be the exact number of users from the specified domain.

With IS 5.8.0, filtering users according to their group name supports filtering according to a specified domain. To filter users in a specified domain there are two ways that one can follow.

1. Specify the domain in the request as a parameter [2]. This is the most recommended method.
2. Specify the domain in the filter attribute value [8]. But if you are following this method, you have to remember that this will only work if the filter attribute is either a ‘username’ uri or a ‘group’ uri.

[8] -curl -v -k — user admin:admin ‘https://localhost:9443/scim2/Users?filter=userName+sw+ PRIMARY/ki’

Read more about user retrieval, refer WSO2 documentation.

The enhanced groups endpoint of IS 5.8.0 now supports domain filtering in both groups listing and filtering. Therefore, request [6] will only retrieve groups from the specified domain. Similar to the USERS endpoint, filtering groups in the GROUPS endpoint has two ways.

1. Specify the domain as a parameter in the request. This is the most recommended method.
2. Specify the domain in the filter attribute value [9]. Remember, you cannot use this feature with all filter attributes. This will work only with the displayName uri, members.value uri or members.display uri.

[9] -curl -v -k — user admin:admin ‘https://localhost:9443/scim2/Groups?filter=displayName+sw+ PRIMARY/eng’

Read more about groups retrieval, refer WSO2 documentation.

StartIndex and Count parameters

According to the SCIM2 specification, any negative value needs to be interpreted as zero and count equals zero should not retrieve any response. However, this was not honored in the previous versions. In the IS 5.8.0 any value less than zero will be interpreted as zero and will not retrieve any results. If the count value is not specified in the request, all the results will be retrieved. As a rule of thumb, it is recommended to use the count parameter to improve the efficiency of the system.

New properties for filtering

With Identity Server 5.8.0, three new properties have been introduced in identity.xml to enhance SCIM2 filtering.

• FilterUsersAndGroupsOnlyFromPrimaryDomain

With this property enabled, filtering will only take place in the primary user store if the domain is not specified in the request.

• MandateDomainForUsernamesAndGroupNamesInResponse

In a typical filtering response, primary domain name is not prepended (eg: PRIMARY/adminUser) for both usernames and group names of the primary user store. But, when this property is enabled, the primary domain name will be prepended to both usernames and group names of the primary user store.

• MandateDomainForGroupNamesInGroupsResponse

In IS 5.7.0, primary domain name was prepended for group names which are in the primary user store (PRIMARY/manager). But with IS 5.8.0 that behavior is changed. The new behavior is that there is no domain name in front of the group name. So, if you wish to maintain the old behavior, Identity 5.8.0 respects that. Therefore, to get the old behavior you just have to enable this property.

So there you have it, these are the SCIM enhancements that you could expect in WSO2 Identity Server 5.8.0.