For registration, you can optionally allow users to leverage their existing identities from third-party identity providers. Any IdP connection or IdP adapter (such as the LinkedIn Cloud Identity Connector) can be used as an authentication source to a third-party identity provider. This optional capability enables a mapping configuration between the attributes returned by the identity provider and the fields within the registration page, thus streamlining the registration process. This configuration involves the same five components to set up registration, plus the IdP connections or IdP adapter instances to connect with the third-party identity providers.

  • IdP connections or IdP adapter instances
  • A PingDirectory installation (step 1)
  • An authentication policy contract (step 2)
  • A local identity profile (step 3)
  • An HTML Form Adapter instance (step 4)
  • An IdP authentication policy (step 5)

To illustrate the configuration steps, consider the following example:

You are tasked to support a consumer registration use case, where users can complete a self-service registration process to create their accounts and then access resources protected by multiple service providers. For a registration to complete successfully, a user must provide an email address, a first name, a last name, an optional mobile phone number, and a password. The email address is the user identifier. All attributes are sent to the service providers as per the partner agreements. You have already created a specific object class in the directory to store the user information. The object class name is aPerson, and the LDAP attributes are mail, givenName, sn, and mobile.

Additionally, this use case must also allow users to take advantage of their existing accounts at ACME (a major social network) for registration and authentication. It happens that you have already established an IdP connection to this social network, from which you received the same set of attributes: SAML_SUBJECT (for the user's email address), ssoFirstName, ssoLastName, and ssoMobile.

Configuration steps:

Tip:

If you are familiar with the steps to set up PingDirectory to connect with PingFederate and an authentication policy contract (as documented in Setting up self-service registration), you may skip to step 3 to create a local identity profile.

  1. Install PingDirectory, update its LDAP schema, set up the required index, and then create an LDAP datastore and an LDAP Username Password Credential Validator instance in PingFederate.
  2. Create an authentication policy contract using the Identity Provider > Policy Contract configuration wizard. Extend the authentication policy contract with three additional attributes; for example, firstName, lastName and mobileNumber.
    (For more information, see Managing policy contracts.)
  3. Create a local identity profile using the Identity Provider > Identity Profiles configuration wizard.
    1. On the Profile Info screen, enter a name of the local identity profile, select the authentication policy (from step 2), and select the Enable Registration check box.
    2. On the Authentication Sources screen, enter ACME under Authentication Source and then click Add.
      Note:

      To support additional third-party identity providers, enter a value for each. At runtime, the sign-on page displays them in the order defined on this screen.

      Tip:

      If you are familiar with the steps to set up a local identity profile and an HTML Form Adapter instance for customer identities (as documented in Setting up self-service registration), you may skip to step 5 to create an IdP authentication policy.

    3. On the Fields screen, define four local identity fields, as follows:
      Type ID Label Parameters
      Email lipEmail Email address Select the Required and Unique ID Field check boxes.
      Text lipFirstName First name Select the Required check box.
      Text lipLastName Last name Select the Required check box.
      Phone lipMobile Mobile number None required.

      As needed, select the Mask Log Values check box for any of the four local identity fields and the Mask all OGNL-expression generated log values check box (for all fields).

    4. On the Email Verification screen, click Next.
    5. On the Registration screen, click Next.
    6. On the Data Store Configuration screen, click Configure Data Store.
    7. On the Data Store Configuration > Data Store screen, select the LDAP datastore that has been set up to connect to your PingDirectory.
    8. On the Data Store Configuration > LDAP Configuration screen, specify the branch of your directory hierarchy where you want PingFederate to store customer identities in the Base DN field and the LDAP attributes to be associated with fields defined in this local identity profile under Attribute.
    9. On the Data Store Configuration > Identity Creation screen, define the RDN pattern in the Relative DN Pattern field and select your object class (aPerson for this sample use case) from the Object Class list.

      The pattern is:

      attribute1=value1[, ..., attributeN=valueN]

      If you want to use the ${entryUUID} variable to guarantee the uniqueness of the relative DNs for all users, you must use it with the entryUUID LDAP attribute; for example:

      entryUUID=${entryUUID}

    10. On the Data Store Configuration > Data Store Mapping screen, configure the mapping between the local identity profile fields and the datastore attributes as follows:
      Field Data Store Attribute
      lipEmail mail
      lipFirstName givenName
      lipLastName sn
      lipMobile mobile
    11. On the Data Store Configuration > Summary screen, click Done.
    12. On the Summary screen of the local identity profile, click Save.
    (For more information, see Defining a local identity profile.)
  4. Configure an HTML Form Adapter instance for customer identities.
    1. Go to the Identity Provider Adapters screen.
    2. Create a new HTML Form Adapter instance or reuse an existing instance by clicking its name.
    3. On the IdP Adapter screen, add the LDAP Username Password Credential Validator instance that has been set up to validate credentials stored on your PingDirectory.
    4. On the IdP Adapter screen, select the newly created local identity profile from the Local Identity Profile list.
    5. Complete the rest of the configuration and save all changes.
  5. Create an IdP authentication policy.
    1. Go to the IdP Providers > Policies screen.
    2. Select the HTML Form Adapter instance (configured in step 4) under Action.
      1. For its Fail path, select Done.
      2. For its Success path, select the local identity profile (created in step 3).
    3. Click Local Identity Mapping underneath the selected local identity profile, which opens the Inbound Mapping & Contract Fulfillment configuration wizard.
      Note:

      The next few steps configure the fulfillment of the authentication policy contract for the scenario where users choose to register directly without going through ACME.

      Tip:

      If you are familiar with the steps to setup the inbound mapping and contract fulfillment of an authentication policy contract through a local identity profile (as documented in Setting up self-service registration), you may skip to step i to create a rule for the scenario where users choose to register and subsequently authenticate via ACME.

    4. On the Inbound Mapping & Contract Fulfillment > Inbound Mapping screen, configure the pf.local.identity.unique.id built-in local identity field for the registration process.
      At runtime, PingFederate fulfills the value of the pf.local.identity.unique.id built-in local identity field based on this configuration and passes the value to PingDirectory. PingDirectory uses this value to determine whether such identity has already been created. The pf.local.identity.unique.id field value should therefore be mapped from the subject identifier of the preceding authentication source, namely the username attribute from the HTML Form Adapter.

      For this sample use case, configure the Inbound Mapping screen as follows:

      Inbound Mapping Fulfillment Source Value
      pf.local.identity.unique.id Adapter username
    5. On the Inbound Mapping & Contract Fulfillment > Attribute Sources & User Lookup screen, click Next.
    6. On the Inbound Mapping & Contract Fulfillment > Attribute Sources & User Lookup screen, click Next.
    7. On the Inbound Mapping & Contract Fulfillment > Issuance Criteria screen, click Next.
    8. On the Inbound Mapping & Contract Fulfillment > Summary screen, click Done.
      The Inbound Mapping & Contract Fulfillment configuration wizard brings back the Manage Authentication Policies screen.
      Note:

      The remaining steps configure the fulfillment of the authentication policy contract for the scenario where users choose to register and subsequently authenticate via ACME.

    9. Click Rules underneath the Success path of the HTML Form Adapter instance.
    10. On the Rules dialog, create a policy path for users who choose to register and authenticate via ACME. For this sample use case, configure as follows:
      Attribute Name Condition Value Result
      policy.action equal to ACME
      Important:

      The value here must match the value defined on the Authentication Sources screen (see step 3b).

      ACME users

      The Result field controls the label shown for the policy path of this rule. The value does not need to match the value defined on the Authentication Sources screen.

      Important:

      If you have defined multiple third-party identity providers on the Authentication Sources screen, you must repeat these steps to add a policy.action rule to create a policy path for each.

      In addition, select the Default to Success check box (the default behavior). When selected, the Success path remains, which is important for this sample use case where users are free to choose whether to register and subsequently authenticate via ACME.

      When finished, click Done, which brings you back to the Manage Authentication Policies screen.

    11. For the ACME users path, select the IdP connection to ACME under Action.
      Tip:

      Generally speaking, any IdP adapter instance or IdP connection that connects to the third-party identity provider can be used here.

      1. For its Fail path, select Done.
        Note:

        If you have defined multiple third-party identity providers and added rules to create a policy path for each, you may select Restart. The Restart policy action provides users the opportunity to do over. When triggered, the policy engine routes the requests back to the first checkpoint of the invoked authentication policy.

        By selecting Restart for the Fail path, you give users the opportunity to choose another third-party identity provider when they fail to authenticate through ACME.

        Undesirable looping behaviors can occur if you select Restart for the Fail path at the root of an authentication policy tree. PingFederate mitigates this risk by automatically limiting the number of policy restarts per transaction in maintenance releases 9.2.3, 9.3.3, and 10.0.3 or newer.

      2. For its Success path, select the local identity profile (created in step 3).
    12. Click Local Identity Mapping underneath the selected IdP connection, which opens the Inbound Mapping & Contract Fulfillment configuration wizard.
    13. On the Inbound Mapping & Contract Fulfillment > Inbound Mapping screen, configure the pf.local.identity.unique.id built-in local identity field for the registration process and optionally other fields so that PingFederate can pre-populate values for these fields on the registration page.

      At runtime, PingFederate fulfills the value of the pf.local.identity.unique.id built-in local identity field based on this configuration and passes the value to PingDirectory. PingDirectory uses this value to determine whether such identity has already been created. The pf.local.identity.unique.id field value should therefore be mapped from the subject identifier of the preceding authentication source, namely the subject identifier from the IdP connection.

      For this sample use case, the Inbound Mapping screen is configured as follows:

      Inbound Mapping Fulfillment Source Value
      pf.local.identity.unique.id IdP Connection SAML_SUBJECT
      lipEmail IdP Connection SAML_SUBJECT
      lipFirstName IdP Connection ssoFirstName
      lipLastName IdP Connection ssoLastName
      lipMobile IdP Connection ssoMobile
    14. On the Inbound Mapping & Contract Fulfillment > Attribute Sources & User Lookup screen, click Next.
    15. On the Inbound Mapping & Contract Fulfillment > Attribute Sources & User Lookup screen, click Next.
    16. On the Inbound Mapping & Contract Fulfillment > Issuance Criteria screen, click Next.
    17. On the Inbound Mapping & Contract Fulfillment > Summary screen, click Done.
      The Inbound Mapping & Contract Fulfillment configuration wizard brings back the Manage Authentication Policies screen.
      Important:

      If you have defined multiple rules, each forming a policy path for a third-party identity provider, ensure you complete the Inbound Mapping & Contract Fulfillment configuration for each of them.

    18. Select the IdP Authentication Policies check box.
      Note:

      Other IdP authentication policies (if any) are enabled as well.

    19. Click Save to keep your changes.

You have now successfully set up self-service registration with an option for users to register and subsequently authenticate via ACME. When users sign on through this HTML Form Adapter instance, they have two registration options:

  • Click the Register now link, fill in the registration page, and register.
  • Click the social sign on link, authenticate via ACME, review the registration page, and register.

Based on the configuration of this sample use case, the following sign-on page is presented:

A sample sign-on page with an option to sign on with ACME

If you have added Facebook, Google, LinkedIn, and Twitter as the authentication sources, the following sign-on page is presented:

A sample sign-on page with an option to sign on with ACME and more

Suppose a user chooses to register through ACME. Once authenticated and redirected back to PingFederate, PingFederate pre-populates the registration page with values it receives from ACME, as illustrated in this screen capture:

A sample registration page

This registration option streamlines the self-service registration process.