Using the administrative console, follow the instructions below for configuring an Identifier First Adapter instance, creating an authentication policy to prompt the user for their identifier first, determining their user population, and routing the request to the desired authentication recommendations. Consider the sample use case here.

You need to enforce different sets of authentication requirements for two sets of users, employees, and external consultants.

Employees are given username@example.com email addresses, such as asmith@example.com. User records are stored in a local directory server. Employees sign on through an HTML Form Adapter instance.

Consultants have either username@example.org or username@example.info email addresses. User records are stored in a local database. Consultants can sign on using their username or email address and password through a local web portal. This web portal is integrated with PingFederate using the OpenToken framework.

Your organization owns another local database that keeps track of username, domain information, and email address for both employees and consultants. The column names are dsUid, dsDomain, and dsMail, respectively. For simplicity, no users share the same dsUid value.

In this sample use case, you must make sure that the Identifier First Adapter instance can handle the scenario where users might enter their email address or just their username when setting up the Identifier First Adapter instance. Additionally, when accessing protected resources, your organization has agreed to send the user's email address in the security token.

You have already created the following components:

  • An LDAP datastore connecting to the local directory server. The attribute name of the user identifier is uid.
  • An instance of the LDAP Username Password Credential Validator (PCV) validating credentials against the local directory server with the LDAP datastore. The LDAP Username PCV instance is extended with an additional attribute mail. The search filter is configured to handle identifiers in the format of an email address or a username. See the following code example.


                         (|(uid=${username})(mail=${username}))
                      

  • An HTML Form Adapter instance delegating credential-validation to the LDAP Username PCV instance. The HTML Form Adapter instance is also extended with an additional attribute mail, which takes the mail attribute value from the LDAP Username PCV instance. The ID of this HTML Form Adapter instance is htmlForm.
  • An OpenToken IdP Adapter instance digesting tokens from the web portal as the source of user attributes. The adapter contract is extended with an additional attribute mail. The web portal is designed to always include the user's email address in the token through the mail attribute. The ID of this OpenToken IdP Adapter instance is opentTokenIdp.

This sample use case requires the following additional components:

  • An expression-enabled PingFederate environment. See step 1.
  • An authentication policy contract to carry the email address from your organization to your partners. See step 2.
  • A Java Database Connectivity (JDBC) datastore connecting to the database that hosts username, email, and domain information. See step 3.
  • An Identifier First Adapter instance with an attribute source lookup configuration and a contract fulfillment via expressions for the domain adapter attribute. See step 4.
  • An authentication policy to route user requests to different authentication sources based on user populations. See step 5.

To fulfill the requirements:

  1. Enable expressions in PingFederate.

    For configuration steps, see Enabling and disabling expressions.

  2. Go to Authentication > Policies > Policy Contracts.
  3. On the Policy Contracts window, click Create New Contract and create an authentication policy contract without any additional attributes.
  4. Go to System > Data & Credential Stores > Data Stores.
  5. From the Data Stores window, click Add New Data Store.
    1. On the Data Store Type tab, enter Name.
    2. From the Type list, select Database (JDBC) to create a JDBC datastore connection to the database that hosts username and domain information.
  6. Create an instance of the Identifier First Adapter instance.
    1. Follow steps 1 through 6 in Configuring an Identifier First Adapter instance.

      For the sample use case, suppose you name the adapter instance ID 1st.

    2. Go to Applications > Integration > Adapter-to-Adapter Mappings.
    3. On the Adapter-to-Mappings window, select a source instance and a target instance, and click Add Mapping.
    4. On the Attribute Sources & User Lookup tab, click Add Attribute Source.
      Note:

      For more information about configuring the following steps, see Datastore query configuration.

      1. On the Data Store tab, enter an ID in Attribute Source ID and a name in Attribute Source Description, such as domainInfo and Domain Info, respectively. In the Active Data Storelist, select the JDBC datastore created previously. Click Next.
      2. On the Database Table and Columns tab, select the applicable options from the Schema and Table lists.
      3. Under Columns to return from SELECT, select the dsDomain column and click Add Attribute. Click Next.
      4. On the Database Filter tab, in the Where field, specify a filter to search by identifier that can handle identifiers in the format of an email address or a username.

        See the following example of a filter entry.

        dsUid='${subject}' OR dsMail='${subject}'.
      5. Click Next.
      6. On the Summary tab, click Done.
    5. On the Adapter Contract Fulfillment tab, configure as follows.
      Contract Source Value
      domain Expression 
      
