PingOne Platform APIs

Identity Provider Management

The identity provider (IdP) endpoints manage external IdP configurations. These endpoints are part of a suite of services that enable social login, authoritative login, and inbound SAML login in PingOne. Configuring an external IdP allows users with linked accounts to authenticate and access PingOne resources using the login flows and credentials of their external provider.

Attribute mapping rules

PingOne supports various external IdPs. When configuring an IdP resource, you define the provider type and map user attributes from the external IdP to PingOne user attributes.

Because attributes can contain one or multiple values, PingOne applies the following rules when resolving format differences:

  • Single-valued IdP to single-valued PingOne: The PingOne attribute mirrors the exact value of the IdP attribute.

  • Multi-valued IdP to multi-valued PingOne: The PingOne attribute becomes an array containing all the IdP attribute values.

  • Single-valued IdP to multi-valued PingOne: The PingOne attribute becomes a single-element array containing the IdP attribute value.

  • Multi-valued IdP to single-valued PingOne: The PingOne attribute uses only the first element from the multi-valued IdP attribute.

Attribute placeholder syntax

When defining mappings in the request body, you must use the following placeholder syntax:

${providerAttributes.<IdP_attribute_name>}

If the inbound attribute name contains special characters (such as URLs commonly used by Microsoft), you must wrap the full attribute name in square brackets and single quotes. For example:

${providerAttributes.['http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress']}

Mapping to JSON attributes

You can also map inbound attributes to custom PingOne attributes of type JSON:

  • If the target PingOne attribute is JSON and single-valued, the attribute value is a single JSON object.

  • If the target PingOne attribute is JSON and multi-valued, the attribute value is an array of one or more JSON objects.

Constructing JSON objects

  • For OIDC IdPs, you can use the simple providerAttributes.<name> path when mapping a single IdP attribute to a JSON attribute.

  • For SAML IdPs, or when constructing a JSON object from multiple attributes, you must use an expression.

    • To construct a single JSON object:

      {"<key>": providerAttributes.<attr>}

    • To construct an array of multiple JSON objects (for a multi-valued attribute), separate the objects with commas and wrap them in outer braces:

      {{"<key1>": providerAttributes.<attr1>}, {"<key2>": providerAttributes.<attr2>}}

Example: SAML attribute mapped to a single-valued JSON attribute

Given these inbound SAML attributes:

<Attribute Name="mail">
  <AttributeValue>jsmith@example.com</AttributeValue>
</Attribute>
<Attribute Name="groupInfo">
  <AttributeValue>CN=AR,OU=People,DC=example,DC=com</AttributeValue>
  <AttributeValue>CN=AP,OU=People,DC=example,DC=com</AttributeValue>
</Attribute>

The following expression maps both attributes to a single-valued JSON attribute:

{"mail-in-JSON": providerAttributes.mail, "groupInfo-in-JSON": providerAttributes.groupInfo}

Result:

{
  "mail-in-JSON": "jsmith@example.com",
  "groupInfo-in-JSON": [
    "CN=AR,OU=People,DC=example,DC=com",
    "CN=AP,OU=People,DC=example,DC=com"
  ]
}

Account linking

PingOne cannot guarantee that usernames are unique for all external IdPs. To prevent users from different IdPs being treated as the same PingOne user, PingOne uses account linking. The user must have a PingOne account. When the user signs in to PingOne, an account link between the external IdP user account and their PingOne account is created.

Account linking only applies when the user’s authoritative IdP is PingOne. Account linking is not supported when the authoritative IdP is an external IdP rather than PingOne. In this case, account linking will fail. For a user to link their account with multiple external IdPs, their authoritative IdP must be set to PingOne.

For more information about identity providers, refer to External IDPs in the PingOne Admin documentation.

Assigning admin roles and permissions to this service

Admin role assignments determine access to PingOne APIs. When assigning admin roles to this service, refer to PingOne Permissions by Service for the service-specific permissions.

You can also choose to assign admin roles based on particular service resources. Refer to PingOne Permissions by Resource when assigning admin roles per service resources.

Admin assignments to roles are set by:

Refer to Roles Management for more information.

Base IdP data model

