PingFederate Server

Configuring an HTTP Basic Adapter instance

Configure an HTTP Basic Adapter instance to use credentials against a user repository through an instance of a password credential validator (PCV) to support user authentication when it occurs outside of the PingFederate server.

About this task

Using the administrative console, configure an HTTP Basic Adapter instance.

Steps

  1. Go to Authentication > Integration > IdP Adapters.

  2. On the IdP Adapters page, 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. (Optional) 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 HTTP Basic Adapter instance as follows:

    1. If you have not yet defined the desired Password Credential Validator instance, click Manage Password Credential Validators to do so.

    2. Click Add a new row to 'Credential Validators' to select a credential-authentication mechanism instance for this adapter instance.

    3. From the Password Credential Validator Instance list, select a Password Credential Validator instance. Click Update.Add as many validators as necessary. Use the up and down arrows to adjust the order in which you want PingFederate to attempt credential authentication. If the first mechanism fails to validate the credentials, PingFederate moves sequentially through the list until credential validation succeeds. If none of the Password Credential Validator instances can authenticate the user’s credentials, and the challenge retries maximum has been reached, the process fails.

      If usernames overlap across multiple Password Credential Validator instances, this failover setup could lock out those accounts in their source locations.

    4. Enter values for the adapter configuration.

      See the on-window field descriptions and the following table for more information.

    PingFederate’s fields and descriptions for creating an HTTP Basic Adapter instance
    Property Description

    Realm

    (Required)

    The name of a protected area. The value of this field is sent as a part of the HTTP Basic authentication request. It appears in a dialog box that prompts the user for a username and password.

    After a user authenticates against a realm, if additional HTTP Basic Adapter instances share the same realm, the user is not prompted to re-authenticate.

    Challenge Retries

    (Required)

    The number of attempts allowed for password authentication. The default value is 3.

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

    The HTTP Basic Adapter contract includes one core attribute: username.

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

    1. (Optional) In 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 checkbox 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 checkbox 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. If you plan to use OGNL expressions to map derived values into outgoing assertions and want those values masked, select the Mask all OGNL-expression generated log values checkbox.

  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.