#this.get("domain").toString().matches("(?i).+") ? 
#this.get("domain") : 
#this.get("ds.domainInfo.dsDomain")
      Note:

      Line breaks are inserted for readability only.
      subject Adapter Not applicable. No selection is required.

      The expression checks the domain attribute value returned by the Identifier First Adapter. If the value contains one or more character, PingFederate uses that as the value for the domain attribute. Otherwise, it uses the dsDomain column value returned from the JDBC datastore. In other words, this expression handles identifiers in the format of an email address or a username.

      This sample expression is intended to demonstrate the capability of the Identifier First Adapter. Depending on the actual use cases, expressions may vary. For more information about expressions, see Construct OGNL expressions.

    6. On the Issuance Criteria tab, click Next.
      Note:

      Depending on the actual use cases, you can add issuance criteria.

    7. On the Adapter-to-Adapter Summary tab, review your configuration instance. Click Done to save your adapter instance configuration.
  7. Create an authentication policy with rules to form policy paths based on results from domain attribute values returned by the Identifier First Adapter.
    1. Go to Authentication > Policies > Policies.
    2. From the Policies tab, click Add Policy.
    3. On the Policy window, enter a Name, and optionally a Description, for the policy.
    4. From the Policy list, select the Identifier First Adapter instance created in step 5.
    5. Click Rules to open the Rules dialog.
    6. Add three rules as follows.
      Defining Authentication Policy Rules dialog fields and entries
      Attribute Name Condition Value Result
      domain equal to example.com Example COM
      domain equal to example.org Example ORG
      domain equal to example.info Example INFO
      Note:

      Add one rule for each expected domain attribute value.

    7. Clear the Default to Success check box to disable the option to specify a policy path for the scenario where the domain attribute value from the Identifier First Adapter instance does not match any configured value on the Rules dialog.

      If you want to enable an authentication policy path for unexpected domain attribute values, leave the Default to Success check box as selected.

      For more information about rules, see Configuring rules in authentication policies.

    8. Click Done to close the Rules dialog.

      By adding three rules and disabling the default to success option, the Identifier First Adapter instance now contains four policy paths: Fail, Example COM, Example ORG, and Example INFO.

    9. Configure each policy path.
      Fail
      Select Done, which terminates the request in an error condition.
      Example COM
      Select the HTML Form Adapter instance, which contains two paths: Fail and Success.
      Configure each policy path.
      Fail
      Select Done, which terminates the request in an error condition.
      Success
      Select the policy contract created in step 2.

      Click Options to open the Incoming User ID dialog.

      1. From the Sourcelist, select Adapter (ID 1st).
      2. From the Attribute list, select subject.
      3. Click Done to close the Incoming User ID dialog.

      For more information, see Specifying incoming user IDs.

      Example ORG (and then Example INFO)
      Select the OpenToken IdP Adapter instance, which contains two paths: Fail and Success.
      Configure each policy path by using the same steps documented for the Example COM policy path
    10. Configure contract fulfillment for each authentication policy contract as follows.
      Contract Fulfillment fieldnames and entries
      Result from rules Contract Attribute Source Value
      Example COM subject Adapter (htmlForm) mail
      Example ORG subject Adapter (openTokenIdp) mail
      Example INFO subject Adapter (openTokenIdp) mail

      For more information, see Configuring contract mapping.

    11. Click Done. Click Save.

You have now successfully configured an Identifier First Adapter instance and an authentication policy to prompt the user for their identifier first, determine their user population, and route the request to the desired authentication policy path.