The following changes have been made to the PingAuthorize SCIM API.

The PingAuthorize Server’s SCIM 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:

A SCIM attribute may 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.

The attributes available in any particular SCIM resource type are defined by the schemas associated with the resource type. A resource type has at least one core schema and may have zero or more extension schemas. An extension schema may 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:

1. A core schema: urn:pingidentity:schemas:User:1.0
2. An extension schema: urn:pingidentity:schemas:sample:profile:1.0

The core schema attribute userName may be specified as userName or as urn:pingidentity:schemas:User:1.0.

The extension schema attribute termsOfService may only be specified as urn:pingidentity:schemas:sample:profile:1.0.

Common attributes

In addition to core schema and extension schema attributes, all SCIM resources of any type may have certain common attributes. These attributes never need to be namespaced with a URN.

List responses

Some SCIM responses, such as search responses, contain multiple resources. These responses are called list responses and have a consistent format using the following fields:

By default, the access token provided by the client in the request (see Authentication) is used to control access to requested resources. The PingAuthorize Server’s access control policies are customizable, but in general, the scopes granted by the access token determine which resources and attributes are returned.

If access controls determine that the client cannot access the requested resource, then a response with a 403 status code is returned.

{
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:Error"
    ],
    "scimType": "insufficient_scope",
    "status": 403,
    "detail": "Requested operation not allowed by the granted OAuth2 scopes."
}

A client may be allowed to access a resource but not all of its attributes. Clients should be prepared to receive incomplete resources, including resources stripped of attributes that are required by the schema.

For information about how to configure an application appropriately for SCIM API access, see configuring scopes in the PingAuthorize Server client developer guide.

Clients authenticate to the SCIM APIs by using bearer token authentication, as defined by RFC 6750. Every request must include an Authorization request header, where the header value uses the form Bearer {access token}.

A bearer token must be obtained from an external authorization server, such as PingFederate.

For each resource type, the PingAuthorize Server exposes a SCIM endpoint. For example:

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

Making requests

Each resource is addressable by an identifier; the combination of a resource type name (Users) and the identifier (5caa81af-ec05-41ff-a709-c7378007a99c) uniquely identifies the resource to the PingAuthorize Server. For example:

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

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 the request 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.

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 examples.

Because access controls enforced by the PingAuthorize Server’s policies and scopes can limit a client’s view of a resource, the server must assume that the client 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 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 server ignores 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 PingAuthorize 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 the client from inadvertently removing attributes that it did not specify because it did not have access to them.

The PingAuthorize 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.

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 can provide special query parameters to override this behavior.

The /Me endpoint

A special endpoint is available at /scim/v2/Me that acts as an alias for the currently authenticated user, the user associated with the bearer token.

For example, if the currently authenticated user is available via the path /scim/v2/Users/5caa81af-ec05-41ff-a709-c7378007a99c, then the same user resource will also be available through /scim/v2/Me. The two paths are interchangeable, and the /Me endpoint can be substituted in any request path where the combination of resource type and identifier might otherwise be used.

This includes sub-resources. For example, for an authenticated user with the ID 5caa81af-ec05-41ff-a709-c7378007a99c, the paths /scim/v2/Users/5caa81af-ec05-41ff-a709-c7378007a99c/password and /scim/v2/Me/password both identify the user’s password sub-resource.

Filtering searches

Some but not all endpoints support an optional filter parameter for filtering responses containing multiple resources. As a rule of thumb, 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, 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:

The following logical operators are supported:

The following grouping operators are supported:

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"]

For more information about searching with SCIM, including caveats, see the client developer guide.

Pagination

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

The PingAuthorize Server provides three service metadata endpoints, ServiceProviderConfig, Schemas, and ResourceTypes, which clients may use to discover information about the service’s capabilities, configuration, schemas, and resource types.

Clients do not necessarily need to rely on the service metadata endpoints. Clients may be developed based on an out-of-band understanding of the service configuration and data.

The user profile endpoint exposes user attributes from the PingAuthorize Server’s user store as SCIM resources.

Note that the schemas used, the resource type, and the endpoint name may all be configured differently than shown here.

This guide assumes that the PingAuthorize Server is configured to serve user resources at the /scim/v2/Users endpoint. The information in this reference is applicable to any resource type, however.

A special endpoint is available at /scim/v2/Me that acts as an alias for the currently authenticated user, the user associated with the bearer token.

For example, if the currently authenticated user is available via the path /scim/v2/Users/5caa81af-ec05-41ff-a709-c7378007a99c, then the same user resource will also be available through /scim/v2/Me. The two paths are interchangeable, and the /Me endpoint can be substituted in any request path where the combination of resource type and identifier might otherwise be used.

This includes sub-resources. For example, for an authenticated user with the ID 5caa81af-ec05-41ff-a709-c7378007a99c, the paths /scim/v2/Users/5caa81af-ec05-41ff-a709-c7378007a99c/password and /scim/v2/Me/password both identify the user’s password sub-resource.

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

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

Password update errors

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

{
     "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"
             }
         ]
     }
 }