PingFederate Server

Configuring an Identifier First Adapter instance

Configure an instance of the Identifier First Adapter in PingFederate following these instructions and for additional configuration information on fieldnames, descriptions, and optimal settings depending on your use case.

About this task

Using the PingFederate administrative console, configure an Identifier First Adapter instance.

Steps

  1. Go to Authentication → Integration → IdP Adapters.

  2. On the IdP Adapters window, click Create New Instance to start the Create Adapter Instance configuration.

  3. On the Type tab, configure the basics of this adapter instance:

    1. Enter the Instance Name and Instance ID.

    2. In the Type list, select the adapter type.

    3. In the Parent Instance list, select an existing type.

    If you are creating an instance that is similar to an existing instance, consider making it a child instance by specifying a parent. A child instance inherits the configuration of its parent unless overridden. You can specify overrides during the rest of the setup.

  4. On the IdP Adapter tab, configure your Identifier First Adapter instance.

    For more information about each field, see the following table.

    PingFederate’s fields and descriptions for creating an Identifier First Adapter instance
    Field Description

    Identifier Cookie Lifetime

    Determines the number of days that previously authenticated identifiers are preserved as a cookie on the client side. This value can range from 0 through 3650.

    Set to 0 to disable the storage of any previously authenticated identifiers.

    The default value is 30.

    Allow Cancelling Identifier Selection

    Determines whether a user is allowed to continue without entering or selecting an identifier.

    If allowed, when a user decides to continue without providing an identifier, the Identifier First Adapter treats the authentication attempt as a failure and returns control to PingFederate.

    This check box is not selected by default.

    Click Show Advanced Fields to review the following settings. Modify as needed.

    Maximum Identifiers Count

    Determines the maximum number of previously authenticated identifiers can be preserved in the identifier cookie. This value can range from 0 through 10.

    Set to 0 to disable the storage of any previously authenticated identifiers.

    The default value is 5.

    Identifier Selection Template

    The HTML template to prompt the user to enter or select an identifier. PingFederate allows each configured adapter instance to use a different template as needed.

    The default template file is identifier.first.template.html.

    Like other Velocity template files, it is located in the <pf_install>/pingfederate/server/default/conf/template directory.

    Enable Risk Provider

    (Optional) Enables the use of a risk provider, such as CAPTCHA, which will call the service when the HTML template is shown to the end user.

    Risk Provider

    If Enable Risk Provider is enabled, the provider configured in this field is used by this adapter instance.

  5. On the Extended Contract tab, configure additional attributes for this adapter instance as needed.

    The Identifier First Adapter contract includes two core attributes: subject and domain.

    If the identifier is an email address, the adapter extracts the email address suffix and exposes it downstream through the domain attribute. As needed, the adapter can leverage datastore queries to fulfill the domain attribute. For more information, see step 7).

  6. On the Adapter Attributes tab, do the following:

    1. Optional: From the Unique User Key Attribute list, select an attribute to uniquely identify users signing on with this adapter.

      The attribute’s value is used to identify user sessions across all adapters. None is selected by default.

      If you choose a custom user key attribute, PingFederate uses the value of the attribute after the Adapter Contract Mapping (if any) has been evaluated. If you choose a custom user key attribute that is based on the username, configure the adapter’s password credential validator (PCV) to trim spaces.

      For the HTML Form Adapter, If you enabled the Revoke Sessions after Password Change or Reset option on the IdP Adapter tab, you cannot select None as the unique user key attribute. Doing so results in an error message.

    2. Select the check box under Pseudonym for the user identifier of the adapter and optionally for the other attributes, if available.

      This selection is used if any of your service provider (SP) partners use pseudonyms for account linking.

      A selection is required whether or not you use pseudonyms for account linking. This allows account linking to be used later without having to delete and reconfigure the adapter. Ensure that you choose at least one attribute that is unique for each user, such as a user’s email, to prevent assigning the same pseudonym to multiple users.

    3. Select the check box under Mask Log Values for any attributes whose values you want PingFederate to mask in its logs at runtime.

      Masking is not applied to the unique user key attribute in the logs even though the attribute used for the key is marked as Mask Log Values.

    4. Select the Mask all OGNL-expression generated log values check box if OGNL expressions might be used to map derived values into outgoing assertions and you want those values masked.

  7. On the Adapter Contract Mapping tab, configure the adapter contract for this instance with the following optional workflows:

    • Configure one or more data sources for datastore queries.

    • Fulfill adapter contract with values from the adapter, the default, datastore queries, if configured, context of the request, text, or expressions, if enabled.

    • Set up the Token Authorization framework to validate one or more criteria prior to the issuance of the adapter contract.

  8. Optional: On the Summary tab, review your configuration and modify as needed. Click Save.

  9. When finished in the IdP Adapters window, click Save to confirm the adapter instance configuration.

    If you want to exit without saving the configuration, click Cancel.