SCIM operations in the Liberty profile

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

Retrieving resources

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

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

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":"bjensen",
  "externalId": "uid=bjensen,o=ibm,c=us",
  "name":{
    "familyName":"Jensen",
    "givenName":"Barbara"
  }
}

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=bjensen,o=ibm,c=us.

Based on the create request, the created user object is returned.
{
    "schemas":["urn:scim:schemas:core:1.0"],
    "id":"uid=bjensen,o=ibm,c=us",
    "userName":"bjensen",
    "externalId":"uid=bjensen,o=ibm,c=us",
    "name":{
          "formatted":"Barbara Jensen",
          "familyName":"Jensen",
          "givenName":"Barbara"
    },
    "meta":{
         "lastModified":"2015-09-15T14:30:11",        "location":"https:\\localhost:9090\ibm\api\scim\Users\uid=bjensen,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=bjensen,o=ibm,c=us.
Content-Type: application/json
Content-Length: ...

{
  "schemas":["urn:scim:schemas:core:1.0"],
  "userName":"bjensen",
  "externalId":"uid=bjensen,o=ibm,c=us",
  "name":{
    "familyName":"Jensen",
    "givenName":"Barb"
  }
}
This request modifies the given name of the object from Barbara to Barb. 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=bjensen,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=bjensen,o=ibm,c=us that is created in the previous example, send a request to https://localhost:9090/ibm/api/scim/Users/uid=bjensen,o=ibm,c=us
Note: SCIM runs only on Java 7 or later.

Icon that indicates the type of topic Reference topic



Timestamp icon Last updated: Saturday, 3 December 2016
http://www14.software.ibm.com/webapp/wsbroker/redirect?version=cord&product=was-nd-mp&topic=rwlp_sec_scim_operations
File name: rwlp_sec_scim_operations.html