Working with pass-through authentication

The PingDirectory server provides support for passing through LDAP simple bind attempts to an external service for authentication processing, either instead of or in addition to the processing that it typically performs against the locally stored data.

Pass-through authentication can be useful when migrating to the PingDirectory server from a different type of datastore, especially when that datastore doesn’t provide a means of directly migrating passwords.

The server provides pass-through authentication support for other LDAP servers (including Active Directory (AD), Oracle DSEE, OpenLDAP, and any other standards-compliant LDAPv3 server) and PingOne by default. You can also use the Server SDK to implement support for custom pass-through authentication handlers for interacting with other types of external services.

Configuration properties for pass-through authentication to LDAP servers

When used with the LDAP pass-through authentication handler, the pluggable pass-through authentication plugin can forward LDAP simple bind requests to another type of LDAP server for processing.

The following table contains the pluggable pass-through authentication plugin configuration properties.

Property Description

Property	Description
`pass-through-authentication-handler`	The pass-through authentication handler that is used to interact with the external service. For passing through authentication to an LDAP directory server, create an LDAP pass-through authentication handler.
`included-local-entry-base-dn`	The base distinguished names (DNs) of subtrees containing local entries for which pass-through authentication is attempted. If this isn’t provided, then all regular user entries (excluding root users and topology administrators) might be passed through.
`connection-criteria`	Optional connection criteria that can be used to indicate which clients can have their bind attempts passed through.
`request-criteria`	Optional request criteria that can be used to indicate which bind requests should be passed through.
`try-local-bind`	Indicates whether to try the bind attempt against the entry in the local server, only passing through to the external service if the local attempt fails. If this is `false`, then only pass-through authentication is used for applicable requests and local credentials aren’t evaluated.
`override-local-password`	Indicates whether to pass through bind attempts for local accounts that have passwords. If this is set to `false`, bind attempts will only be passed through for accounts that don’t have local passwords. This only applies if `try-local-bind` is `true`.
`update-local-password`	Indicates whether to update the password for the local account if authentication succeeds against the external service. This only applies if `try-local-bind` is `true`.
`update-local-password-dn`	The DN to use as the authorization identity when updating local passwords, which can be helpful if you want to synchronize other types of changes between the PingDirectory server and the external repository. If this isn’t provided, an internal root account is used.
`allow-lax-pass-through-authentication-passwords`	Indicates whether to update the password for the local account even if it wouldn’t have otherwise been accepted by the server (for example, if the password doesn’t satisfy the configured set of password validators). This only applies if `update-local-password` is `true`.
`ignored-password-policy-state-error-condition`	Optionally allows pass-through authentication attempts to proceed against local accounts that are in certain states that don’t allow them to authenticate locally (for example, if the account is locked or the password is expired).

pass-through-authentication-handler

The pass-through authentication handler that is used to interact with the external service.

For passing through authentication to an LDAP directory server, create an LDAP pass-through authentication handler.

included-local-entry-base-dn

The base distinguished names (DNs) of subtrees containing local entries for which pass-through authentication is attempted. If this isn’t provided, then all regular user entries (excluding root users and topology administrators) might be passed through.

connection-criteria

Optional connection criteria that can be used to indicate which clients can have their bind attempts passed through.

request-criteria

Optional request criteria that can be used to indicate which bind requests should be passed through.

try-local-bind

Indicates whether to try the bind attempt against the entry in the local server, only passing through to the external service if the local attempt fails.

If this is false, then only pass-through authentication is used for applicable requests and local credentials aren’t evaluated.

override-local-password

Indicates whether to pass through bind attempts for local accounts that have passwords.

If this is set to false, bind attempts will only be passed through for accounts that don’t have local passwords. This only applies if try-local-bind is true.

update-local-password

Indicates whether to update the password for the local account if authentication succeeds against the external service.

This only applies if try-local-bind is true.

update-local-password-dn

The DN to use as the authorization identity when updating local passwords, which can be helpful if you want to synchronize other types of changes between the PingDirectory server and the external repository.