Property Type Required Mutable Description

description

String

Optional

Mutable

The description of the IdP.

enabled

String

Required

Mutable

The current enabled state of the IdP. Options are ENABLED or DISABLED.

environment.id

String

Required

Immutable

The environment associated with the IdP resource.

icon.id

String

Optional

Mutable

The ID for the IdP icon.

icon.href

String

Optional

Mutable

The HREF for the IdP icon.

id

String

Required

Immutable

The resource ID.

loginButtonIcon.id

String

Optional

Mutable

The image ID for the IdP login button icon. For Facebook, Google, and LinkedIn IdPs, updates to the login button are ignored to preserve the IdP branding rules.

loginButtonIcon.href

String

Optional

Mutable

The HREF for the IdP login button icon image file. For Facebook, Google, and LinkedIn IdPs, updates to the login button are ignored to preserve the IdP branding rules.

name

String

Required

Mutable

The name of the IdP.

pkceMethod

String

Optional

Mutable

The method for PKCE. Options are NONE or S256. The default is NONE. This value auto-populates from a discovery endpoint if the OpenID Provider includes S256 in its code_challenge_methods_supported claim. The plain method is not currently supported.

registration.population.id

Object

Optional

Mutable

An external IdP to use as authoritative. Setting this attribute gives management of linked users to the IdP and also triggers just-in-time provisioning of new users. These users are created in the population indicated with registration.population.id.

sloBinding

String

Optional

Mutable

The binding protocol to be used for the logout response. Options are HTTP_REDIRECT or HTTP_POST. The default is HTTP_POST; existing configurations with no data default to HTTP_POST. This is an optional property.

sloEndpoint

String

Optional

Mutable

The logout endpoint URL. This is an optional property. However, if a sloEndpoint logout endpoint URL is not defined, logout actions result in an error.

sloResponseEndpoint

String

Optional

Mutable

The endpoint URL to submit the logout response. If a value is not provided, the sloEndpoint property value is used to submit SLO response.

sloWindow

Integer

Optional

Mutable

Defines how long PingOne can exchange logout messages with the application, specifically a LogoutRequest from the application, since the initial request. PingOne can also send a LogoutRequest to the application when a single logout is initiated by the user from other session participants, such as an application or identity provider. This setting is per application. The SLO logout is separate from the user session logout that revokes all tokens.

spSigning.algorithm

String

Optional

Mutable

The signing key algorithm used by PingOne. Value will depend on which key algorithm and signature algorithm you chose when creating your signing key. Possible values are SHA256withRSA, SHA384withRSA, SHA512withRSA, SHA256withECDSA, SHA384withECDSA, SHA512eithEDCSA.

spSigning.key.id

String

Optional

Read-only

The UUID of the signing key. Refer to Adding a Certificate and Key Pair.

type

String

Required

Immutable

The IdP type. This is a required property. Options are FACEBOOK, GOOGLE, LINKEDIN_OIDC, LINKEDIN (Deprecated), OPENID_CONNECT, APPLE, AMAZON, TWITTER, YAHOO, PAYPAL, MICROSOFT, GITHUB, and SAML.

Mapping attributes data model

Property Type Required Mutable Description

mappingType

String

Optional

Immutable

The mapping type. Options are: CORE (This attribute is required by the schema and cannot be removed. The name and update properties cannot be changed.) or CUSTOM (All user-created attributes are of this type.)

name

String

Required

Mutable

The user attribute, which is unique per provider. The attribute must not be defined as read only from the user schema or of type COMPLEX based on the user schema. Valid examples: username, and name.first. The following attributes may not be used: account, id, created, updated, lifecycle, mfaEnabled, and enabled.

value

String

Required

Mutable

A placeholder referring to the attribute (or attributes) from the provider. Placeholders must be valid for the attributes returned by the IdP type and use the ${} syntax (for example, username="${email}"). For SAML, any placeholder is acceptable, and it is mapped against the attributes available in the SAML assertion after authentication. The ${samlAssertion.subject} placeholder is a special reserved placeholder used to refer to the subject name ID in the SAML assertion response.

update

String

Required

Mutable

