PingOne Platform APIs

SCIM

The System for Cross-domain Identity Management (SCIM) defines an open standard protocol for identity management via HTTP in RFC 7644. The PingOne SCIM API provides support for this protocol within the PingOne platform.

This PingOne SCIM API makes PingOne a SCIM Service Provider - the system which accepts incoming user provisioning and user update requests. Being a SCIM Client - sending identities outbound for creation in foreign systems - is separate and handled by Identity Propagation (Provisioning) via the SCIM provisioning connector.

The PingOne SCIM API, at a high level, acts as a translation layer that receives SCIM requests to then issue as equivalent PingOne API requests, and translates PingOne API responses to SCIM-compliant responses for the user.

PingOne supports only version 2.0 of the SCIM standard. PingOne will not support the 1.1 version of the standard, and the 1.0 version is officially deprecated.

In the SCIM API sample requests shown in this document, the {{scimPath}} variable in the sample requests represents the regional domain for the PingOne server. Refer to PingOne API domains for more information.

Calls to the SCIM API require a PingOne admin-level access token to authenticate the requests. Like other PingOne management APIs, an access token from a Worker app gives you access to the SCIM API (and for these requests, the Worker app must include the Identity Data Admin role).

Highlights of the PingOne SCIM API

  • SCIM is an open standard used for identity management that PingOne supports.

  • Support for SCIM in PingOne is provided by an API that translates HTTP calls between the SCIM client and PingOne.

  • The URI for interacting with the PingOne SCIM API takes the form of: https://scim-api.pingone.com/environments/{{envID}}/v2/.

  • The PingOne SCIM API supports an extended version of SCIM users (that is, users with a URN of urn:ietf:params:scim:schemas:core:2.0:User) as well as "direct-mapped" users.

  • Direct-mapped users allow clients to use the PingOne SCIM API without worrying about schema resource mappings.

  • SCIM users in PingOne include a SCIM extension schema to include PingOne-specific data, such as the population identifier.

  • All user data created via the PingOne SCIM API or directly via the PingOne API can be modified or deleted by using either API, regardless of how the resource was initially created.

  • PingOne does not support some SCIM attributes, such as x509Certificates. Attempts to add or modify this data will be ignored, in accordance with the SCIM protocol.

  • The PingOne SCIM API does not support pagination. Lists of resources, such as ListResponse objects, return no more than 200 elements.

  • Groups are not supported.

  • PingOne supports SCIM POST searches that provide filtering data in a JSON body.

  • PingOne supports querying SCIM resources with attribute filters as query parameters.

PingOne SCIM API constraints

Some attributes are multi-valued in the SCIM standard schema, but single-valued in the PingOne schema. These SCIM attributes are emails, phoneNumbers, photos, and addresses. Because PingOne can only accept one value for these attributes, the SCIM API will reject requests that provide more than one values. However, they must still be provided as an array with only one element.

The SCIM standard states that the HTTP 501 (Not Implemented) error code should be returned when an invalid endpoint is accessed. However, due to infrastructure limitations, invalid endpoints will return an HTTP 404 (Not Found). The exception to this is when established SCIM endpoints that are not supported by PingOne (such as /Me) are queried.

When the PingOne SCIM API returns a list of results, it returns no more than 200 resources, and it does not page results. In other words, there is no way to see the remainder of the results. This is due to a conflict between the way the RFC describes pagination (with index-based pagination) and the way PingOne implements pagination in the PingOne API (with cursor-based pagination).

The PingOne SCIM API supports query parameters when retrieving users. However, the service does not support these query parameters defined by the SCIM specification:

  • sortBy

  • sortOrder

  • startIndex

Atypical behavior

The PingOne SCIM API provides an additional user resource type called a "direct-mapped user". This can be used on its own endpoint (/DirectMappedUsers) and provides a mechanism for making SCIM calls without the need for a SCIM resource mapping. Refer to Direct-mapped Users for more information.

Some of the default SCIM attributes are not necessarily relevant to PingOne, so they are not supported, such as x509Certificates. These attributes have been listed in a later section.

