PingDirectory and PingDirectoryProxy SCIM 2.0 API Reference

Before you read the PingDirectory and PingDirectoryProxy SCIM 2.0 API topics or use the API, review the following:

In addition, ensure you are familiar with HTTP headers, methods, and response codes. For more information, see the following articles:

Overview

The PingDirectory and PingDirectoryProxy SCIM 2.0 APIs are a set of REST interfaces based on the SCIM (System for Cross-domain Identity Management) 2.0 standard. With these APIs, you can:

  • Create users.

  • Search for users.

  • Retrieve and update a user’s profile.

  • Change a user’s password.

  • Manage a user’s login sessions.

  • Retrieve a user’s history of consent to data access.

  • Manage second factor authentication settings.

With SCIM 2.0, any type of data is called a resource type. One or more schemas specify the attributes available for any given resource type. Resources are formatted as JSON and are requested using standard HTTP methods such as GET, POST, or PATCH. For more information about SCIM 2.0, see RFC 7642, RFC 7643, and RFC 7644.

To use these APIs, you must configure PingDirectory or PingDirectoryProxy for SCIM 2.0. You can set up PingDirectory as a stand-alone server. Whereas, you must set up PingDirectoryProxy with an external PingDirectory server.

For more information on configuring PingDirectory for SCIM 2.0, see Configuring SCIM 2.0 on Your Server. For more information on configuring PingDirectoryProxy for SCIM 2.0, see the PingDirectoryProxy Server Administration Guide.

These topics provide the following information about the PingDirectory and PingDirectoryProxy SCIM 2.0 APIs:

Data types and resources

The PingDirectory and PingDirectoryProxy SCIM 2.0 APIs use the data types and resource format specified by the SCIM 2.0 schema standard, RFC 7643.

SCIM data types

SCIM attributes are typed. The following data types are used:

Data type Description
string A JSON string.
boolean A JSON boolean value, true or false.
decimal A JSON floating-point number.
integer A JSON integer number.
dateTime A JSON string representing a timestamp. SCIM DateTime values are always encoded as an xsd:dateTime value, as specified by XML Schema, section 3.3.7.
binary A JSON string representing a binary value. SCIM binary values are always base64-encoded.
reference A JSON string representing a reference to another resource. A SCIM reference is always a URI: This can be a URN, the URL of another SCIM resource, or another URL. URLs can be absolute or relative.
Object A JSON object. A SCIM complex attribute is a composition of sub-attributes. These sub-attributes can have any data type except “complex”.

A SCIM attribute can also be multi-valued. All members of a multi-valued attribute must be of the same data type.

SCIM resource format

A SCIM resource is always represented as a JSON object.

SCIM schemas define a resource's attributes. A resource type has at least one core schema and can have zero or more extension schemas. An extension schema can be configured to be either required or optional for a resource to be valid.

SCIM schemas provide the means of namespacing JSON attributes. Every schema is identified by a unique schema URN prefix. When specifying attributes, the schema URN prefix is implied for attributes belonging to the core schema but must be provided for attributes belonging to extension schemas. Consider this example resource:

{
  "schemas": [
    "urn:pingidentity:schemas:User:1.0",
    "urn:pingidentity:schemas:sample:profile:1.0"
  ],
  "id": "5caa81af-ec05-41ff-a709-c7378007a99c",
  "meta": {
    "created": "2016-06-07T13:13:30.873Z",
    "lastModified": "2016-06-07T13:13:30.873Z",
    "resourceType": "Users",
    "location": "https://example.com/scim/v2/Users/5caa81af-ec05-41ff-a709-c7378007a99c"
  },  
  "userName": "joe.chip",
  "name": {
    "familyName": "Chip",
    "formatted": "Joe Chip",
    "givenName": "Joe"
  },
  "accountVerified": true,
  "urn:pingidentity:schemas:sample:profile:1.0": {
    "termsOfService": [
      {
        "id": "urn:X-pingidentity:ToS:StandardUser:1.0",
        "timeStamp": "2014-11-23T16:36:59Z",
        "collector": "urn:X-pingidentity:App:Mobile:1.0"
      }
    ]
  }
}

This resource has two schemas:

  • A core schema: urn:pingidentity:schemas:User:1.0

  • An extension schema: urn:pingidentity:schemas:sample:profile:1.0

The core schema attribute userName can be specified as userName or as urn:pingidentity:schemas:User:1.0: {"userName": ...}.

