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}
.
<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
- 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.
- 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
Users
or Groups
. The POST content must contain the user
json
object and the HTTP header content-type must be set to
application/json
. application/xml
content type is not
supported.
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
.
{
"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"
}
}
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
/Users
or /Groups
. A PUT request performs a complete update of the
resource. Any attributes that is not specified in the input are deleted.
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.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"}]
}
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