Rate this page

Making Requests

For each resource type, the Data Governance Broker exposes a SCIM endpoint. For example:

  • /scim/v2/Users
  • /scim/v2/Products
  • /scim/v2/Suppliers

Each resource is addressable by an identifier; the combination of a resource type name (“Users”) and the identifier (“25d0af58-a93b-4ba4-a49c-ab0fe35783c4”) uniquely identifies the resource to the Data Governance Broker. For example:

  • /scim/v2/Users/25d0af58-a93b-4ba4-a49c-ab0fe35783c4
  • /scim/v2/Users/b987b6e1-61e8-43ef-9a62-2796703556b2

Each resource might offer further sub-resources. For example:

  • /scim/v2/Users/25d0af58-a93b-4ba4-a49c-ab0fe35783c4/password
  • /scim/v2/Users/25d0af58-a93b-4ba4-a49c-ab0fe35783c4/consentHistory

Media types

All requests and responses use the UTF-8 character encoding and are formatted as JSON.

Clients must accept either the application/scim+json or application/json media types, and should always provide an Accept request header with one or both values.

When providing a request body (as with POST, PUT, and PATCH requests), clients should include a Content-Type request header with the value application/scim+json or application/json.

Searching

Some but not all endpoints support an optional filter parameter for filtering responses containing multiple resources.

SCIM filtering is described in detail by RFC 7644, section 3.4.2.2, and that should be considered an authoritative reference. The following discussion should not be considered exhaustive.

The value of the filter parameter is a search filter, which typically takes the form <attribute> <operator> <value>. For example:

filter=userName eq "pkd"

Search responses are always list responses, except in the case of an error.

The following attribute operators are supported:

Operator Description
eq equal
ne not equal
co contains
sw starts with
ew ends with
pr present
gt greater than
ge greater than or equal to
lt less than
le less than or equal to

The following logical operators are supported:

Operator
and
or
not

The following grouping operators are supported:

Operator Description
() Groups expressions to alter precedence.
[] Contains a filter expression to be applied to a complex attribute. See example below.

Example of filtering by a core attribute:

filter=userName eq "pkd"

Example of filtering by an extended attribute using the ‘starts with’ operator:

filter=urn:pingidentity:schemas:sample:profile:1.0:birthDate sw "1939"

Example of a complex filter:

filter=emails[value eq "glen@runciter.com"]

Example of a complex filter with two expressions:

filter=emails[value eq "glen@runciter.com" and type eq "work"]

Pagination

The client may provide pagination parameters to page through search result sets.

Parameter Description
startIndex The 1-based index of the first query result.
count A non-negative integer specifying the maximum number of matching resources to return per page. If 0 is specified, then no resources will be returned, but the totalResults field will still indicate the number of matching resources.

Searching with GET

A client may filter for matching resources by performing a GET and providing a filter query parameter, as described above. Pagination parameters may also be provided.

The response is formatted as a list response containing zero or more matching resources in the Resources field. If the request was valid, then the response will always use a 200 status code, even if no matching resources are found.

In the following example, a search is performed for resources under the Users endpoint using specific values for name.givenName and name.familyName.

Request:

GET /scim/v2/Users?filter=name.givenName%20eq%20%22Pat%22%20and%20name.familyName%20eq%20%22Conley%22 HTTP/1.1
Accept: application/scim+json
Authorization: Bearer eyJhbGciOi...
Content-Type: application/scim+json
Host: example.com:443

Response:

HTTP/1.1 200 OK
Content-Length: 672
Content-Type: application/scim+json
Date: Sat, 30 Jul 2016 00:28:56 GMT

{
    "Resources": [
        {
            "emails": [
                {
                    "primary": true,
                    "type": "work",
                    "value": "pat.conley@runciter.com"
                }
            ],
            "id": "76b4c133-87a7-4b2f-8058-4716e78b0fd4",
            "meta": {
                "created": "2016-07-30T00:28:07.507Z",
                "lastModified": "2016-07-30T00:28:07.507Z",
                "location": "https://example.com:443/scim/v2/Users/76b4c133-87a7-4b2f-8058-4716e78b0fd4",
                "resourceType": "Users"
            },
            "name": {
                "familyName": "Conley",
                "formatted": "Pat Conley",
                "givenName": "Pat"
            },
            "schemas": [
                "urn:pingidentity:schemas:sample:profile:1.0",
                "urn:pingidentity:schemas:User:1.0"
            ],
            "urn:pingidentity:schemas:sample:profile:1.0": {
                "birthDate": "1948-07-13"
            },
            "userName": "pconley"
        }
    ],
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:ListResponse"
    ],
    "totalResults": 1
}

Searching with POST

As an alternative to searching using the GET method, a client may filter for matching resources by performing a POST against the special .search endpoint and providing a filter query parameter, as described above. Pagination parameters may also be provided.

