PingFederate Server

Configuring a Composite Adapter instance

Configuring a Composite Adapter instance allows you to enable adapter chaining for a user authentication connection.

About this task

Configure an instance of a Composite Adapter in PingFederate using the administrative console.

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 Composite Adapter instance as follows:

    1. Click Add a new row to 'Adapters'.

    2. From the Adapter Instance list, select an IdP adapter instance. Click Update.

      For more information, see the Description column in each configuration section and the following table.

      PingFederate’s column names and descriptions for creating an adapter instance
      Column Description

      Policy

      (Required)

      Required (the default) indicates authentication through this adapter instance is needed to continue SSO processing and to invoke any remaining instances in the chain. If you are integrating multifactor authentication, use this policy for each instance. The Composite Adapter instance returns an error when the authenticate attempt against a required adapter instance fails.

      Sufficient indicates that authentication through this adapter instance is enough to satisfy requirements, along with any required instances that have already been selected. Any subsequent configured instances in the chain are not invoked.

      For the sufficient policy to work correctly, the adapter must return control to PingFederate after any kind of a failure.

      AuthN Context Weight

      (Required)

      If more than one adapter instance in the chain is capable of returning an authentication context, this relative weight is used to determine which value is included in the assertion, unless the value is overridden under AuthN Context Override.

      If weights are the same for two or more contexts, the first one processed is included in the assertion.

      The default value is 3.

      AuthN Context Override

      If provided, this value overrides the authentication context value that might be returned from the adapter instance. The value in this field can be sent in the assertion if the associated adapter instance is invoked.

      If weights are the same for two or more contexts, the first one processed is included in the assertion.

    3. Add at least one more adapter instance and configure its Policy, AuthN Context Weight, and AuthN Context Override settings.

      Repeat this step to add more adapter instances as needed.

      At runtime adapter chaining is sequential, starting at the top of the list.

      You can configure several types of adapters — for example, the IWA IdP Adapter — to direct end users to an error page if authentication fails for any reason, which will halt further progress through a composite-adapter chain. For such adapter instances, ensure the Error URL option is not used in the instance configuration when continuation through an adapter-chaining sequence is required.

    4. Optional: In the Action column, manage the selected adapter instances.

    5. Configure Input User ID Mapping.

      If you have configured any IdP Adapter developed using the IdpAuthenticationAdapterV2 interface from the PingFederate SDK, including the HTML Form Adapter, the Input User ID Mapping section appears. Additionally, some IdP adapters, such as the PingID Adapter and the separately available Symantec VIP Adapter, require a user ID to be passed in from an earlier-authentication step to perform multifactor authentication. If so, an administrator must specify the attribute containing the unique ID on this window. For example, to pre-populate the username of an HTML Form Adapter instance with an attribute from an earlier authentication source in the previous steps:

      1. Click Add a new row to 'Input User ID Mapping'.

      2. From the Target Adapter list, select the HTML Form Adapter instance.

      3. From the User ID Selection list, select a source attribute.

      4. Click Update.

        For OAuth use cases, entries in the Input User ID Mapping section might override the login_hint parameter value provided by the OAuth clients when they submit their requests to the /as/authorization.oauth2 authorization endpoint.

        By default, the HTML Form Adapter does not allow the users to change the username if it is configured to be pre-populated with an attribute from another authentication source. You can override this restriction by enabling the Allow Username Edit option on a per-adapter instance.

    6. Configure Attribute Name Synonyms.

      If any attributes are logically equivalent across two adapter instances but have different names, click Add a new row to 'Attribute Name Synonyms'. Select attributes from the Name and Synonym lists to create a mapping between them.

      The attribute name under Synonym and its value are used in the SAML assertion when the two values returned from each adapter are identical. If returned values are different, both values are sent for the synonym.

      Without this configuration to identify synonymous attribute names, both names and their values are sent in the SAML assertion.

    7. Define the order in which different values are returned for the same attribute name.

      For attributes of the same name configured in different adapter instances, you can change the order of returned values when the values are different. (Values are merged if they are the same.)

      By default, the Add to Back value for an attribute name configured in the first instance is returned first and also listed first in the resulting SAML assertion. Then any different value from the same attribute name in a subsequently invoked instance is appended.

      The order might not matter for many attributes, but in the case of the SAML-subject attribute, only the first value in the SAML assertion can be used for an SP connection partner under normal circumstances. Click Add to Front to reverse the default order, if needed.

  5. On the Extended Contract tab, click Add to add attributes to be returned from each adapter instance configured on the previous window.

    Attributes must correspond exactly to any or all of the attribute names listed on the Adapter Attribute tab for each configured adapter instance.

  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. (Optional) 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. 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.