PingFederate Server

Setting up self-service registration

PingFederate leverages the HTML Form Adapter to deliver include::partial$pf_rc_consumerregistrationauthenticationprofilemanagement.adoc[tags=pf_ph_consumerRegistrationAuthenticationProfileManagement].

About this task

A typical self-service registration setup involves five components:

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

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

      For more information, see Managing policy contracts.

  3. Create a local identity profile using the Authentication → Policies → Local Identity Profiles configuration wizard.

    1. In the Local Identity Profiles window, click Create New Profile.

    2. On the Profile Info tab, enter a name in the Local Identity Profile Name field.

    3. From the Authentication Policy Contract list, select the authentication policy (from step 2), and select the Enable Registration check box. Click Next.

    4. On the Authentication Sources tab, click Next.

    5. On the Fields tab, click Create New Field.

    6. In the Field Configuration window, on the Field Configuration tab, define four local identity fields. Enter the information described in the following table.

      Local Identity Profile fields and entries
      Type ID Label Parameters

      Email

      lipEmail

      Email address

      Select the Required check box.

      Text

      lipFirstName

      First name

      Select the Required check box.

      Text

      lipLastName

      Last name

      Select the Required check box.

      Phone

      lipMobile

      Mobile number

      No parameters are required.
      Screen capture of the local identity profile field configuration window. There are fields for ID, Label, and Type. There are also Read-Only, which is selected, Required, and Mask Log Values check boxes in the Parameters section.

    7. After each field entry, click Next. On the Summary tab, review your changes. Click Done.

    8. Repeat steps e through g until the fields are entered.

      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. The latter applies to all local identity fields.

    9. In the Local Identity Profile window, on the Fields tab, identify an ID field to be the unique ID for your configuration, and click the corresponding Unique ID. Click Next.

    10. On the Email Verification tab, click Next.

    11. On the Registration tab, click Next.

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

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

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

    15. 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}

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

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

    18. 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 Authentication → Policies → Policies.

    2. Click Add Policy.

    3. In the Policy window, in the Name field, enter a name.

    4. Select the HTML Form Adapter instance (configured in step 4) under Policy.

      1. For its Fail path, select Done.

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

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

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

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

    8. On the Contract Fulfillment tab, fulfill the authentication policy contract with values from this local identity profile as follows:

      Outbound Contract Fulfillment Source Value

      subject

      Local Identity

      lipEmail

      firstName

      Local Identity

      lipFirstName

      lastName

      Local Identity

      lipLastName

      mobileNumber

      Local Identity

      lipMobile

    9. On the Issuance Criteria tab, click Next.

    10. On the Summary tab, click Done.

    11. On the Policy window, click Done.

    12. On the Policies window, select the IdP Authentication Policies check box.

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

    13. Click Save to keep your changes.

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

  6. Map the authentication policy contract to the applicable Browser SSO connections, OAuth grant-mapping configuration, or both. See Managing authentication source mappings and Managing authentication policy contract grant mapping.

Result

You have now successfully set up self-service registration. When users sign on through this HTML Form Adapter instance, they have the option to complete a self-service registration process to create their accounts using the Register now link, as illustrated in the following screen capture.

Screen capture of a sample sign-on page

If a user chooses to register, the HTML Form Adapter redirects the user to the registration page. Based on the configuration of this sample use case, as illustrated in the following registration screen capture.

Screen capture of a sample registration page