The extension schema attribute termsOfService can only be specified as urn:pingidentity:schemas:sample:profile:1.0: {"termsOfService": [...]}.

Common attributes

In addition to core schema and extension schema attributes, all SCIM resources can have common attributes. These attributes never need to be namespaced with a URN.

Common attribute Description
id An immutable unique identifier for the resource. This attribute is always present.
externalId An optional identifier assigned to the resource by the client that provisioned it.
meta A complex read-only attribute containing resource metadata. Its sub-attributes are described in the following table.
Meta sub-attribute Description
resourceType The resource type.
created A timestamp indicating the resource’s creation date.
lastModified A timestamp indicating the time of the resource’s last update.
location The canonical URI of the resource.

List responses

Some SCIM responses, such as search responses, contain multiple resources. These responses are called list responses and include the following fields:

Field Type Provided? Description
schemas array always The SCIM schema of the list response. Always contains the value urn:ietf:params:scim:api:messages:2.0:ListResponse.
totalResults number always The number of matching resources.
startIndex number The index of the first result in the current set of list results. Index starts at 1. Always present if pagination is used.
itemsPerPage number The number of resources returned per page. Always present if pagination is used.
Resources array always An array consisting of one or more resource objects. For example, this may contain all of the User resources matching a search query.

Authentication

Authenticate PingDirectory and PingDirectoryProxy SCIM 2.0 API requests with an OAuth 2.0 access (bearer) token, as defined by RFC 6750. Obtain the bearer token through an OAuth 2 authorization server, such as PingFederate. Add the bearer token to the Authorization header of your requests.

curl --location --request GET '{{apiPath}}/scim/v2/Users/5caa81af-ec05-41ff-a709-c7378007a99c?attributes=userName' \
--header 'Authorization: Bearer eyJraWQiOiJBY2Nlc3MgVG9rZW4gU2lnbmluZ...' \
--header 'Accept: application/scim+json' \
--header 'Accept-Encoding: gzip, deflate'

If the access token is missing, expired, or invalid, the server responds with a status code of 401 Unauthorized.

{
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:Error"
    ],
    "scimType": "invalid_token",
    "status": 401,
    "detail": "Access token is expired or otherwise invalid."
}

Authorization

For Authentication, you provide an OAuth 2.0 access (bearer) token. That bearer token controls access to which resources and attributes are returned. It does this through a scope that an administrator configures on the server that contains the data. What this means is that regardless of whether you use PingDirectory or PingDirectoryProxy as the endpoint server, you always configure access controls on the PingDirectory server. For more information on configuring SCIM 2.0 on PingDirectory, see Configuring SCIM 2.0 on Your Server.

If access controls determine that you cannot perform the requested operation, the response depends on the request. See the following examples.

  • If you send a search request, but you do not have search and read permissions, you get a 200 OK status code without any results.

  • If you send a retrieve, replace, or modify request, but you do not have search and read permissions, you get a 404 Not Found status code.

    {
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:Error"
    ],
    "status": 404,
    "detail": "Request failed:
    correlationID='473ac6b1-50e5-4c48-9d65-8b1fc633280d'"
    }
    
  • If you send a create, replace, or modify request and you have search and read permissions, but you do not have write permissions, you get a 403 Forbidden status code.

    {
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:Error"
    ],
    "status": "403",
    "detail": "Request failed:
    correlationID='aa74e893-2ae6-4395-b3c4-351f38becb8a'"
    }
    

Based on access control configuration, you may be allowed to access a resource but not all of its attributes. See your administrator if you receive incomplete resources, including resources stripped of attributes that are required by the schema.

Requests and responses

Each resource has an identifier. The resource type name (Users) is combined with the identifier (5caa81af-ec05-41ff-a709-c7378007a99c) to uniquely identify the resource to the PingDirectory or PingDirectoryProxy Server. For example:

/scim/v2/Users/5caa81af-ec05-41ff-a709-c7378007a99c

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

HTTP request headers

  • Accept

    Provide this header with a value of application/scim+json or application/json.

  • Content-Type

    If you provide a request body (as with POST, PUT, and PATCH requests), also include this header with the value application/scim+json or application/json.

Updating resources

SCIM resources are modified using the PUT and PATCH methods, described in sections 3.5.1 and 3.5.2 of RFC 7644. For examples, see User profile endpoints.

