PingFederate Server

Configuring an LDAP connection

In the Data Stores configuration window, establish an Lightweight Directory Access Protocol (LDAP) connection to your directory server.

Steps

  1. Go to System → Data & Credential Stores → Data Stores.

  2. On the Data Stores window, click Add New Data Store.

  3. On the Data Store Type tab, type a name for the datastore.

  4. From the Type list, select Directory (LDAP).

  5. Optional: To mask attribute values returned from this datastore in PingFederate logs, select the Mask Values in Log check box.

  6. Click Next.

  7. On the LDAP Configuration tab, configure your LDAP connection as described in the following table.

    Field Description

    Data Store Name

    The name of the datastore.

    This field is visible only when editing an existing datastore.

    Hostname(s)

    (Required)

    The network address of the directory server, either an IP address, a host name, or a fully qualified domain name. The entry might include a port number; for example, 10.10.10.101:1389. For failover, enter multiple directory servers, each separated by a space. In addition to network error conditions, PingFederate also fails over to the next server if the current server returns an LDAP system error.

    If multiple directory servers are specified, each server must be accessible by using the same user distinguished name (DN) and password (unless the Bind Anonymously check box is selected).

    You can add multiple hostnames. You can also specify which node is the default by clicking Set as Default under Action.

    PingFederate can also leverage DNS service records to locate the directory server (when the Use DNS SRV Record check box is selected), in which case the value of this field must be a single domain; for example, example.com.

    Tags

    Tags are defined in the node.tags property in the <pf_install>/pingfederate/bin/run.properties file. See Deploying cluster servers for a description of the node.tags property.

    In regional PingFederate deployments, you can enter one or more tags for a host name, which specify with which datastore that particular PingFederate node should communicate. If none of the tags match what is defined for the node.tags property, the default node is used.

    The following rules apply to tags:

    • You must separate multiple tags specified for one node with spaces.

    • You cannot use a tag more than once per datastore.

    • Tags are optional. If needed, you can configure a non-default node without tags. This is useful if you are not yet ready to tag the node, or if you are still in the planning stage but want to enter the address for the node now.

    Use LDAPS

    When selected, PingFederate connects to the directory server using LDAPS. This selection applies equally to all servers specified in the Hostname(s) field.

    You should secure all LDAP connections by using LDAPS.

    To enable the password changes, password reset, or account unlock features in the HTML Form Adapter against Microsoft Active Directory, you must secure the connection to your directory server using LDAPS; Microsoft Active Directory requires this level of security to allow password changes.

    This check box is cleared by default.

    Use DNS SRV Record

    Used in conjunction with the domain information defined in the Hostname(s) field and the preference of LDAP or LDAPS, PingFederate uses DNS SRV records to locate the directory server when this check box is selected. You can fine-tune the TTL value and the record prefixes on the Advanced LDAP Options window.

    When the DNS returns multiple SRV records, PingFederate uses the record with the lowest-numbered priority value and fails over to the record with the next lowest priority value. If multiple records share the same priority value, PingFederate uses the records with the highest-numbered weight value.

    PingFederate repeats this exercise until it establishes a connection or fails to connect to any directory server after taking all records into consideration.

    This check box is cleared by default.

    Follow LDAP Referrals

    Select this check box to let the datastore follow LDAP referrals on Microsoft Active Directory or Oracle Unified Directory.

    PingFederate always follows LDAP referrals from PingDirectory based on the recommended PingDirectory configuration.

    LDAP Type

    (Required)

    If you are using this datastore for outbound provisioning and your directory server is PingDirectory, Microsoft Active Directory or Oracle Unified Directory, select the applicable type from the list, such that PingFederate can pre-populate many provisioning settings on Outbound Provisioning → Channel → Source Settings.

    If your directory server is not PingDirectory, Microsoft Active Directory, or Oracle Unified Directory, you can define a custom LDAP Type to streamline the outbound provisioning configuration.

    The LDAP type is also used to enable password-change messaging between Microsoft Active Directory and PingFederate when an HTML Form Adapter instance is used.

    Authentication Method

    Select how PingFederate will authenticate with the directory server, which depends on the configuration of the directory server:

    • None (Anonymous): Select this option if your directory server supports anonymous binding and no credentials are needed to access the directory server.

      For inbound provisioning, because PingFederate needs to manage local user records, your directory server might require a specific service account to handle the communication between PingFederate and the target directory server. If you choose an anonymous binding, ensure that this access level provides permission to search the directory for user-account information.

    • Simple: Select this option if the directory server requires PingFederate to provide a user domain name (DN) and password to authenticate.

    After selecting this option, select a Credential Storage option: Internally Managed or Secret Manager. Then specify the User DN and either the Password or Password Reference. [.uicontrol]Client TLS Certificate: This option is available if you selected [.uicontrol]Use LDAPS. Select this option when using mutual TLS (mTLS) authentication. PingFederate authenticates by presenting the client transport layer security (TLS) certificate that you select in the [.uicontrol]Client Certificate** list.

    Credential Storage

    Select whether PingFederate with store the credentials internally or in a secret manager. For more information, see Secret managers.

    These settings are visible only when Authentication Method is set to Simple.

    User DN

    The user name credential required to access the directory server. This field is visible only when Authentication Method is set to Simple.

    The service account must have permission to search the directory for user-account information. If your use cases involve reading from the directory server without creating, updating, or deleting any records, consider using a service account with read-only access.

    For inbound provisioning, a service account with permission to create, read, update, and delete users and groups is required.

    When connecting to a Microsoft Active Directory server, enter a Microsoft Active Directory user account. Do not use a computer account.

    When connecting to PingDirectory or Oracle Unified Directory, configure proxied authorization for the service account on the directory server if you intend to enable self-service password reset in any HTML Form Adapter instances that use this datastore. For more information, see Proxied authorization.

    Password

    The credential required to access the directory server for simple authentication.

    This field is visible only when Authentication Method is set to Simple and Credential Storage is set to Internally Managed.

    Password Reference

    The reference code PingFederate uses to retrieve the password it needs to access the directory server for simple authentication.

    This field is visible only when Authentication Method is set to Simple and Credential Storage is set to Secret Manager. For information about generating a password reference code, see Using passwords in secret managers to access datastores.

    Client Certificate

    Select the client TLS certificate that PingFederate will present to the directory server for authentication. This list is visible only when Authentication Method is set to Client TLS Certificate.

    If you have not yet created or imported a client certificate, click the Manage SSL Client Keys & Certificates button to do so. For more information, see Manage SSL client keys and certificates.

    Mask Values in Log

    Determines whether all attribute values returned through this datastore should be masked in PingFederate logs.

    This check box is visible only when editing an existing datastore.

  8. Click Test Connection to determine whether the administrative node can communicate with the specified datastore.

    • Datastore validation is not enabled during configuration, which lets you configure datastores without requiring a successful connection between the administrative node and the datastore. You can also save the datastore even if the connection is not currently successful.

    • Due to the implementation of Client TLS Certificate Authentication in Active Directory, when the LDAP Type is Active Directory and the Authentication Method is Client TLS Certificate, the connection test always succeeds, even when an incorrect certificate is selected. This is not the case when PingFederate attempts to retrieve data from the datastore because the connection will fail to bind.

  9. Optional: Click Advanced. If you choose an anonymous binding, configure additional settings in the Advanced LDAP Options window Click Save.

    Result:

    You are directed back to the LDAP Configuration tab.

  10. On the Summary tab, click Save.