SCIM Action: Read a Resource

To retrieve or read a resource from the SCIM Service Provider, the HTTP GET verb is used. There are two mechanisms that can be used to retrieve a user - via a filter or directly. These are both described below.

The SCIM query defines filters that can be used to constrain the returned list of users as well as sorting and pagination mechanisms.NOTE: SCIM query, sort and pagination functionality is optional in the SCIM specifications so varying degrees of support may be found in SCIM Service Providers.

Retrieving Users via Filter

To query for a user you will use the SCIM filter language to form your query. The filter language is fairly straightforward and the operators are defined below:

equal

The attribute and operator values must be identical for a match.

contains

The entire operator value must be a substring of the attribute value for a match.

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.

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.

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.

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.

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.

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.

A simple example of a SCIM filter is to find a specific record by username:

username eq "marcher"

The filter expressions can be joined using the "and" and "or" logical operators and grouped via parentheses, for example to find all users who have a familyName that starts with "A" and have been modified since the 1st January 2015 we can use the filter:

(name.familyName sw "A") and (urn:scim:schemas:com_pingone:1.0:createTimeStamp gt 1420084800000)

When submitting the GET request with a filter, be sure to urlencode the filter value.

To retrieve our recently created user we will use the filter: username eq marcher which will be urlencoded and appended to the User endpoint as the filter parameter. Both requests below will result in the same response:

curl -v --user 1234-aaaa-bbbb-5678:eXJzbmVha3kh \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
https://directory-api.pingone.com/api/directory/user?filter=userName%20eq%20%22marcher%22

Retrieving Users Directly

If we know the resources location value, we can perform a GET directly on the user resource (which is defined in the "location" attribute in the "meta" section of the user record). So to retrieve Meredith’s profile directly I can also perform the following command:

curl -v --user 1234-aaaa-bbbb-5678:eXJzbmVha3kh \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
https://directory-api.pingone.com/v1/user/a7d67610-ceb5-4350-ba5a-746472c4f1f7

A successful request will result in a HTTP 200 OK response and the JSON representation of the user:

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
  "id":"a7d67610-ceb5-4350-ba5a-746472c4f1f7",
  "schemas": [
    "urn:scim:schemas:core:1.0",
    "urn:scim:schemas:com_pingone:1.0"
  ],
  "urn:scim:schemas:com_pingone:1.0": {
    "createTimeStamp":1429123454227,
    "accountId":"a6538050-412a-4bca-a44d-07deb4b073a8",
    "lastModifiedTimeStamp":1429123454227,
    "directoryId":"90b3dfe3-f8d0-45ad-8c04-047c88b03137",
    "state":"ACTIVE"
  },
  "name": {
    "familyName":"Archer",
    "givenName":"Meredith"
  },
  "userName":"marcher",
  "active":true,
  "emails": [
    {
      "value":"meredith.archer@pingdevelopers.com",
      "type":"work"
    }
  ],
  "meta": {
    "lastModified":"2015-04-15T12:44:14.227-06:00",
    "location":"https://directory-api.pingone.com/v1/user/a7d67610-ceb5-4350-ba5a-746472c4f1f7",
    "created":"2015-04-15T12:44:14.227-06:00"
  },
  "groups": [
    {
      "display":"Users",
      "value":"0b854f8d-a291-4e95-ad4b-68474a666e55"
    }
  ]
}

Developer Resources

SCIM Action: Read a Resource

Retrieving Users via Filter

Retrieving Users Directly