The response is formatted as a list response containing zero or more matching resources in the Resources field. If the request was valid, then the response will always use a 200 status code, even if no matching resources are found.

Example request:

POST /scim/v2/Users/.search HTTP/1.1
Accept: application/scim+json
Authorization: Bearer eyJhbGciOi...
Content-Length: 38
Content-Type: application/scim+json
Host: example.com:443

{
    "filter": "userName sw \"pc\""
}

Example response:

HTTP/1.1 200 OK
Content-Length: 672
Content-Type: application/scim+json
Date: Sat, 30 Jul 2016 00:02:16 GMT

{
    "Resources": [
        {
            "emails": [
                {
                    "primary": true,
                    "type": "work",
                    "value": "pat.conley@runciter.com"
                }
            ],
            "id": "76b4c133-87a7-4b2f-8058-4716e78b0fd4",
            "meta": {
                "created": "2016-07-30T00:01:23.824Z",
                "lastModified": "2016-07-30T00:01:23.824Z",
                "location": "https://example.com:443/scim/v2/Users/76b4c133-87a7-4b2f-8058-4716e78b0fd4",
                "resourceType": "Users"
            },
            "name": {
                "familyName": "Conley",
                "formatted": "Pat Conley",
                "givenName": "Pat"
            },
            "schemas": [
                "urn:pingidentity:schemas:sample:profile:1.0",
                "urn:pingidentity:schemas:User:1.0"
            ],
            "urn:pingidentity:schemas:sample:profile:1.0": {
                "birthDate": "1948-07-13"
            },
            "userName": "pconley"
        }
    ],
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:ListResponse"
    ],
    "totalResults": 1
}

Updating resources

SCIM resources are modified using the PUT and PATCH methods, described by sections 3.5.1 and 3.5.2 of RFC 7644, respectively. See the user profile API reference for simple examples.

HTTP method Description
PUT Replace an existing resource with a resource representation specified in the body of the request. Typically used after a client has obtained a resource using GET.
PATCH Perform a partial modification of a resource against specific attributes specified by the client. A PATCH request uses the following operation types: add, remove, replace

Because access controls enforced by the Data Governance Broker’s policies and scopes can limit a client’s view of a resource, the Broker must assume that the client may not have access to all attributes of a resource. This is important for PUT requests, because the Broker needs to distinguish between a case in which the client explicitly wishes to remove an attribute and a case in which the client does not know about an attribute. The general rule is that the Broker will ignore an attribute that is omitted from a PUT request, rather than deleting it. If a client explicitly wishes to delete an attribute, then it should set its value to null.

When a client requests a modification, the Broker computes the difference between the current state of the resource and the state specified by the modification request, applying a minimal set of changes when passing the modification request to the user store. In effect, this means that a PUT request is ultimately treated as if it were a PATCH request. This prevents unnecessary modifications from being sent to the user store and, more importantly, also prevents the client from inadvertently removing attributes that it did not specify because it did not have access to them.

The Data Governance Broker performs this diffing logic at the attribute and sub-attribute level, comparing each attribute in a modification request against the corresponding attribute in the current resource. For multivalued, complex attributes, the Broker iterates through the values in the modification request and tries to find the corresponding value in the current resource to determine a match. If it is found, it then diffs at the sub-attribute level.

This behavior is summarized by the following table.

Operation Result
PUT request omitting a simple single-valued attribute (such as userName). No change.
PUT or PATCH request setting a simple single-valued attribute to null. The attribute is deleted.
PUT or PATCH request replacing the value of a multi-valued attribute, omitting an existing member. The omitted attribute is deleted.
PUT or PATCH request replacing the value of a complex attribute, omitting an existing sub-attribute. No change to the omitted sub-attribute.

For example, if the current value of a resource’s phoneNumbers attribute is:

"phoneNumbers": [
   {
      "value": "054-757-2291",
      "type": "work",
      "primary":"true"
   }
]

And a modification request includes:

"phoneNumbers": [
   {
      "value": "054-757-2291",
      "primary": "false"
   }
]

Then the final result is:

"phoneNumbers": [
   {
      "value": "054-757-2291",
      "type": "work",
      "primary": "false"
   }
]

When finding a matching value in a complex attribute, matches of the value, $ref, type, and display sub-attribute values are given more weight when compared to values of other sub-attributes. This is done because the above sub-attribute values are typically unique for any given complex attribute.

Specifying attributes to return

By default, all attributes that the client is authorized to read will be returned when a resource is requested. Your application may provide special query parameters to override this behavior.

Parameter Description
attributes Indicates the set of attributes to include in the response. Takes a comma-separated list of attribute names. Extension schema attribute names must be prefixed with the extension schema URN.
excludedAttributes Indicates a set of attributes to exclude from response. Takes a comma-separated list of attribute names. Extension schema attribute names must be prefixed with the extension schema URN.

Note that the attributes and excludedAttributes parameters are mutually exclusive and should not both be specified in the same request.