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.