If this isn’t provided, an internal root account is used.

allow-lax-pass-through-authentication-passwords

Indicates whether to update the password for the local account even if it wouldn’t have otherwise been accepted by the server (for example, if the password doesn’t satisfy the configured set of password validators).

This only applies if update-local-password is true.

ignored-password-policy-state-error-condition

Optionally allows pass-through authentication attempts to proceed against local accounts that are in certain states that don’t allow them to authenticate locally (for example, if the account is locked or the password is expired).

The following table contains the LDAP pass-through authentication handler configuration properties.

Property Description

Property	Description
`server`	The LDAP external servers to which bind attempts should be passed through.
`server-access-mode`	The mechanism that the server should use when choosing the order that the servers should be selected for pass-through authentication attempts.
`dn-map`	An optional mapping that can be used to construct the remote bind DN from the local PingDirectory server entry when authenticating to the external servers.
`bind-dn-pattern`	An optional pattern that can be used to construct the remote bind DN from the local PingDirectory server entry when authenticating to the external servers.
`search-base-dn`	The search base DN to use when searching for the corresponding entry in the external servers.
`search-filter-pattern`	An optional pattern you can use to construct a filter to search for the entry in the external servers that corresponds to an entry in the local PingDirectory server.
`initial-connections`	The initial number of connections to establish to each of the LDAP external servers.
`max-connections`	The maximum number of connections to maintain to each of the LDAP external servers.
`use-location`	Indicates whether to consider each server’s location relative to the local PingDirectory server instance location when choosing the order that servers should be selected for pass-through authentication attempts.
`maximum-allowed-local-response-time`	The maximum length of time to wait for a response from an external server in the same location as the local PingDirectory server.
`maximum-allowed-nonlocal-response-time`	The maximum length of time to wait for a response from an external server in a different location from the local PingDirectory server.
`use-password-policy-control`	Indicates whether to include the password policy request control in bind requests forwarded to the external LDAP servers. This control can improve the server’s ability to categorize authentication failures against the remote server, but not all types of LDAP servers support it. By default, the server includes the password policy request control if the server’s root DSA-specific entry (DSE) advertises support for it.

server

The LDAP external servers to which bind attempts should be passed through.

server-access-mode

The mechanism that the server should use when choosing the order that the servers should be selected for pass-through authentication attempts.

dn-map

An optional mapping that can be used to construct the remote bind DN from the local PingDirectory server entry when authenticating to the external servers.

bind-dn-pattern

An optional pattern that can be used to construct the remote bind DN from the local PingDirectory server entry when authenticating to the external servers.

search-base-dn

The search base DN to use when searching for the corresponding entry in the external servers.

search-filter-pattern

An optional pattern you can use to construct a filter to search for the entry in the external servers that corresponds to an entry in the local PingDirectory server.

initial-connections

The initial number of connections to establish to each of the LDAP external servers.

max-connections

The maximum number of connections to maintain to each of the LDAP external servers.

use-location

Indicates whether to consider each server’s location relative to the local PingDirectory server instance location when choosing the order that servers should be selected for pass-through authentication attempts.

maximum-allowed-local-response-time

The maximum length of time to wait for a response from an external server in the same location as the local PingDirectory server.

maximum-allowed-nonlocal-response-time

The maximum length of time to wait for a response from an external server in a different location from the local PingDirectory server.

use-password-policy-control

Indicates whether to include the password policy request control in bind requests forwarded to the external LDAP servers.

This control can improve the server’s ability to categorize authentication failures against the remote server, but not all types of LDAP servers support it.

By default, the server includes the password policy request control if the server’s root DSA-specific entry (DSE) advertises support for it.

At most one of the dn-map, bind-dn-pattern, and search-filter-pattern properties can be provided to indicate how the server should identify the entry in the remote server that corresponds to the entry in the local server. If none of these properties are provided, the local entry DN is used as the remote entry DN.