SCIM operations in Liberty

The System for Cross-domain Identity Management (SCIM) 1.1 specifications are supported in Liberty.

WebSphere® Application Server Liberty supports SCIM 1.1 specifications. For more information about the specification, see http://www.simplecloud.info/.

Retrieving resources

To retrieve a known resource, you must send a GET request to the configured HTTP endpoint. See the following example: /Users/{id} or /Groups/{id}.

Additionally, the following example shows the operations against an LDAP registry:


    <ldapRegistry id="LDAP1" realm="SampleLdapIDSRealm" host="9.127.1.90" port="1389" ignoreCase="true"
        baseDN="o=ibm,c=us" ldapType="IBM Tivoli Directory Server" searchTimeout="8m" recursiveSearch="true"
        bindDN="xxxxxx" bindPassword="xxxxxxx">
	    <ldapEntityType name="PersonAccount">
	        <rdnProperty name="uid" objectClass="inetOrgPerson"/>
                <objectClass>inetOrgPerson</objectClass>
            </ldapEntityType>
            <ldapEntityType name="Group">
	        <objectClass>groupofnames</objectClass>
		<objectClass>ibm-nestedGroup</objectClass>
		  <rdnProperty name="cn" objectClass="groupofnames"/>
	    </ldapEntityType>
    <attributeConfiguration>
        <attribute name="title" propertyName="honorificPrefix" syntax="String" entityType="PersonAccount">
        </attribute>
	<attribute name="initials" propertyName="middleName" syntax="String" entityType="PersonAccount">
        </attribute>
	<attribute name="st" propertyName="honorificSuffix" syntax="String" entityType="PersonAccount">
        </attribute>
	<attribute name="l" propertyName="homeStateOrProvinceName" syntax="String" entityType="PersonAccount">
        </attribute>
	<attribute name="street" propertyName="homeStreet" syntax="String" entityType="PersonAccount">
        </attribute>
	<attribute name="postalAddress" propertyName="homeCity" syntax="String" entityType="PersonAccount">
        </attribute>
	<attribute name="postalCode" propertyName="homePostalCode" syntax="String" entityType="PersonAccount">
        </attribute>
       <attribute name="postOfficeBox" propertyName="homeCountryName" syntax="String" entityType="PersonAccount">
        </attribute>
        <attribute name="departmentNumber" propertyName="photoURLThumbnail" syntax="String" entityType="PersonAccount">
        </attribute>
	<attribute name="description" propertyName="photoURL" syntax="String" entityType="PersonAccount">
        </attribute>
    </attributeConfiguration>
    <groupProperties>
        <memberAttribute name="member" dummyMember="uid=dummy" objectClass="groupOfNames" scope="direct"/>
	<memberAttribute name="ibm-memberGroup" objectClass="ibm-nestedGroup" scope="direct"/>
    </groupProperties> 
</ldapRegistry>

To retrieve a resource from the LDAP, you must send a GET request as https://localhost:9090/ibm/api/scim/Users/uid=jsmith,o=ibm,c=us.

Querying resources

To query resources, you must send a GET request to the configured HTTP endpoint and specify the filter for searching. You can also specify the attributes parameter to return a subset of values from the returned resources and specify the paging and sorting parameters to organize the returned resources. The following examples show some of the filter options:

Specify the parameter to retrieve subset of the values: For example: https://localhost:9090/ibm/api/scim/Users?filter=givenname sw "Jo" retrieves all users whose name starts with Jo.
Specify the attributes parameter to retrieve subset of the values: For example: https://localhost:9090/ibm/api/scim/Users?filter=givenname sw "Jo"&attributes=username,emails&filter=name.familyname eq "Smith" retrieves the email addresses of the user name that starts with Jo and whose family name is Smith.
Specify the paging and sorting parameters to retrieve organized resources. For example, https://localhost:9090/ibm/api/scim/Users?filter=givenname sw "Jo"&attributes=username&sortBy=username&startIndex=3&count=5 retrieves the third page of the sorted result with each page containing five user names that start with Jo and whose family name is Smith.

Notes:

The underlying federated repositories determine whether the values that are specified in the filters are case-sensitive. In case of LDAP, the values are not case-sensitive by default, unless the attribute is mapped to a case-sensitive LDAP attribute.
User name cannot be used in the search filter.
When federating basic, SAF or custom registries that do not support the SCIM attributes, the filter pattern is always searched against the user name and only the user name attribute is returned.

Creating resources