HTTP method Description
PUT Updates a resource by completely replacing it.
PATCH Updates a resource by modifying only the changes to be made.

Because access controls enforced by the PingDirectory server policies and scopes can limit your view of a resource, the server must assume that you may not have access to all attributes of a resource. This is important for PUT requests, because the server needs to distinguish between a case in which you explicitly wish to remove an attribute and a case in which you do not know about an attribute. The general rule is that the server ignores an attribute that is omitted from a PUT request, rather than deleting it. If you explicitly wish to delete an attribute, then you should set its value to null.

When you request a modification, the server 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 you from inadvertently removing attributes that you did not specify because you did not have access to them.

The server 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 server 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 of the array. The omitted member is deleted.
PUT or PATCH request replacing the value of a complex attribute, omitting an existing sub-attribute from the object. 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 you are authorized to read are returned when a resource is requested. Your application can 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 the response. Takes a comma-separated list of attribute names. Extension schema attribute names must be prefixed with the extension schema URN.

Filtering searches

Some endpoints support an optional filter parameter for filtering responses containing multiple resources. In general, if a SCIM path returns a single resource, it does not support filtering. If it returns multiple resources, then it generally supports filtering. For example, /scim/v2/Users supports filtering, but /scim/v2/Users/{userId} does not.

SCIM filtering is described in detail by RFC 7644, section 3.4.2.2. 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.

The following is a sample of filtering by a core attribute:

filter=userName eq "pkd"

The following is a sample of filtering by an extended attribute using the 'starts with' operator:

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

The following is a sample of a complex filter:

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

The following is a sample of a complex filter with two expressions:

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

Pagination

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

Parameter Description
startIndex The index of the first query result. Indexing starts at 1.
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.

Search users


Search users

Errors

Like all other responses, errors are returned as SCIM responses with a media type of application/scim+json.

Some errors contain correlation IDs that can be used to troubleshoot. For more information, see Troubleshoot the SCIM 2.0 Servlet Extension.

Field Type Provided? Description
schemas array always SCIM schemas used in the error message. The schemas array always includes the value urn:ietf:params:scim:api:messages:2.0:Error to identify the message as an error. Other schema values can be present if Ping Identity-proprietary error fields are used.
status number always The HTTP status code of the error. This is always in the 400 or 500 range.
scimType string An error code defined by RFC 7644, section 3.12.
detail string A human-readable error description. In some cases, this field contains a correlation ID corresponding to log messages on the endpoint server.
{
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:Error"
    ],
    "status": "400",
    "detail": "Request failed: correlationID='269bb1a8-8c51-48b3-83a0-380e1d4b4ab9'"
}

Password update errors

If an error response is returned because of a password update failure, an additional field is provided under the urn:unboundid:scim:api:messages:2.0:PasswordUpdateError schema URN.

Field Type Provided? Description
passwordRequirements array An array of password quality requirements. These are rules that must be satisfied in order to successfully change a password.
{
     "detail": "The provided new password cannot be the same as the current password or any password in the user's password history",
     "schemas": [
         "urn:pingidentity:scim:api:messages:2.0:PasswordUpdateError"
     ],
     "scimType": "invalidValue",
     "status": 400,
     "urn:pingidentity:scim:api:messages:2.0:PasswordUpdateError": {
         "passwordRequirements": [
             {
                 "additionalInfo": "The provided new password cannot be the same as the current password or any password in the user's password history.",
                 "description": "The new password must not be the same as the current password.",
                 "requirementSatisfied": false,
                 "type": "notCurrentPassword"
             }
         ]
     }
 }

Service metadata endpoints

The PingDirectory and PingDirectoryProxy SCIM 2.0 API provides service metadata endpoints. You can use these endpoints to return information about the service’s capabilities, configuration, schemas, and resource types.


READ a SCIM service provider configuration


READ SCIM schemas


READ a SCIM schema


READ SCIM resource types


READ a SCIM resource type

User profile endpoints

The user profile endpoints expose user attributes from the PingDirectory or PingDirectoryProxy user store.

This guide assumes that the PingDirectory or PingDirectoryProxy server is configured to serve user resources at /scim/v2/Users. If your server is configured differently, adjust the endpoint accordingly.


CREATE a user


READ search users


READ search users


READ a user


UPDATE a user


UPDATE Replace one or more user attributes


UPDATE Add a member to user attributes


UPDATE Remove a value from user attributes


DELETE a user