--- title: Identity Provider Management description: 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. component: pingone-api page_id: pingone-api:platform:identity-provider-management canonical_url: https://developer.pingidentity.com/pingone-api/platform/identity-provider-management.html section_ids: 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. 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.}` | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | | Attributes that contain special characters must use the syntax: `${providerAttributes.['']}`.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](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.html#automatic-role-assignment). * [Group Role Assignments](group-role-assignments/group-role-assignments.html). * [User Role Assignments](users/user-role-assignments.html). Refer to [Roles Management](roles.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. |