Identity providers


Identity provider management

Identity provider resources link users who are authenticated through an external identity provider (like Facebook) to PingOne for Customers. These mappings enable linked users to authenticate and gain access to PingOne resources using the login flow and credentials provided by the external identity provider.

PingOne for Customers supports Facebook and SAML as external identity providers. PingOne identity provider resources include a value property that contains a placeholder that references the user attribute (or attributes) from the external identity provider that are mapped to PingOne user attributes.

When Facebook is specified as the the external identity provider, the placeholder value must use the following syntax and specify Facebook’s email attribute:

<PingOneUserAttribute>="${email}"

When SAML is specified as the the external identity provider, any SAML attribute used as the placeholder is acceptable. Note that the ${saml_subject} attribute is a special reserved placeholder to refer to the subject name ID in the SAML response. The placeholder value must use the following syntax:

<PingOneUserAttribute>="${placeholder}"

In these examples, the <PingOneUserAttribute> variable represents any searchable PingOne user attribute. such as username, name.family, name.given, email, phone, or population.id.

Identity provider API operations

The identity provider endpoints support the following operations:

For hands-on experience with the identity provider management API endpoints, click the Run in Postman button below to download a Postman collection that you can import and open in your local Postman application.

Identity provider data model

Property Description
accountLinking.filter A string that specifies the SCIM filter that is used to locate a matching user to create the link. The filter can contain placeholders that reference attributes that can be returned by the provider in ${} format.
description A string that specifies the description of the identity provider.
enabled A string that specifies the current enabled state of the identity provider. Options are ENABLED or DISABLED.
environment.id A string that specifies the environment associated with the identity provider resource.
icon.id The ID for the identity provider icon.
icon.href The HREF for the identity provider icon.
id A string that specifies the resource ID.
name A string that specifies the name of the identity provider. This is a required property.
type A string that specifies the identity provider type. This is a required property. Options are FACEBOOK and SAML.

Facebook settings data model

Property Description
appId A string that specifies the application ID from Facebook. This is a required property.
appSecret A string that specifies the application secret from Facebook. This is a required property.
permissions An array that specifies permissions (scopes) to request from Facebook in addition to the standard permissions. Options include USER_AGE_RANGE, USER_BIRTHDAY, and USER_GENDER.

SAML settings data model

Property Description
acsBinding A string that specifies the binding to use for the inbound response.
assertionVerification.cert.id A string that specifies the configuration for assertion signature verification.
assertionVerification.algorithm A string that specifies the assertion verification algorithm.
idpEntityId A string that specifies the entity ID URI that is checked against the issuerId tag in the incoming response.
requestSigning.key.id A string that specifies the configuration for assertion signature verification.
requestSigning.algorithm A string that specifies the request signing algorithm.
responseVerification.cert.id A string that specifies the configuration for assertion signature verification.
responseVerification.algorithm A string that specifies the response verification algorithm.
assertionVerificationCert A string that specifies the HREF to the assertion verification cert resource.
name A string that specifies the name of SAML attribute and must be unique within an application. The saml_subject name is a reserved case-insensitive name which indicates the mapping to be used for the subject in an assertion. This is a required property.
spEntityId A string that specifies the service provider’s entity ID.
ssoBinding A string that specifies the binding to use for the outbound request.
ssoEndpoint A string that specifies the SSO endpoint to send the outbound request.

Identity provider attributes data model

Property Description
name A string that specifies the user attribute, which is unique per provider. The attribute must not be defined as read only from the user schema.
update A string that specifies the Whether to update the user attribute in the directory with the non-empty mapped value from the identity provider. Options are: EMPTY_ONLY (Only update the user attribute if it has an empty value); ONCE_ONLY (Only update the user attribute on initial linking and if it has an empty value); ALWAYS (Always update the user attribute value).
value A string that specifies placeholder referring to the attribute(or attributes) from the provider. Placeholders must be valid for the attributes returned by the identity provider type and use the ${} syntax (for example, username="${saml_subject}").

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.

