PingID Administration Guide

Configuring a PingID adapter instance

This topic describes how to configure a PingID Adapter instance.

Before you begin

To configure a PingID Adapter instance for integrating PingID with Windows login through PingFederate, refer to Configuring a PingID Adapter instance (Windows login).

To configure a PingID Adapter instance for a passwordless authentication experience with the PingID desktop app or FIDO2 passkeys:

About this task

  • If an IdP adapter for primary authentication hasn’t already been created, create one (refer to Configure an IdP adapter instance).

  • (Optional) If you want to override the default application name or application icon that the user sees when authenticating, follow the instructions in Identify the target application in the PingFederate documentation.

Steps

  1. On the PingFederate administrative console:

    • PingFederate 10.1 and later: Click Authentication, and select IdP Adapters.

    • PingFederate 10 and earlier: UnderIdentity Provider in the INTEGRATION area, click Adapters.

  2. On the IdP Adapter Instances window, click Create New Instance.

  3. On the Type tab, enter the following information, and then click Next:

    • Instance Name: The name you want to use to identify the adapter instance.

    • Instance ID: The adapter ID. This ID is for internal use and cannot contain spaces or non-alphanumeric characters.

    • Type: In the list, select the relevant PingID Adapter.

  4. To connect the legacy PingID authenticator, on the IdP Adapter tab, in the PingID Properties field, click Choose File and navigate to the PingID properties file you downloaded earlier (refer to PingFederate).

    Refer to Configure the PingID service for instructions if you haven’t yet configured the PingID service.

  5. If you’re using LDAP to retrieve user information, click Show Advanced Fields, enter the information for the relevant fields, and then click Save.

    This step enables the user email to be pre-populated on the mobile device registration page, and saves the user details, (including first name and last name), in the user listing for the PingID service.

    • LDAP fields supply profile information to the PingID mobile device during registration (pairing a mobile device).

    • LDAP attribute fields are case sensitive.

    This step is also required if you want to use group-based policies.

    • LDAP Data Source (optional): Select a configured LDAP data store.

      If you want greater flexibility, you can set the value of LDAP Data Source to "chained attributes". An example of where you can use this approach is to write OGNL expressions to define custom user groups that can be used in PingID policies (in addition to those groups defined in the directory). Find more information in Defining the IdP adapter contract in the PingFederate documentation.

    • Query Directory (optional): The LDAP query for user information is done for every request. If this option isn’t enabled, the query is only made when a PingID user cookie is not found.

      If this flag isn’t enabled, features that rely on LDAP information may not work correctly.

    • Base Domain: The location that' i’s used to search for the user, including subgroups. This attribute is equivalent to the Search Base attribute in Active Directory (for example, Base Domain: CN=Users,DC=domainname,DC=global).

      The Base Domain path must include at least one group, as well as the DC.

    • Filter: LDAP attribute used to find the LDAP entry for a specific user entity. If thePingID User Attribute isn’t defined, the attribute is also used to represent the username in PingID. For example, userPrincipalName=${username}..

    • LDAP Search Scope:

      • OBJECT_SCOPE: Limits the search to the base object.

      • ONELEVEL_SCOPE: Searches the immediate children of a base object, but excludes the base object itself.

      • SUBTREE_SCOPE (Default) : Searches all child objects as well as the base object.

    • Fname Attribute: The attribute containing the user first name. For example, givenName.

    • Lname Attribute: The attribute containing the user last name. For example, sn.

    • PingID User Attribute: The LDAP attribute used to represent the username in PingID (for example, User Principal Name (UPN), sAMAccountName or objectGUID). The value is taken from the user entity identified by the Filter attribute. If this field is blank, the Filter attribute is used.

    • Email Attribute: The attribute containing the user email address. For example, mail. This email address is used during registration if users need to receive a link on their mobile device to download the PingID application.

    • Secondary Email Attribute: An additional LDAP attribute that can be used for Email messages.

    • Group Attribute: The LDAP attribute for group membership.

    • Phone Attribute: The LDAP attribute of the phone number used for SMS messages, as well as voice calls if Voice Number attribute is left empty.

      This attribute must use the Google Library format, which dictates that all phone numbers must include ‘+’, as well as the international country code.

    • Secondary Phone Attribute: An additional LDAP attribute that can be used for SMS messages. If the Secondary Voice Attribute is undefined, this attribute ​is used for voice calls.

    • YubiKey Attribute: The LDAP attribute for YubiKey (for future use).

    • Voice Number Attribute: The LDAP attribute of the phone number used for voice calls. If left empty, the Phone Attribute is used for voice calls.

      This attribute must use the Google Library format, which dictates that all phone numbers must include ‘+’, as well as the international country code.

    • Secondary Voice Attribute: An additional LDAP attribute that can be used for ​Voice calls. If th​is attribute is undefined, the Secondary ​Phone​ Attribute is used for voice calls.

    • State Attribute: The LDAP attribute that’s preset in Active Directory, which is used to override how a specific user is authenticated during offline authentication.

    • PingID Heartbeat Timeout: (optional) Specify how many seconds to wait for a response when verifying the PingID and PingID services. If not specified, the default is 30 seconds. If set to 0, the system default is used.

    • Authentication During Errors: Determines how to handle user authentication requests when PingID services are unavailable. Options include:

      • Bypass User: Accept the user’s first factor authentication, and bypass the PingID MFA flow when the PingID MFA service is unavailable.

        Requiring PingID registration while also allowing Bypass User might result in users being redirected to the next link in the PingFederate policy tree during a PingID service outage.

      • Block User: Reject and block the user’s login attempt when the PingID MFA service is unavailable.

      • Passive Offline Authentication: Fallback to the PingID offline MFA flow when the PingID MFA service is unavailable. Users will be asked to scan a QR code with a mobile device previously registered with PingID to obtain an authentication code to authenticate.

      • Enforce Offline Authentication: Force PingID offline MFA flow regardless of the PingID MFA service availability.

        In PingID Adapter versions older than v2.0 the Authentication During Errors property is called Bypass PingID During Errors, and if enabled, its meaning is the same as Bypass User.

    • Users without a paired device: When PingID services are unavailable, choose to bypass or block users if they don’t have a paired mobile device:

      • Bypass: bypass the PingID MFA flow when the PingID MFA service is unavailable and the user does not have a paired device.

      • Block: Reject and block the user’s login attempt when the PingID MFA service is unavailable, and the user does not have a paired device.

    • LDAP Data Source for Devices: The LDAP data source used for device attributes during offline authentication.

    • Encryption Key for Devices: The Base64url encoded 256 bit key. Used to optionally encrypt the users devices list before saving to LDAP.

    • Distinguished Name Pattern: The pattern the adapter uses to save device entries. This field is required only if the offline authentication is enabled and the offline authentication LDAP is different from the users LDAP. Example: CN=${username},OU=PingID-Devices,DC=myDomain,DC=com.

    • HTML Template: The HTML template displayed to the user during offline authentication.

    • Cookie Duration: The duration of the cookie (in days) before it expires. The default value is 1 day.

    • PingID Properties File Name: Ensure the PingID Properties file is unique.

      The PingID properties file name must be unique for each adapter instance. This value is automatically assigned during the adapter configuration process, but when you create a hierarchical adapter configuration it doesn’t reset automatically to a unique value.

    • Keep cookies at sign-off: Prevents PingID cookies from being cleared during single logout (SLO) of a user. Requires PID Adapter v2.7 or later.

      This option prevents a full clean up of the user trace on the machine after SLO and could expose your user accounts to additional security risks. This option should only be used with full understanding of the security implications.

    • Refresh UserId Cookie: Refresh UserId cookie after a successful authentication. By default this option is unchecked.

    • Require PingID Registration (optional): If the checkbox is selected, users that do not have at least one device paired with their account are blocked, until they successfully pair a device with their account.

    • Risk Level (optional): If you’re using a third-party risk management service, set the value of this parameter to the name that was set in the adapter for the service.

    • Resource ID (optional): If you’re using the PingOne Protect integration with PingFederate, this should be the name that you entered under PingOne Risk API Response Mapping or PingOne Protect API Response Mapping, on the relevant Adapter settings page.

    • PingOne Environment (optional): To define the PingOne environment that you want to integrate with PingFederate when configuring PingFederate policy for a consistent passwordless authentication experience, select the relevant PingOne connection.

      This field is only relevant when configuring a PingFederate policy for a consistent passwordless experience.

    • Conditional UI: Select the mode for selectively displaying passkeys and WebAuthn sign-on processes:

      This field is only relevant when configuring a PingFederate policy for a consistent passwordless experience.

      • Disabled: Disable all conditional UI features in the sign-on HTML form.

      • Optional: If a passkey exists in the current domain, automatically display a WebAuthn modal prompting the user to select it when the sign-on page renders.

      • Conditional: When the user clicks the Username field, show a list of available passkeys as auto-fill sign-on options.

  6. (Optional) To add an attribute to the contract, on the Extended Contract tab, in the Extend the Contract area, enter the name of the attribute and click Add. Repeat this step for all attributes you want to add and then click Next.

    You can find more information on using the Extended Contract window in Extend an IdP Adapter Contract in the PingFederate documentation.

  7. On the Adapter Attributes tab in the Pseudonym column, select the checkbox for the subject attribute to be used as the expected identifier, then click Next.

    On the Adapter Attributes tab you also have the option to mask attribute values in PingFederate log files. Learn more in Attribute masking in the PingFederate documentation.

  8. On the Adapter Contract Mapping tab, click Configure Adapter Contractand then in theAdapter Contract Mapping window:

    1. Click Next, and then in the Adapter Contract Fulfillment tab, for each contract attribute, select the relevant Source value with which to fulfill your adapter contract.

  9. Click Next, and then Next again to move to the Summary tab. Verify the information is correct and then click Done.

  10. Click Next again, and then on the Summary tab, verify that the information is correct and click Done to return to the Create Adapter Instance screen.

  11. Click Next, then Done, and then Save. The new adapter instance is saved.