To create new resources, you must send a POST request to the resource endpoint, that is, Users or Groups. The POST content must contain the user json object and the HTTP header content-type must be set to application/json.

Note: The application/xml content type is not supported.

To create a user, the following request must be posted to https://localhost:9090/ibm/api/scim/Users Content-Type


Content-Type: application/json
Content-Length: ...

{
  "schemas":["urn:scim:schemas:core:1.0"],
  "userName":"jdoe",
  "externalId": "uid=jdoe,o=ibm,c=us",
  "name":{
    "familyName":"Doe",
    "givenName":"Jane"
  }
}

The request must contain all the attributes that are required to successfully create a User or Group in the user registry. For example, in a back-end Tivoli Directory Server LDAP, the minimum set of LDAP attributes needed to create a user would be uid, sn, and cn; so any request for creation of user must contain userName, givenName, and familyName. The create operation fails if there are any schema violation from the user registry.

The externalId attribute acts like an identifier and must be specified. The attribute format depends on the specification of back-end user registry. In the previous example, the back-end is an LDAP server with a baseEntry as o=ibm,c=us and the RDN property for the user is set as UID, so the externalId becomes uid=jdoe,o=ibm,c=us.

Based on the create request, the created user object is returned.


{
    "schemas":["urn:scim:schemas:core:1.0"],
    "id":"uid=jdoe,o=ibm,c=us",
    "userName":"jdoe",
    "externalId":"uid=jdoe,o=ibm,c=us",
    "name":{
          "formatted":"Jane Doe",
          "familyName":"Doe",
          "givenName":"Jane"
    },
    "meta":{
         "lastModified":"2015-09-15T14:30:11",        "location":"https:\\localhost:9090\ibm\api\scim\Users\uid=jdoe,o=ibm,c=us",
         "created":"2015-09-15T14:30:11"
    }
}

When more than one LDAPs are configured and a create operation needs to be invoked, a default parent for the entity must be defined. The defined parent specifies the base entry under which the new entity would be created. The following example shows the configuration of a default parent for PersonAccount.


<federatedRepository>
    <primaryRealm name="WIMRegistry">
        <participatingBaseEntry name="o=ibm,c=us"/>
        <participatingBaseEntry name="o=ldap"/>
    </primaryRealm>
    <supportedEntityType>
        <defaultParent>o=ldap</defaultParent>
        <name>PersonAccount</name>
    </supportedEntityType>
</federatedRepository>

Modifying resources

To modify resources, one needs to send a PUT request to the resource endpoint, that is, /Users or /Groups. A PUT request performs a complete update of the resource. Any attributes that is not specified in the input are deleted.

Note: Partial updates with PATCH are not supported.

To modify the previously created resource, the following request must be posted to https://localhost:9090/ibm/api/scim/Users/uid=jdoe,o=ibm,c=us.


Content-Type: application/json
Content-Length: ...

{
  "schemas":["urn:scim:schemas:core:1.0"],
  "userName":"jdoe",
  "externalId":"uid=jdoe,o=ibm,c=us",
  "name":{
    "familyName":"Doe",
    "givenName":"Janet"
  }
}

This request modifies the given name of the object from Jane to Janet. The ID specified in the URL must match the externalId specified in the user object.

To modify a Group cn=employeeGroup,o=ibm,c=us and change the Group membership, the member attribute needs to be specified.


Content-Type: application/json
Content-Length: ...
{
    "id":"cn=employeeGroup,o=ibm,c=us",
    "schemas":["urn:scim:schemas:core:1.0"],
    "displayName":"employeeGroup",
    "externalId":"cn=employeeGroup,o=ibm,c=us",
    "members":[{"value":"uid=jdoe,o=ibm,c=us", "type":"User"},{"value":"cn=consultants,o=ibm,c=us", "type":"Group"}]
}

To modify a Group cn=employeeGroup,o=ibm,c=us and remove all the members from a group an empty member attribute needs to be specified.


Content-Type: application/json
Content-Length: ...
{
    "id":"cn=employeeGroup,o=ibm,c=us",
    "schemas":["urn:scim:schemas:core:1.0"],
    "displayName":"employeeGroup",
    "externalId":"cn=employeeGroup,o=ibm,c=us",
    "members":[]
}

Deleting resources

To delete resources, you need to send a DELETE request to the resource endpoint, that is, /Users or /Groups. For example, to delete the user uid=jdoe,o=ibm,c=us that is created in the previous example, send a request to https://localhost:9090/ibm/api/scim/Users/uid=jdoe,o=ibm,c=us

Note: SCIM runs only on Java 7 or later.