Endpoint examples

Get identity providers

The GET /environments/{environmentId}/identityProviders endpoint returns a list of all identity provider resources for the specified environment resource.

curl -X "GET" "https://api.pingone.com/v1/environments/{environmentId}/identityProviders" \
-H 'Authorization: Bearer jwtToken'

The response data looks like this:

{
    "_links": {
        "self": {
            "href": "https://api.pingone.com/v1/environments/88c23def-39c9-4646-8d41-aa91a14a1006/identityProviders"
        }
    },
    "_embedded": {
        "identityProviders": [
            {
                "_links": {
                    "self": {
                        "href": "https://api.pingone.com/v1/environments/88c23def-39c9-4646-8d41-aa91a14a1006/identityProviders/3425af27-cf3a-4bbd-ab15-f0f8323b54a8"
                    },
                    "environment": {
                        "href": "https://api.pingone.com/v1/environments/88c23def-39c9-4646-8d41-aa91a14a1006"
                    },
                    "attributes": {
                        "href": "https://api.pingone.com/v1/environments/88c23def-39c9-4646-8d41-aa91a14a1006/identityProviders/3425af27-cf3a-4bbd-ab15-f0f8323b54a8/attributes"
                    }
                },
                "name": "SocialMediaExtIdProvider",
                "description": "Social media identity provider.",
                "enabled": true,
                "type": "FACEBOOK",
                "environment": {
                    "id": "88c23def-39c9-4646-8d41-aa91a14a1006"
                },
                "id": "3425af27-cf3a-4bbd-ab15-f0f8323b54a8",
                "createdAt": "2019-03-25T19:44:42.394Z",
                "updatedAt": "2019-03-25T19:44:42.394Z",
                "appSecret": "FBSecret",
                "appId": "FBID"
            },
            {
                "_links": {
                    "self": {
                        "href": "https://api.pingone.com/v1/environments/88c23def-39c9-4646-8d41-aa91a14a1006/identityProviders/d8656e57-a061-4729-8d77-c8c1210bae62"
                    },
                    "environment": {
                        "href": "https://api.pingone.com/v1/environments/88c23def-39c9-4646-8d41-aa91a14a1006"
                    },
                    "attributes": {
                        "href": "https://api.pingone.com/v1/environments/88c23def-39c9-4646-8d41-aa91a14a1006/identityProviders/d8656e57-a061-4729-8d77-c8c1210bae62/attributes"
                    }
                },
                "name": "SAMLAPPExtIdProvider",
                "description": "SAML identity provider.",
                "enabled": true,
                "type": "SAML",
                "environment": {
                    "id": "88c23def-39c9-4646-8d41-aa91a14a1006"
                },
                "id": "d8656e57-a061-4729-8d77-c8c1210bae62",
                "createdAt": "2019-03-25T19:48:19.572Z",
                "updatedAt": "2019-03-25T19:48:19.572Z"
            }
        ]
    },
    "size": 2
}

Get one identity provider

To get data for a single identity provider resource, the GET /environments/{environmentId}/identityProviders/{providerId} operation returns data only for the identity provider resource with the specified ID.

curl -X GET "https://api.pingone.com/v1/environments/{environmentId}/identityProviders/{providerId}" \
-H "Authorization: Bearer jwtToken"

The response data looks like this:

{
    "_links": {
        "self": {
            "href": "https://api.pingone.com/v1/environments/88c23def-39c9-4646-8d41-aa91a14a1006/identityProviders/41bc4ed0-41fa-4a2e-ba87-67b6c66fae92"
        },
        "environment": {
            "href": "https://api.pingone.com/v1/environments/88c23def-39c9-4646-8d41-aa91a14a1006"
        },
        "attributes": {
            "href": "https://api.pingone.com/v1/environments/88c23def-39c9-4646-8d41-aa91a14a1006/identityProviders/41bc4ed0-41fa-4a2e-ba87-67b6c66fae92/attributes"
        }
    },
    "name": "FacebookIdP",
    "enabled": true,
    "type": "FACEBOOK",
    "icon": {
        "id": "9765e2ec-f958-4a20-a178-3ba5f54d6477",
        "href": "https://upload.wikimedia.org/wikipedia/commons/thumb/9/96/Oxygen-user-identity-female.svg/128px-Oxygen-user-identity-female.svg.png"
    },
    "environment": {
        "id": "88c23def-39c9-4646-8d41-aa91a14a1006"
    },
    "id": "41bc4ed0-41fa-4a2e-ba87-67b6c66fae92",
    "createdAt": "2019-03-27T18:25:14.565Z",
    "updatedAt": "2019-03-27T18:25:14.565Z",
    "appSecret": "FBSecret",
    "appId": "FBID"
}

Add identity providers

The POST /environments/{environmentId}/identityProviders operation adds a new identity provider resource to the specified environment.

curl -X "POST" "https://api.pingone.com/v1/environments/{environmentId}/identityProviders" \
-H 'Content-type: application/json' \
-H 'Authorization: Bearer jwtToken' \
-d '{
  "name": "SAMLExtIdProvider",
  "description": "SAML identity provider.",
  "enabled": true,
  "type": "SAML",

}'

The response data looks like this:

{
    "_links": {
        "self": {
            "href": "https://api.pingone.com/v1/environments/88c23def-39c9-4646-8d41-aa91a14a1006/identityProviders/3425af27-cf3a-4bbd-ab15-f0f8323b54a8"
        },
        "environment": {
            "href": "https://api.pingone.com/v1/environments/88c23def-39c9-4646-8d41-aa91a14a1006"
        },
        "attributes": {
            "href": "https://api.pingone.com/v1/environments/88c23def-39c9-4646-8d41-aa91a14a1006/identityProviders/3425af27-cf3a-4bbd-ab15-f0f8323b54a8/attributes"
        }
    },
    "name": "ExtIdProvider",
    "description": "Social media identity provider.",
    "enabled": true,
    "type": "SAML",
    "environment": {
        "id": "88c23def-39c9-4646-8d41-aa91a14a1006"
    },
    "id": "3425af27-cf3a-4bbd-ab15-f0f8323b54a8",
    "createdAt": "2019-03-25T19:44:42.394Z",
    "updatedAt": "2019-03-25T19:44:42.394Z"
}

When the type property value is set to FACEBOOK, Facebook’s appId and appSecret property values are required in the request body. The following sample shows the request with the type property set to FACEBOOK.

curl -X "POST" "https://api.pingone.com/v1/environments/{environmentId}/identityProviders" \
-H 'Content-type: application/json' \
-H 'Authorization: Bearer jwtToken' \
-d '{
    "#accountLinking": {
        "filter": "SCIM filter for matching to a User"
    },
    "description": "Custom Facebook ID Provider",
    "enabled": true,
    "icon": {
        "id": "9765e2ec-f958-4a20-a178-3ba5f54d6477",
        "href": "https://images.org/andre.svg.png"
    },
    "name": "FacebookIdP",
    "type": "FACEBOOK",
    "appId": "FacebookAppID",
    "appSecret": "FacebookAppSecret",
    "#permissions": [
        "USER_AGE_RANGE",
        "USER_BIRTHDAY",
        "USER_GENDER",
        "EMAIL"
    ]
}'

The response data looks like this:

{
    "_links": {
        "self": {
            "href": "https://api.pingone.com/v1/environments/88c23def-39c9-4646-8d41-aa91a14a1006/identityProviders/4d8ee244-b4cb-4dc9-9cd5-3e3728ab6d59"
        },
        "environment": {
            "href": "https://api.pingone.com/v1/environments/88c23def-39c9-4646-8d41-aa91a14a1006"
        },
        "attributes": {
            "href": "https://api.pingone.com/v1/environments/88c23def-39c9-4646-8d41-aa91a14a1006/identityProviders/4d8ee244-b4cb-4dc9-9cd5-3e3728ab6d59/attributes"
        }
    },
    "name": "FacebookIdP2",
    "description": "Custom Facebook ID Provider",
    "enabled": true,
    "type": "FACEBOOK",
    "icon": {
        "id": "9765e2ec-f958-4a20-a178-3ba5f54d6477",
        "href": "https://upload.wikimedia.org/wikipedia/commons/thumb/9/96/Oxygen-user-identity-female.svg/128px-Oxygen-user-identity-female.svg.png"
    },
    "environment": {
        "id": "88c23def-39c9-4646-8d41-aa91a14a1006"
    },
    "id": "4d8ee244-b4cb-4dc9-9cd5-3e3728ab6d59",
    "createdAt": "2019-03-27T18:34:46.555Z",
    "updatedAt": "2019-03-27T18:34:46.555Z",
    "appSecret": "FBSecret",
    "appId": "FBID"
}

Update an identity provider

To update a property value associated with a selected identity provider resource, use the PUT /environments/{environmentId}/identityProviders/{providerId} operation to modify the specified attribute values. For example, you can change the description attribute value of the identity provider.

curl -X "PUT" "https://api.pingone.com/v1/environments/{environmentId}/identityProviders/{providerId}" \
-H 'Content-type: application/json' \
-H 'Authorization: Bearer jwtToken' \
-d '{
  "description": "My SAML application identity provider."
}'

Delete an identity provider

To delete an identity provider resource, you need to specify the environment ID and the identity provider resource ID in the request URL. The DELETE /environments/{environmentId}/applications/{applicationId} operation deletes the identified identity provider resource.

curl -X "DELETE" "https://api.pingone.com/v1/environments/{environmentId}/identityProviders/{providerId}" \
-H 'Authorization: Bearer jwtToken'

For successful delete operations, a 204 NO CONTENT message is returned by the request.

Get identity provider attributes

The GET /environments/{environmentId}/identityProviders/{providerId}/attributes endpoint returns a list of all identity provider attribute resources for the specified identity provider resource.

curl -X "GET" "https://api.pingone.com/v1/environments/{environmentId}/identityProviders/{providerId}/attributes" \
-H 'Authorization: Bearer jwtToken'

The response data looks like this:

{
    "_links": {
        "self": {
            "href": "https://api.pingone.com/v1/environments/88c23def-39c9-4646-8d41-aa91a14a1006/identityProviders/4d8ee244-b4cb-4dc9-9cd5-3e3728ab6d59/attributes"
        }
    },
    "_embedded": {
        "attributes": [
            {
                "_links": {
                    "self": {
                        "href": "https://api.pingone.com/v1/environments/88c23def-39c9-4646-8d41-aa91a14a1006/identityProviders/4d8ee244-b4cb-4dc9-9cd5-3e3728ab6d59/attributes/4611c151-3e27-4b72-9a06-bde1d7651ea5"
                    },
                    "identityProvider": {
                        "href": "https://api.pingone.com/v1/environments/88c23def-39c9-4646-8d41-aa91a14a1006/identityProviders/4d8ee244-b4cb-4dc9-9cd5-3e3728ab6d59"
                    }
                },
                "name": "name.first",
                "value": "${email}",
                "id": "4611c151-3e27-4b72-9a06-bde1d7651ea5",
                "environment": {
                    "id": "88c23def-39c9-4646-8d41-aa91a14a1006"
                },
                "identityProvider": {
                    "id": "4d8ee244-b4cb-4dc9-9cd5-3e3728ab6d59"
                },
                "createdAt": "2019-04-18T23:07:49.359Z",
                "updatedAt": "2019-04-18T23:07:49.359Z"
            },
            {
                "_links": {
                    "self": {
                        "href": "https://api.pingone.com/v1/environments/88c23def-39c9-4646-8d41-aa91a14a1006/identityProviders/4d8ee244-b4cb-4dc9-9cd5-3e3728ab6d59/attributes/c7843aca-9dd9-4541-b1e2-feb063e53188"
                    },
                    "identityProvider": {
                        "href": "https://api.pingone.com/v1/environments/88c23def-39c9-4646-8d41-aa91a14a1006/identityProviders/4d8ee244-b4cb-4dc9-9cd5-3e3728ab6d59"
                    }
                },
                "name": "username",
                "value": "${email}",
                "id": "c7843aca-9dd9-4541-b1e2-feb063e53188",
                "environment": {
                    "id": "88c23def-39c9-4646-8d41-aa91a14a1006"
                },
                "identityProvider": {
                    "id": "4d8ee244-b4cb-4dc9-9cd5-3e3728ab6d59"
                },
                "createdAt": "2019-04-18T23:02:44.955Z",
                "updatedAt": "2019-04-18T23:02:44.955Z"
            }
        ]
    },
    "size": 2
}