Indicates whether to update the user attribute in the directory with the non-empty mapped value from the IdP. Options are: EMPTY_ONLY (only update the user attribute if it has an empty value); ALWAYS (always update the user attribute value).

Attribute type mapping rules

User attribute type Provider JSON value type Result

String

*

Valid. The value is cast at runtime, as necessary.

Complex

*

Error

Boolean

Boolean

Valid

Boolean

*

Error

JSON

Object

Valid

JSON

*

Error

JSON (sub-attribute)

*

Valid

Identity provider events generated

Refer to Audit Reporting Events for the events generated.

Response codes

Code Message

200

Successful operation.

201

Successfully created.

204

Successfully removed. No content.

400

The request could not be completed.

401

You do not have access to this resource.

403

You do not have permissions or are not licensed to make this request.

404

The requested resource was not found.

500

An unexpected error occurred.

Identity provider errors

In addition to the general error codes, identity provider operations can return the following errors:

HTTP status Top‑level code Detail code When it happens and what the response contains

400

INVALID_DATA

EMPTY_VALUE or INVALID_VALUE

Message: Validation Error : [<field> <message>]

When and details

When: A POST or PUT request omits or leaves blank a required property (name or enabled), or sets enabled to a value other than true or false

Details: Describes the failing property, such as name must not be blank for an omitted or blank name, or enabled must be a valid boolean value 'true' or 'false' for an invalid enabled value, for example Validation Error : [enabled must be a valid boolean value 'true' or 'false']

400

INVALID_DATA

EMPTY_VALUE or INVALID_VALUE

Message: Validation Error : [type must not be empty] for an omitted or empty value, or Validation Error : ['<type>' is not a valid type. type must be one of [<supportedTypes>]] for an unsupported value.

When and details

When: A POST or PUT request omits type or supplies a provider type the service does not support

Details: must not be empty or must be one of [<supportedTypes>]

400

INVALID_DATA

None

Message: Identity Provider Type <type> is not supported yet.

When and details

When: A POST or PUT request supplies a provider type that is valid but not enabled for the environment (feature‑flag controlled)

Details: None.

400

INVALID_DATA

INVALID_VALUE

Message: Property 'type' is immutable and cannot be changed for Identity Provider '<idpID>' in environment '<envID>'

When and details

When: A PUT request attempts to change the provider’s type

Details: property cannot be changed

400

INVALID_DATA

INVALID_VALUE

Message: Cannot find registration population with the id <populationID> for the environment <envID>

When and details

When: A POST or PUT request sets registration.population.id to a population that does not exist in the environment

Details: The population does not exist.

400

INVALID_DATA

UNIQUENESS_VIOLATION

Message: Identity Provider name '<name>' already exists in environment '<envID>' for provider '<existingID>'

When and details

When: A POST or PUT request supplies a provider name that already exists in the environment

Details: name already exists

400

INVALID_DATA

UNIQUENESS_VIOLATION

Message:

Identity Provider PingOne(sp) entity id '<spEntityId>' already exists in environment '<envID>' for provider '<existingID>'
When and details

When: A POST or PUT request supplies a SAML spEntityId that is already assigned to another provider in the environment

Details: PingOne(sp) entity id already exists

400

REQUEST_FAILED

CONSTRAINT_VIOLATION

Message: The request could not be completed. There was an issue processing the request.

When and details

When: A POST request would exceed the environment’s identity provider limit

Details: Environments cannot have more than <limit> identity providers.

400

REQUEST_FAILED

CONSTRAINT_VIOLATION

Message: The request could not be completed. There was an issue processing the request.

When and details

When: A POST attribute request would exceed the identity provider attribute limit (100 by default)

Details: Identity providers cannot have more than <limit> attributes.

400

REQUEST_FAILED

INVALID_PARAMETER

Message: The request could not be completed. There was an issue processing the request.

When and details

When: A GET request sets limit outside the supported range for the environment, or supplies an invalid cursor value

Details: Must be between 1 and <maximumLimit> or Invalid cursor parameter value

400

INVALID_REQUEST

None

Message: The request could not be completed. One or more validation errors were in the request.

When and details

When: A path identifier cannot be parsed as a UUID

