--- title: Identity Provider Management description: Explains PingOne external identity provider configuration, attribute mapping rules, placeholder syntax, and JSON attribute construction for social and SAML login component: pingone-api page_id: pingone-api:platform:identity-provider-management/index canonical_url: https://developer.pingidentity.com/pingone-api/platform/identity-provider-management/index.html llms_txt: https://developer.pingidentity.com/pingone-api/llms.txt docs_for_agents: https://developer.pingidentity.com/build-with-ai/docs-for-agents.md revdate: 2026-08-11 section_ids: attribute-mapping-rules: Attribute mapping rules attribute-placeholder-syntax: Attribute placeholder syntax mapping-to-json-attributes: Mapping to JSON attributes constructing-json-objects: Constructing JSON objects account-linking: Account linking assigning-admin-roles-and-permissions-to-this-service: Assigning admin roles and permissions to this service base-idp-data-model: Base IdP data model mapping-attributes-data-model: Mapping attributes data model attribute-type-mapping-rules: Attribute type mapping rules identity-provider-events-generated: Identity provider events generated response-codes: Response codes --- # 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.}` 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.` 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: `{"": providerAttributes.}` * To construct an array of multiple JSON objects (for a multi-valued attribute), separate the objects with commas and wrap them in outer braces: `{{"": providerAttributes.}, {"": providerAttributes.}}` > **Collapse: Example: SAML attribute mapped to a single-valued JSON attribute** > > Given these inbound SAML attributes: > > ```xml > > jsmith@example.com > > > CN=AR,OU=People,DC=example,DC=com > CN=AP,OU=People,DC=example,DC=com > > ``` > > The following expression maps both attributes to a single-valued JSON attribute: > > `{"mail-in-JSON": providerAttributes.mail, "groupInfo-in-JSON": providerAttributes.groupInfo}` > > Result: > > ```json > { > "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](https://docs.pingidentity.com/pingone/integrations/p1_external_idps.html) 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](../reference/roles-and-permissions-in-pingone/permissions-by-service.html) for the service-specific permissions. You can also choose to assign admin roles based on particular service resources. Refer to [PingOne Permissions by Resource](../reference/roles-and-permissions-in-pingone/permissions-by-resource.html) when assigning admin roles per service resources. Admin assignments to roles are set by: * [Automatic assignment for some roles](../roles/predefined-roles/index.html#automatic-role-assignment). * [Group Role Assignments](../group-role-assignments/group-role-assignments.html). * [User Role Assignments](../users/user-role-assignments/index.html). Refer to [Roles Management](../roles/index.html) 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](https://docs.pingidentity.com/pingone/settings/p1_addcertificate.html). | | `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](../reference/audit-reporting-events.html) 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. |