Get one identity provider attribute

To get data for a single identity provider attribute resource, the GET /environments/{environmentId}/identityProviders/{providerId}/attributes/{attributeId} operation returns data only for the identity provider attribute resource with the specified ID.

curl -X GET "https://api.pingone.com/v1/environments/{environmentId}/identityProviders/{providerId}/attributes/{attributeId}" \
-H "Authorization: Bearer jwtToken"

Add identity provider attributes

The POST /environments/{environmentId}/identityProviders/{providerId}/attributes operation adds a new identity provider attribute resource to the specified identity provider.

curl -X "POST" "https://api.pingone.com/v1/environments/{environmentId}/identityProviders/{providerId}/attributes" \
-H 'Content-type: application/json' \
-H 'Authorization: Bearer jwtToken' \
-d '{
  "name": "username",
  "value": "${email}",
}'

The response data looks like this:

{
    "_links": {
        "self": {
            "href": "https://api.pingone.com/v1/environments/88c23def-39c9-4646-8d41-aa91a14a1006/identityProviders/4d8ee244-b4cb-4dc9-9cd5-3e3728ab6d59/attributes/c7843aca-9dd9-4541-b1e2-feb063e53188"
        },
        "identityProvider": {
            "href": "https://api.pingone.com/v1/environments/88c23def-39c9-4646-8d41-aa91a14a1006/identityProviders/4d8ee244-b4cb-4dc9-9cd5-3e3728ab6d59"
        }
    },
    "name": "username",
    "value": "${email}",
    "id": "c7843aca-9dd9-4541-b1e2-feb063e53188",
    "environment": {
        "id": "88c23def-39c9-4646-8d41-aa91a14a1006"
    },
    "identityProvider": {
        "id": "4d8ee244-b4cb-4dc9-9cd5-3e3728ab6d59"
    },
    "createdAt": "2019-04-18T23:02:44.955Z",
    "updatedAt": "2019-04-18T23:02:44.955Z"
}

Update an identity provider attribute

To update a property value associated with a selected identity provider attribute resource, use the PUT /environments/{environmentId}/identityProviders/{providerId}/attributes/{attributeId} operation to modify the specified attribute values.

curl -X "PUT" "https://api.pingone.com/v1/environments/{environmentId}/identityProviders/{providerId}" \
-H 'Content-type: application/json' \
-H 'Authorization: Bearer jwtToken' \
-d '{
    "name": "name.first",
    "update": "EMPTY_ONLY",
    "value": "${first_name}"

}'

Delete an identity provider attribute

To delete an identity provider attribute resource, you need to specify the environment ID, the identity provider resource ID, and the attribute ID in the request URL. The DELETE /environments/{environmentId}/identityProviders/{providerId}/attributes/{attributeId} operation deletes the identified identity provider attribute resource.

curl -X "DELETE" "https://api.pingone.com/v1/environments/{environmentId}/identityProviders/{providerId}/attributes/{attributeId}" \
-H 'Authorization: Bearer jwtToken'

For successful delete operations, a 204 NO CONTENT message is returned by the request.