Activity - Configure Facebook as an identity provider


Introduction and workflow tasks

PingOne supports several external identity providers, including Facebook. A configuration in PingOne for Facebook as an identity provider allows users to authenticate and gain access to a configured application using the Facebook sign-on flow and their Facebook credentials.

This scenario illustrates the following common operations supported by the PingOne for Customers APIs:

  • Create an identity provider configuration
  • Create an optional identity provider attribute mapping
  • Create a sign-on policy
  • Create a sign-on policy action
  • Assign the sign-on policy to an application

Workflow order of operations

To create a sign-on policy that specifies Facebook as a supported external identity provider, the following tasks must be completed successfully:

  1. Make a POST request to /environments/{environmentId}/identityProviders to create the identity provider configuration for Facebook.

  2. Make a POST request to /environments/{environmentId}/identityProviders/{providerId}/attributes to map the Facebook email attributes to PingOne email attributes. This step is optional.

  3. Make a POST request to /environments/{environmentId}/signOnPolicies to create a new sign-on policy.

  4. Make a POST request to /environments/{environmentId}/signOnPolicies/{policyId}/actions to create a new LOGIN sign-on policy action, which is associated with the new sign-on policy.

  5. Make a POST request to /environments/{environmentId}/applications/{applicationId}/signOnPolicyAssignments to associate this sign-on policy with the specified application.

Step 1: Create the new identity provider resource

You can use the POST /environments/{environmentId}/identityProviders endpoint to create the identity provider configuration for Facebook. This request automatically creates the core attribute mapping to associate the PingOne username attribute with the Facebook email attribute. To verify the mapping, you can use the ?expand=attributes query filter to show the core attribute details in the POST response.

curl -X "POST" "https://api.pingone.com/v1/environments/{environmentId}/identityProviders?expand=attributes" \
-H 'Content-type: application/json' \
-H 'Authorization: Bearer jwtToken' \
-d '{
  "name": "FacebookIdP",
  "description": "Facebook social media identity provider.",
  "enabled": true,
  "type": "FACEBOOK",
  "appId" : "{facebookAppId}",
  "appSecret": "{facebookAppSecret}"
}'

In the request, the name property for the new identity provider is required and must be unique within the environment. The enabled property is required and should be set to true, and the type property is required and must specify FACEBOOK as the identity provider type.

The {facebookAppId} and {facebookAppSecret} are required. These are the values you must obtain from Facebook.

The response shows the configuration data for the new identity provider.

{
    "_links": {
        "self": {
            "href": "https://api.pingone.com/v1/environments/9ad15e9e-3ac6-43f7-a053-d46b87d6c4a7/identityProviders/65fb47be-c71e-45b6-9c4c-e3deed8df116"
        },
        "environment": {
            "href": "https://api.pingone.com/v1/environments/9ad15e9e-3ac6-43f7-a053-d46b87d6c4a7"
        },
        "attributes": {
            "href": "https://api.pingone.com/v1/environments/9ad15e9e-3ac6-43f7-a053-d46b87d6c4a7/identityProviders/ad6e99f3-1053-4ce0-9623-09bab0a1c74a/attributes"
        }
    },
    "id": "ad6e99f3-1053-4ce0-9623-09bab0a1c74a",
    "type": "FACEBOOK",
    "name": "FacebookIdP",
    "description": "Facebook social media identity provider.",
    "enabled": true,
    "environment": {
        "id": "9ad15e9e-3ac6-43f7-a053-d46b87d6c4a7"
    },
    "createdAt": "2019-06-17T18:03:45.785Z",
    "updatedAt": "2019-06-17T18:03:45.785Z",
    "_embedded": {
      "attributes": [
        {
          "name": "username",
          "value": "${providerAttributes.email}",
          "update": "EMPTY_ONLY",
          "id": "d14033ff-cc74-4ea3-9170-400a877de472",
          "mappingType": "CORE",
          "environment": {
            "id": "9ad15e9e-3ac6-43f7-a053-d46b87d6c4a7"
          },
          "identityProvider": {
            "id": "ad6e99f3-1053-4ce0-9623-09bab0a1c74a"
          },
          "createdAt": "2019-09-26T15:40:56.013Z",
          "updatedAt": "2019-09-26T15:40:56.013Z"
        }
      ]
    },
    "appSecret": "FBSecret",
    "appId": "FBID"
}

Step 2: Create an optional attribute mapping

The POST /environments/{environmentId}/identityProviders/{providerId}/attribute endpoint creates the identity provider attribute mappings. The attributes HAL link returned in the Step 1 response provides the URL for the request.