Details: None.

400

INVALID_REQUEST

INVALID_VALUE or None

Message: The request could not be completed. The request was malformed or invalid.

When and details

When: The request body cannot be deserialized

Details: For a JSON field conversion error, the target is the field path. Otherwise no detail is returned.

400

INVALID_DATA

INVALID_VALUE

Message: The request could not be completed. One or more validation errors were in the request.

When and details

When: A POST or PUT attribute request maps a user attribute that is not supported for the provider, is read only or disabled in the user schema, or supplies a placeholder or expression that fails the attribute mapping rules

Details: Supported attribute names for the <idpType> Idp <idpID> [<idpName>] in environment <envID> does not include the user attribute '<attributeName>'. Only valid mutable user attributes are allowed. with target name, Cannot map attribute for the <idpType> Idp <idpID> [<idpName>] in environment <envID> because the attribute value '<value>' is invalid, Cannot map attribute for the <idpType> Idp <idpID> [<idpName>] in environment <envID> because the attribute '<attributeName>' is read only, Cannot map attribute for the <idpType> Idp <idpID> [<idpName>] in environment <envID> because the attribute '<attributeName>' is disabled, Cannot map attribute for the <idpType> Idp <idpID> [<idpName>] in environment <envID> because the source attribute '<sourceAttribute>' is invalid, or Cannot map attribute for the <idpType> Idp <idpID> [<idpName>] in environment <envID> because the expression '<expression>' is invalid, with targets value or name depending on the failure

400

INVALID_DATA

INVALID_VALUE

Message: The request could not be completed. One or more validation errors were in the request.

When and details

When: An attribute mapping targets a unique user attribute and sets update to a value other than EMPTY_ONLY

Details:

Attribute update type for the <idpType> Idp <idpID> [<idpName>] in environment <envID> can only by 'EMPTY_ONLY' as the attribute '<attributeName>' is unique

with target update

400

INVALID_DATA

INVALID_VALUE

Message: The request could not be completed. One or more validation errors were in the request.

When and details

When: A PUT attribute request changes the name or update property of a CORE (schema‑reserved) attribute

Details:

Property '<propertyName>' is immutable and cannot be changed in 'CORE' attribute '<attributeID>' for Identity Provider '<idpID>' within environment '<envID>'

400

INVALID_DATA

UNIQUENESS_VIOLATION

Message: The request could not be completed. One or more validation errors were in the request.

When and details

When: A POST or PUT attribute request supplies a name that already exists on the identity provider

Details:

Attribute name '<name>' already exists within Identity Provider '<idpID>' in environment '<envID>' for attribute '<existingAttributeID>'

400

REQUEST_FAILED

CONSTRAINT_VIOLATION

Message: Cannot Delete Attribute '<attributeName>' with 'CORE' mapping type in environment <envID> for Identity Provider <idpID>

When and details

When: A DELETE attribute request targets a CORE (schema‑reserved) attribute

Details: operation not supported

403

ACCESS_FAILED

None

Message: The actor attempting to perform the request is not authorized.

When and details

When: The actor lacks the identityProviders:create:identityProvider permission (identity provider POST operations), the identityProviders:read:identityProvider permission (GET operations), the identityProviders:update:identityProvider permission (identity provider PUT operations and all identity provider attribute write operations), or the identityProviders:delete:identityProvider permission (identity provider DELETE operations)

Details: None.

404

NOT_FOUND

INVALID_VALUE

Message: The request could not be completed. The requested resource was not found.

When and details

When: A GET, PUT, or DELETE request references an identity provider that does not exist in the environment

Details: Unable to find Identity Provider with ID: '<idpID>' in Environment '<envID>'

404

NOT_FOUND

INVALID_VALUE

Message: The request could not be completed. The requested resource was not found.

When and details

When: A GET, PUT, or DELETE attribute request references an attribute that does not exist for the identity provider

Details: Unable to find Attribute with ID: '<attributeID>' for Identity Provider '<idpID>' in Environment '<envID>'

500

UNEXPECTED_ERROR

None

Message: Describes the underlying failure.

When and details

When: The service encounters an internal error while processing the request

Details: None.