Telephone numbers provided by clients are not forced to comply with RFC 3966. The service does not force them to be in the format 1-512-123-4567. Instead, telephone numbers are routed to PingOne as submitted.

SCIM attributes defined in the specification

According to Section 2.3 of RFC 7643, the type of an attribute may be one of:

  • String

  • Boolean

  • Decimal

  • Integer

  • DateTime

  • Binary

  • Reference

  • Complex

The PingOne SCIM API’s primary user type on the /v2/Users endpoint is an extension of the one described in the SCIM specification, but is mostly the same. The following Description column describes the relationship between SCIM attributes and its equivalent in the PingOne API, if applicable. It also provides a very brief summary of the purpose of each SCIM attribute. For more details, refer to sections 3.1 and 4.1.1, and 4.1.2 of RFC 7643.

Field Type PingOne API equivalent Description

schemas

String

None

An array of Strings that indicates the SCIM schemas. Duplicate values MUST NOT be included.

id

String

id

A unique identifier for a SCIM resource. This attribute is always returned by the SCIM API, and is equivalent to the id value in the PingOne API.

externalId

String

externalId

An optional identifier for the resource, assigned and used by the provisioning client.

meta

Object

No equivalent

This information is assembled by the PingOne SCIM API itself. All sub-attributes have a mutability of readOnly. This attribute should be ignored when it is provided by clients.

meta.resourceType

String

None

Indicates the type of the SCIM resource, such as User or Group.

meta.created

DateTime

createdAt

The timestamp for when the resource was created.

meta.lastModified

DateTime

updatedAt

The timestamp for when the resource was last updated.

meta.location

String

self.href

A URI indicating the path to the SCIM resource.

userName

String

username

The username. This field is required when creating a user.

name

Object

name (Complex)

A JSON object containing components of a user’s name.

name.formatted

String

name.formatted

The user’s full name.

name.familyName

String

name.family

The user’s family name.

name.givenName

String

name.given

The user’s given name.

name.middleName

String

name.middle

The user’s middle name.

name.honorificPrefix

String

name.honorificPrefix

A user’s title. For example, Mr, Ms, Sir.

name.honorificSuffix

String

name.honorificSuffix

The user’s suffix, such as Jr or III.

nickName

String

nickname

The nickname of the user. This value should not be used to represent a user’s username.

title

String

title

The title of the user, such as Vice President or Director.

preferredLanguage

String

preferredLanguage

Helps PingOne match language tags to a user’s language preferences. This is especially useful when processing interactions that are not directly initiated by the user.

locale

String

locale

Indicates the user’s default location, which helps localize information such as currency or date-time formats.

timezone

DateTime

timezone

The user’s time zone. This is set in IANA Time Zone database format.

active

Boolean

enabled

RFC 7644 declares that "[t]he definitive meaning of this attribute is determined by the service provider." In PingOne, this indicates whether the user is able to authenticate.

password

String

password

The password of the user. The PingOne SCIM API will never return this attribute under any circumstances or in any form, hashed or otherwise.

emails

Object

email (String)

The email addresses of the user. The PingOne SCIM API only allows a single value to be provided.

phoneNumbers

Object

primaryPhone (String)

The phone numbers of the user. The PingOne SCIM API only allows a single value to be provided.

photos

Object

photo (Complex)

A URI indicating the path to the user’s image. This must be a file (such as .gif, .jpg, .png) and cannot be a web page that contains the image. The PingOne SCIM API only allows a single value to be provided.

addresses

Object

address (Complex)

A JSON object that contains a set of data pertaining to the user’s address. The PingOne SCIM API only allows a single value to be provided.

addresses.formatted

String

None

The full mailing address, formatted for display or use with a mailing label. The RFC allows this attribute to contain newlines.

addresses.streetAddress

String

address.streetAddress

The full street address. This may include house number, street name, Post Office box. The RFC allows this attribute to contain newlines.

addresses.locality

String

address.locality

The city or locality.

addresses.region

String

address.region

The state or region.

addresses.postalCode

String

address.postalCode

The ZIP Code or postal code.

addresses.country

String

address.countryCode