It is recommended that you map the PingOne email attribute to the Facebook email attribute. If you do not map a value for the PingOne email address, the user will have to verify their email address when they sign on using Facebook.

The following sample shows the mapping between the PingOne email attribute and the Facebook email attribute.

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

The response data looks like this:

{
    "_links": {
        "self": {
            "href": "https://api.pingone.com/v1/environments/9ad15e9e-3ac6-43f7-a053-d46b87d6c4a7/identityProviders/ad6e99f3-1053-4ce0-9623-09bab0a1c74a/attributes/415281f6-923d-483f-a63f-98888b0c7b66"
        },
        "identityProvider": {
            "href": "https://api.pingone.com/environments/9ad15e9e-3ac6-43f7-a053-d46b87d6c4a7/identityProviders/ad6e99f3-1053-4ce0-9623-09bab0a1c74a"
        }
    },
    "name": "email",
    "value": "${providerAttributes.email}",
    "update": "EMPTY_ONLY",
    "id": "415281f6-923d-483f-a63f-98888b0c7b66",
    "mappingType": "CUSTOM",
    "environment": {
        "id": "9ad15e9e-3ac6-43f7-a053-d46b87d6c4a7"
    },
    "identityProvider": {
        "id": "ad6e99f3-1053-4ce0-9623-09bab0a1c74a"
    },
    "createdAt": 1559592542048,
    "updatedAt": 1559592542048
}

In the request, the name property is required and must identify a valid PingOne user attribute. The value property is required and must specify a supported Facebook attribute. For more information about supported Facebook attributes, see Facebook provider attributes.

The update attribute is required and specifies whether to update the user attribute in the PingOne directory with the non-empty mapped value from Facebook. Optional values for this attribute are EMPTY_ONLY (only update the user attribute if it has an empty value), and ALWAYS (always update the user attribute value).

Step 3: Create the new sign-on policy

You can use the POST /environments/{environmentId}/signOnPolicies endpoint to create the new sign-on policy.

curl -X "POST" "https://api.pingone.com/v1/environments/{environmentId}/signOnPolicies" \
-H 'Content-type: application/json' \
-H 'Authorization: Bearer jwtToken' \
-d '{
  "name": "FacebookPolicy",
  "default": "true",
  "description": "A sign-on policy for the Facebook identity provider."
}'

In the request, the name property is required and must be unique within the environment. The description property is optional, but recommended. The default property is optional, and should be set only if you want this sign-on policy to be the default policy for all applications in the environment. If this property is not set to true in the request, the value is set automatically to false.

The response shows the property data for the new sign-on policy.

{
  "_links": {
    "self": {
      "href": "https://api.pingone.com/v1/environments/9ad15e9e-3ac6-43f7-a053-d46b87d6c4a7/signOnPolicies/ff11048e-c74f-4bda-86d1-851ec721e25d"
    },
    "environment": {
      "href": "https://api.pingone.com/v1/environments/9ad15e9e-3ac6-43f7-a053-d46b87d6c4a7"
    },
    "actions": {
      "href": "https://api.pingone.com/v1/environments/9ad15e9e-3ac6-43f7-a053-d46b87d6c4a7/signOnPolicies/ff11048e-c74f-4bda-86d1-851ec721e25d/actions"
    }
  },
  "id": "ff11048e-c74f-4bda-86d1-851ec721e25d",
  "environment": {
    "id": "9ad15e9e-3ac6-43f7-a053-d46b87d6c4a7"
  },
  "name": "FacebookPolicy",
  "description": "A sign-on policy for the Facebook identity provider.",
  "default": true
}

The response includes an actions HAL link to the sign-on policy actions endpoint, which is used to assign an action to the new sign-on policy. The policy must have at least one associated action before it can be assigned to an application.

Step 4: Create the sign-on policy action

This step associates a sign-on policy action with the new sign-on policy you created in Step 3. The POST /environments/{environmentId}/signOnPolicies/{policyId}/actions operation creates the sign-on policy action resource, which is associated with the sign-on policy ({policyId}) specified in the request URL.

PingOne supports the following two sign-on policy action types:

  • LOGIN

    Basic authentication that prompts for a username and password.

  • MULTI_FACTOR_AUTHENTICATION

    A multi-factor action that can return multiple status conditions, which result in more than one operation to complete.

To establish a Facebook username/password login flow, the type property for the action resource associated with the sign-on policy can be set to LOGIN.

For a sign-on action that supports Facebook, the sign-on policy action must include the socialProviders.​id property to specify the Facebook identity provider ID {providerId} that you created in Step 1.

In addition, it is highly recommended that a sign-on policy that supports Facebook also include the registration property to allow automatic account creation and account linking between the user’s Facebook account and the PingOne account. For details about the registration sign-on action and how it relates to account linking, see External identity provider login flow states.

