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, see Configuring a PingID Adapter instance (Windows login).

About this task

Steps

  1. In the PingFederate administrative console:

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

    • PingFederate 10 and lower: 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 dropdown list, select the relevant PingID Adapter.

  4. On the IdP Adapter tab, in the PingID Properties field, click Choose File and navigate to the PingID properties file you downloaded earlier (see PingFederate).

    See Configure the PingID service for instructions if you’ve not yet configured the PingID service.

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

    This step enables the user email to be pre-populated in 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.

    • 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). For more information, see Defining the IdP adapter contract.

    • 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 is not enabled, features that rely on LDAP information may not work correctly.

    • Base Domain: The location that is used to search for the user, including subgroups. This attribute is equivalent to the Search Base attribute in Active Directory (e.g., 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 is not 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 is 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 PingOne 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 Usermay 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 of a user. Requires PID Adapter v2.7 or higher.

      This option prevents a full clean up of the user trace on the machine after SLO (single logout) and may 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 are 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 are 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.

  6. (Optional) On the Extended Contract tab, to add attributes to the contract, for each attribute you want to add, in theExtend the Contract area, type the name of the attribute and click Add, and when finished, click Next.

    For more information on using theExtended Contract screen, see Extend an IdP Adapter Contract.

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

    On theAdapter Attributes tab you also have the option to mask attribute values in PingFederate log files. See Attribute masking for more information

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

    1. Click Next, and then in the Adapter Contract Fulfillmenttab, 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.