The name of the country. This MUST be in ISO 3166-1 alpha-2 code format, such as US or SE.

Additional attributes accepted by the PingOne SCIM API

This section defines attributes that are not in the SCIM specification, but are allowed (and sometimes required) to be included in SCIM API calls to PingOne. These attributes are defined in the extension schema, urn:pingidentity:schemas:extension:2.0:PingOneUser, allowing clients to provide data custom to PingOne via the /Users endpoint without causing interoperability issues with other SCIM clients.

Field Type PingOne API equivalent Description

population

Object

population

A UUID representing the population of a resource. This is required for POST operations only when the environment does not have a default population defined.

SCIM attributes not supported by PingOne SCIM API

Some of the default attributes in the SCIM specification do not apply to the PingOne solution. These have been listed below. As per the SCIM specification, modifications involving these attributes will be ignored. This behavior is consistent with how invalid attributes are handled by both SCIM and the PingOne API.

Field Type Description

groups

Object

Support for groups is pending.

meta.version

String

The version of the resource. This is essentially the SCIM version of an HTTP ETag, which is not supported in PingOne. Hence, the PingOne SCIM API does not return this attribute.

displayName

String

The user’s name in a "displayable" form for an application. This field is not required.

profileUrl

String

A URI indicating the path to a user’s online profile. PingOne does not have an equivalent attribute for this purpose.

userType

String

Identifies the relationship between the organization and the user, such as Contractor, Employee, Manager.

ims

Object

Instant messaging address. PingOne does not have an equivalent attribute for this purpose.

entitlements

Object

This attribute represents the user’s ownership or right to certain objects.

roles

Object

This attribute generally contains a list of roles for the user that "collectively represent who the user is" (citation: RFC 7643).

x509Certificates

Object

Represents a list of certificates that are associated with a resource.

PingOne SCIM API contracts

For an example environment with an identifier of fa1afe1, the main structure of the SCIM endpoints in PingOne are URIs in the form: https://scim-api.pingone.com/environments/fa1afe1/v2/Users.

These are main endpoints used by the PingOne SCIM API:

  • /v2/Users

  • /v2/DirectMappedUsers

  • /v2/ResourceTypes

  • /v2/Schemas

  • /v2/ServiceProviderConfig

These endpoints are typical for the SCIM standard but are not supported. Sending requests to these endpoints will result in an HTTP 501 (Not Implemented) response.

  • /v2

  • /v2/Bulk

  • /v2/Groups

  • /v2/Me

SCIM users and populations

PingOne environments have a construct called populations that allow administrators to separate and maintain different types of users in the same environment. In PingOne, every user is associated with a population. As a result, PingOne must know in which population the user should be placed. To provide this information directly when creating a SCIM user (via /Users endpoint), this can be done by including the data with the extension schema:

"urn:pingidentity:schemas:extension:2.0:PingOneUser": {
   "population": {
      "id": "5980c790-24c3-4fc6-8144-3d634abdda3a"
   }
}

A direct-mapped user can specify this information directly, just like the behavior of the PingOne API. Thus, it does not use an extension schema:

"population": {
   "id": "5980c790-24c3-4fc6-8144-3d634abdda3a"
}

However, when a default population is defined in the PingOne environment (refer to default in Populations data model), a population is not required to be explicitly declared. By convention, if any request comes to PingOne that does not explicitly declare the population to use by default, then the user will be created in the default population. Otherwise, a population must be included in the JSON body of the request because PingOne must know with which population the user is associated.

Lists of SCIM resources

When multiple SCIM resources are returned in a single response, RFC 7644 states that it must be in the form of a ListResponse object. The RFC also states that pagination should be performed with a page-based implementation, but PingOne only supports cursor-based pagination. The main difference between the two is that page-based pagination requires that the client provide an index parameter, whereas cursor-based pagination provides a next link that can be used to receive the next page of resources.

From a technical perspective, implementing page-based pagination is not feasible in the PingOne SCIM API when the underlying PingOne architecture uses a cursor-based approach. For this reason, the PingOne SCIM API does not support paging, but instead will return up to 200 results. If more than 200 results are available, the true number of results will be available in totalResults.