curl -X "POST" "https://api.pingone.com/v1/environments/{environmentID}/signOnPolicies/{policyId}/actions" \
-H 'Content-type: application/json' \
-H 'Authorization: Bearer jwtToken' \
-d '{
    "environment": {
        "id": "{environmentId}"
    },
    "signOnPolicy": {
        "id": "{policyId}"
    },
    "priority": 1,
    "type": "LOGIN",
    "socialProviders.​id": "{providerId}",
    "registration" : {
      "enabled" : true,
      "population" : {
        "id" : "{populationID}"
      }
    },
    "recovery" : {
      "enabled" : true
    }
}'

In this sample, the priority property is set to 1, which designates this policy as the first sign-on policy executed, if there is more than one sign-on policy associated with the application. In addition, this action includes the recovery property to enable the password.recover authentication flow, allowing users to recover a forgotten password.

The response data looks like this:

{
    "_links": {
        "self": {
            "href": "https://api.pingone.com/v1/environments/9ad15e9e-3ac6-43f7-a053-d46b87d6c4a7/signOnPolicies/5edef002-3f1f-4e00-a4db-130807f41234/actions/a256b35d-4b14-4ee5-85da-d8450c1aefd2"
        },
        "environment": {
            "href": "https://api.pingone.com/v1/environments/9ad15e9e-3ac6-43f7-a053-d46b87d6c4a7"
        },
        "signOnPolicy": {
            "href": "https://api.pingone.com/v1/environments/9ad15e9e-3ac6-43f7-a053-d46b87d6c4a7/signOnPolicies/5edef002-3f1f-4e00-a4db-130807f41234"
        }
    },
    "id": "a256b35d-4b14-4ee5-85da-d8450c1aefd2",
    "environment": {
        "id": "9ad15e9e-3ac6-43f7-a053-d46b87d6c4a7"
    },
    "signOnPolicy": {
        "id": "5edef002-3f1f-4e00-a4db-130807f41234"
    },
    "priority": 1,
    "type": "LOGIN",
    "socialProviders.​id": "65fb47be-c71e-45b6-9c4c-e3deed8df116",
    "registration" : {
      "enabled" : true,
      "population" : {
        "id" : "fb526776-dc9b-4c35-af89-d9c98d8d723b"
      }
    },
    "recovery" : {
      "enabled" : true
    }
}

Step 5: Assign the sign-on policy to an application

To use the new sign-on policy, the POST /environments/{environmentId}/applications/{applicationId}/signOnPolicyAssignments operation assigns the new sign-on policy to the application designated by its ID in the request URL. The request body requires the sign-on policy property id and an integer value for the priority property.

curl -X "POST" "https://api.pingone.com/v1/environments/{environmentId}/applications/{applicationId}/signOnPolicyAssignments" \
-H 'Content-type: application/json' \
-H 'Authorization: Bearer jwtToken' \
-d '{
    "signOnPolicy": {
      "id": "5edef002-3f1f-4e00-a4db-130807f41234"
    },
    "priority": 1
}'

The response data looks like this:

{
    "_links": {
        "self": {
            "href": "https://api.pingone.com/v1/environments/9ad15e9e-3ac6-43f7-a053-d46b87d6c4a7/applications/d64f66de-1502-4398-96a1-02f0d2a86f9c/signOnPolicyAssignments/ede42c6c-a97a-4c2c-aaeb-9cb38f13bb13"
        },
        "environment": {
            "href": "https://api.pingone.com/v1/environments/9ad15e9e-3ac6-43f7-a053-d46b87d6c4a7"
        },
        "application": {
            "href": "https://api.pingone.com/v1/environments/9ad15e9e-3ac6-43f7-a053-d46b87d6c4a7/applications/d64f66de-1502-4398-96a1-02f0d2a86f9c"
        },
        "signOnPolicy": {
            "href": "https://api.pingone.com/v1/environments/9ad15e9e-3ac6-43f7-a053-d46b87d6c4a7/signOnPolicies/5edef002-3f1f-4e00-a4db-130807f41234"
        }
    },
    "id": "ede42c6c-a97a-4c2c-aaeb-9cb38f13bb13",
    "environment": {
        "id": "9ad15e9e-3ac6-43f7-a053-d46b87d6c4a7"
    },
    "application": {
        "id": "d64f66de-1502-4398-96a1-02f0d2a86f9c"
    },
    "signOnPolicy": {
        "id": "54f11a8b-0e09-4f76-8cdc-2efa2c9c499e"
    },
    "priority": 1
}