The PingOne Pass-Through Authentication plugin

The PingOne Pass-Through Authentication plugin allows users to authenticate to the PingDirectory server with a password from PingOne and can optionally update the passwords in PingDirectory after successfully validating it in PingOne.

Although the PingDataSync server supports bidirectional synchronization between the PingDirectory server and PingOne, and it can synchronize password changes from PingDirectory to PingOne, it can’t sync password changes from PingOne to PingDirectory. However, you can use the PingOne Pass-Through Authentication plugin to authenticate to the PingDirectory server with a PingOne password, and can optionally update the password in PingDirectory after successfully validating it in PingOne.

This plugin features a mandatory try-local-bind configuration property that enables one of the following modes of operation:

When try-local-bind is true, the plugin attempts to authenticate locally first. It sends a request to PingOne only if the local bind attempt fails.
When try-local-bind is false, the plugin attempts to authenticate with PingOne first.

The following table identifies and describes the configuration properties associated with the PingOne Pass-Through Authentication plugin.

The PingOne Pass-Through Authentication plugin properties and their descriptions
Property	Description	Required	Default
`api-url`	URL that the PingDirectory server uses to communicate with PingOne.	Yes	N/A
`auth-url`	URL that the PingDirectory server uses to authenticate to PingOne.	Yes	N/A
`oauth-client-id`	OAuth client ID that the PingDirectory server uses to authenticate to PingOne.	Yes	N/A
`oauth-client-secret`	OAuth client secret that the PingDirectory server uses to authenticate to PingOne.	Yes	N/A
`environment-id`	Identifier for the PingOne environment that contains the users for whom pass-through authentication is attempted.	Yes	N/A
`included-local-entry-base-dn`	If this value is set, authentication attempts are passed to PingOne only for users in a specified distinguished name (DN). If this value is set, only users who exist within a specified base DN allow their authentication attempts to be passed through to PingOne.	No	All public naming contexts (if not set)
`connection-criteria`	Reference to a connection criteria object to use to identify the bind requests to pass-through to PingOne based on the server’s knowledge of the client expected to be the address, protocol, and security level. If this property is defined, only client connections that match the criteria are included. If this property is not defined, all clients are included.	No	N/A
`request-criteria`	Reference to a request criteria object to use to identify the bind requests to pass through to PingOne, based on the contents of the request. If this property is defined, only bind requests that match the criteria are included. If this property is not defined, all bind requests are included.	No	N/A
`try-local-bind`	Indicates whether the PingDirectory server tries to process the bind locally before forwarding the bind request to PingOne. If this value is set to `true` and the bind succeeds locally, the PingDirectory server does not make a request to PingOne. If this value is set to `false`, the PingDirectory server ignores local credentials and attempts to authenticate only to PingOne.	Yes	`True`
`override-local-password`	Indicates whether the PingDirectory server attempts to bind to PingOne if the local account has a password. This property is used if `try-local-bind` is `true`. If it has a value of `false`, the plugin attempts to authenticate to PingOne only if the local user account doesn’t have a password. If the local bind attempt fails while this value is set to `true`, the server tries to authenticate to PingOne even if the local account has a password.	Yes	`True`
`update-local-password`	Indicates whether the PingDirectory server attempts to set the password for the local user account, regardless of whether one is already set, when the local authentication attempt fails but the attempt to authenticate with PingOne succeeds. This property is used only if `try-local-bind` is `true`. If the on-premise PingDirectory server is the authoritative source for passwords, set this property to `false` and configure the PingDataSync server to synchronize password changes from the PingDirectory server into PingOne. If the passwords differ, either the local password or the password for PingOne allows the user to authenticate. If PingOne is the authoritative source for passwords, set this property to `true`. To ensure that a pass-through attempt to PingOne doesn’t override local changes, make all password changes in PingOne.	Yes	`False`
`allow-lax-pass-through-authentication-passwords`	Indicates whether the PingDirectory server bypasses the normal password-validation process when setting the local password from PingOne. This property is used only when both `try-local-bind` and `update-local-password` are `true`. If this value is `true` when a local bind attempt fails but the authentication attempt with PingOne succeeds, the user’s password is updated locally even if a local attempt to change the password to the same value is rejected because the password is considered too weak. If this value is `false`, pass-through authentication succeeds only if the authentication to PingOne succeeds, and if the password is accepted by the local password validators. If the PingOne password does not satisfy the configured set of password validators, the pass-through authentication attempt fails.	Yes	`True`
`ignored-password-policy-state-error-condition`	Set of zero or more password policy state error conditions that are ignored for pass-through authentication. For a list of values and their descriptions, see the following table.	No	N/A
`user-mapping-local-attribute`	Name of an LDAP attribute that is used to map local user entries to the corresponding PingOne account. This property must include the same number of values as the `user-mapping-remote-json-field` property, and the order of their values is correlated. If multiple values are specified, all attributes must be present in the local entry, and the plugin performs an `AND` search in PingOne to locate the user account with all the values in the corresponding fields. The `entryDN` attribute can be used to represent the DN of the local entry.	Yes	N/A
`user-mapping-remote-json-field`	The name of a PingOne field used to map local user entries to the corresponding PingOne account. This property must include the same number and order of values as the `user-mapping-local-attribute` property.	Yes	N/A
`additional-user-mapping-scim-filter`	The System for Cross-domain Identity Management (SCIM) filter included in the search and used to identify the PingOne account that corresponds to the local user entry. If a value is provided for this property, it is used with the SCIM filter that was created to map the local user entry to a PingOne account. If a value is not provided for this property, no additional filter is used.	No	N/A

The following table identifies the values to use with the optional configuration property ignored-password-policy-state-error-condition and describes the scenarios in which a user is permitted to bind when using pass-through authentication.

Optional configuration property and the scenarios for use when using pass-through authentication
Property	Scenario in which a user can still bind by using pass-through authentication
`temporarily-locked-due-to-failures`	The account is locked temporarily because of too many failed attempts.
`permanently-locked-due-to-failures`	The account is locked permanently because of too many failed attempts.
`locked-due-to-idle-interval`	The account is locked because the user has not authenticated recently.
`locked-due-to-maximum-reset-age`	The account is locked because an administrator recently reset the password, and the user failed to specify a new password within the allotted time frame.
`password-is-expired`	The password is expired.

ExampleConfiguring the PingOne Pass-Through Authentication plugin

To create and configure the PingOne Pass-Through Authentication plugin, run dsconfig create-plugin in a command similar to the following.

dsconfig create-plugin \
     --plugin-name "PingOne Pass-Through Authentication" \
     --type ping-one-pass-through-authentication \
     --set enabled:true \
     --set "api-url:<API URL>" \
     --set "auth-url:<Auth URL>" \
     --set "oauth-client-id:<Client ID>" \
     --set "oauth-client-secret:<Client Secret>" \
     --set "environment-id:<Environment ID>" \
     --set user-mapping-local-attribute:entryUUID \
     --set user-mapping-remote-json-field:externalId