Identity Provider Management

The identity provider (IdP) endpoints manage external IdP configurations. It is one of several related services that enable the social login, authoritative login, and inbound SAML login features in PingOne. An external IdP configuration allows users whose accounts are linked to PingOne to authenticate and gain access to PingOne resources using the login flow and credentials provided by the external IdP.

PingOne supports several external IdPs. IdP resources in PingOne configure the external IdP settings, which include the type of provider and the user attributes from the external IdP that are mapped to PingOne user attributes. These attributes might have one or many values assigned to them. As you might expect, mapping a single-value IdP attribute to a single-value PingOne attribute results in a PingOne attribute having the same value as the IdP attribute. Similarly, if the IdP attribute is multi-valued, the PingOne attribute value will be an array of the IdP attribute values. If the attributes are not the same format, then the following rules apply:

If the IdP attribute is single-valued and the PingOne attribute is multi-valued, the PingOne attribute will be a single-element array containing the value of the IdP attribute.
If the IdP attribute is multi-valued and the PingOne attribute is single-value, then the PingOne attribute will use the first element in the IdP attribute as its value.

The mapping attribute placeholder value must be expressed using the following syntax in the request body:

${providerAttributes.<IdP attribute name>}

Attributes that contain special characters must use the syntax: ${providerAttributes.['<IdP attribute name>']}.

For example, Microsoft often provides attributes that contain special characters, often prefixed with http://. To map these attributes appropriately in PingOne, use square brackets and single quotes around the full attribute name. Such as, ${providerAttributes.['http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress']}.

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

Use cases

Base IdP data model

Property Type Required? Mutable? Description

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

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

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

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

User attribute type

Provider JSON value type

Result

String

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

Complex

Error

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.

PingOne Platform APIs

Identity Provider Management

Account linking

Use cases

Base IdP data model

Mapping attributes data model

Attribute type mapping rules

Identity provider events generated

Response codes