PingFederate Server

Enabling third-party identity providers

For registration, you can optionally allow users to leverage their existing identities from third-party identity providers. Any identity provider (IdP) connection or IdP adapter, such as the LinkedIn IdP Adapter in the LinkedIn Login Integration Kit, can be used as an authentication source to a third-party identity provider.

About this task

Using the Administrative console, enable third-party IdP. 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. This capability enables a mapping configuration between the attributes returned by the identity provider and the fields within the registration page, streamlining the registration process. See the following configuration steps.

  • 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 need to support a consumer registration use case, where users 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.

Configure a third-party identifier.

If you know how to set up PingDirectory to connect with PingFederate and an authentication policy contract shown in Setting up self-service registration, you can skip to step 3 to create a local identity profile.

Steps

  1. Install PingDirectory.

  2. Create an authentication policy contract.

    1. Go to Authentication → Policies → Policy Contracts.

    2. In the Policy Contracts window, click Create New Contract.

    3. On the Contract Attributes tab, in the Extend the Contract field, extend the authentication policy contract with three additional attributes, such as, firstName, lastName, and mobileNumber.

    4. After each entry add, click Add. Click Next.

    5. On the Summary tab, review your changes. Click Done.

    6. In the Policy Contracts window, click Save.

      For more information, see Managing policy contracts.

  3. Create a local identity profile using the Authentication → Policies → Local Identity Profiles. Click Create New Profileto access the Local Identity Profile window and configuration wizard.

    1. On the Profile Info tab, enter a name in theLocal Identity Profile Name field, select the authentication policy from step 2, and select the Enable Registration check box. Click Next.

    2. On the Authentication Sources tab, enter ACME in the Authentication Source field. Click Add.

      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 window.

      If you know how to set up a local identity profile and an HTML Form Adapter instance for customer identities shown in Setting up self-service registration), you can skip to step 5 to create an IdP authentication policy.

    3. On the Fields tab, define four local identity fields as shown in the following table.

      Type ID Label Parameters

      Email

      lipEmail

      Email address

      Select the Required and Unique ID check boxes.

      The Unique IDcheck boxes are on the Fields tab.

      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 select the Mask all OGNL-expression generated log values check box for all fields.

    4. On the Email Verification tab, click Next.

    5. On the Registration tab, click Next.

    6. On the Data Store Configuration tab, click Configure Data Store.

    7. In the Data Store Configuration window, on the Data Store tab, from the Data Store list, select the LDAP datastore that has been set up to connect to your PingDirectory. Click Next.

    8. In the Data Store Configuration window, on the LDAP Configuration tab, 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. In the Data Store Configuration window, on the Identity Creation tab, define the RDN pattern in the Relative DN Pattern field, and select your object, such as class aPerson for this sample use case, from the Object Class list.

      The pattern is as follows.

      attribute1=value1[, …​, attributeN=valueN]

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

      entryUUID=${entryUUID}

    10. In the Data Store Configuration window, on the Data Store Mapping tab, configure the mapping between the local identity profile fields and the datastore attributes. See the following table.

      Mapping entries for local identity profile fields and datastore attributes
      Field Data Store Attribute

      lipEmail

      mail

      lipFirstName

      givenName

      lipLastName

      sn

      lipMobile

      mobile

    11. In the Data Store Configuration window, on the Summary tab, click Done.

    12. On the Summary tab of the local identity profile, click Save.

      For more information, see Configuring local identity profiles.

  4. Configure an HTML Form Adapter instance for customer identities.

    1. Go to the Authentication → Integration → IdP Adapters.

    2. Create a new HTML Form Adapter instance or reuse an existing one by clicking its name.

    3. On the IdP Adapter tab, in the Password Credential Validator Instance section 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 tab, select the newly created local identity profile in the Local Identity Profile list.

    5. Complete the rest of the configuration and save all changes.

      (For more information, see Configuring the HTML Form Adapter for customer identities.)

  5. Create an IdP authentication policy.

    1. Go to the Authentication → Policies → Policies.

    2. Under Policy, select the HTML Form Adapter instance configured in step 4.

    3. In the Policy window, under the Value section, select the drop-down arrow to show the Fail and Success fields.

      1. For the Fail path, select Done.

      2. For the Success path, select the local identity profile created in step 3. Click Done.

    4. Click Local Identity Mapping underneath the selected local identity profile, which opens the Inbound Mapping & Contract Fulfillment configuration wizard.

      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.

      If you know how to setup the inbound mapping and contract fulfillment of an authentication policy contract through a local identity profile shown in Setting up self-service registration, you can skip to step 1 to create a rule for the scenario where users choose to register and subsequently authenticate via ACME.

    5. On the Inbound Mapping & Contract Fulfillment Inbound Mapping window, 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 window as shown in the following table.

      Inbound Mapping Fulfillment Source Value

      pf.local.identity.unique.id

      Adapter

      username

    6. On the Attribute Sources & User Lookup tab, click Next.

    7. On the Attribute Sources & User Lookup tab, click Next.

    8. On the Issuance Criteria tab, click Next.

    9. On the Inbound Mapping & Contract Fulfillment → Summary window, click Done.

      The Inbound Mapping & Contract Fulfillment configuration wizard brings back the Manage Authentication Policies window.

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

    10. Click Rules underneath the Success path of the HTML Form Adapter instance.

    11. 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 in the following table.

      Authentication policy rules fields and entries
      Attribute Name Condition Value Result

      policy.action

      equal to

      ACME

      The value here must match the value defined on the Authentication Sources window. 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 window.

      If you have defined multiple third-party identity providers on the Authentication Sources window, 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 Authentication Policies window.

    12. For the ACME users path, select the IdP connection to ACME under Action.

      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.

        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.

      2. For its Success path, select the local identity profile created in step 3.

    13. Click Local Identity Mapping underneath the selected IdP connection, which opens the Inbound Mapping & Contract Fulfillment configuration wizard.

    14. On the Inbound Mapping & Contract FulfillmentInbound Mapping window, 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 window is configured as in the following table.

      Inbound Mapping fields and entries
      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

    15. On the Attribute Sources & User Lookup tab, click Next.

    16. On the Attribute Sources & User Lookup tab, click Next.

    17. On the Issuance Criteria tab, click Next.

    18. On the Inbound Mapping & Contract Fulfillment Summary tab, click Done.

      The Inbound Mapping & Contract Fulfillment configuration wizard brings back the Manage Authentication Policies window.

      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.

    19. In the Policies window, on the Policies tab, select the IdP Authentication Policies check box.

      Other IdP authentication policies, if any, are enabled as well.

    20. Click Save to keep your changes.

    For more information, see Applying policy contracts or identity profiles to authentication policies.

Result

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 screen capture of a sign-on page is presented.

Screen capture of 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 screen capture of a sample registration page

This registration option streamlines the self-service registration process.