The Pass Through Authentication Plugin may be used to allow simple bind attempts to be passed through to an external LDAP server. It may be used to either pass through all authentication attempts instead of processing them locally, or to only pass through attempts if a local bind attempt fails. In the event that a local bind fails but a passed-through attempt succeeds, then it may optionally update the local password to match the successful remote attempt.
Only one instance of this plugin may be active in the server at any time. It cannot be used in conjunction with other pass-through authentication plugins, including another instance of the original LDAP pass-through authentication plugin, the PingOne pass-through authentication plugin, or the pluggable pass-through authentication plugin. If you need multiple types of pass-through authentication active in the server at one time, use the pluggable pass-through authentication plugin with the aggregate pass-through authentication handler.
If multiple external servers are defined, then the server-access-mode property may be used to indicate how servers are selected. If the Directory Server and all associated external servers all have locations defined, then the selection process will favor external servers in the same location as the Directory Server, and then remote servers in the order specified by the preferred-failover-location property for the location used by this Directory Server.
The Pass Through Authentication Plugin component inherits from the Plugin
The following components have a direct aggregation relation from Pass Through Authentication Plugins:
The properties supported by this managed object are as follows:
| Description | A description for this Plugin |
| Default Value | None |
| Allowed Values | A string |
| Multi-Valued | No |
| Required | No |
| Admin Action Required | None. Modification requires no further action |
| Description | Indicates whether the plug-in is enabled for use. |
| Default Value | None |
| Allowed Values | true false |
| Multi-Valued | No |
| Required | Yes |
| Admin Action Required | None. Modification requires no further action |
| Description | Specifies the LDAP external server(s) to which authentication attempts should be forwarded. |
| Default Value | None |
| Allowed Values | The DN of any LDAP External Server. |
| Multi-Valued | Yes |
| Required | Yes |
| Admin Action Required | None. Modification requires no further action |
| Description | Indicates whether the bind attempt should first be attempted against the local server. Depending on the value of the override-local-password property, the bind attempt may then be attempted against a remote server if the local bind fails. |
| Default Value | true |
| Allowed Values | true false |
| Multi-Valued | No |
| Required | Yes |
| Admin Action Required | None. Modification requires no further action |
| Description | Indicates whether the bind attempt should be attempted against a remote server in the event that the local bind fails but the local password is present. This option will only be used if the try-local-bind property has a value of "true". |
| Default Value | false |
| Allowed Values | true false |
| Multi-Valued | No |
| Required | Yes |
| Admin Action Required | None. Modification requires no further action |
| Description | Indicates whether the local password value should be updated to the value used in the bind request in the event that the local bind fails but the remote bind succeeds. This option will only be used if the try-local-bind property has a value of "true". |
| Default Value | false |
| Allowed Values | true false |
| Multi-Valued | No |
| Required | Yes |
| Admin Action Required | None. Modification requires no further action |
allow-lax-pass-through-authentication-passwords
| Description | Indicates whether updates to the local password value should accept passwords that do not meet password policy constraints. This option will only be used if the try-local-bind property is true and the update-local-password property is true. Setting this property to true will allow the local password to be updated even if the pass through authentication password does not meet all of the password policy constraints, for example, the password strength or password history requirements. Setting this property to false and attempting a bind with a pass through authentication password causing an update to the local password where the password does not meet local password policy constraints will result in a failure to bind. |
| Default Value | true |
| Allowed Values | true false |
| Multi-Valued | No |
| Required | No |
| Admin Action Required | None. Modification requires no further action |
| Description | Specifies the manner in which external servers should be used for pass-through authentication attempts if multiple servers are defined. |
| Default Value | round-robin |
| Allowed Values | round-robin - Bind attempts to external servers should be spread evenly across all defined external servers (in a location-aware manner if appropriate). Any single bind request will only be attempted on multiple servers if earlier attempts were to a server that was unavailable. failover-on-unavailable - All bind attempts will be sent to the same server (in a location-aware manner if appropriate) and will only be attempted on other servers if the primary server is unavailable. failover-on-any-failure - All bind attempts will be sent to the same server (in a location-aware manner if appropriate). In the event that the first server is unavailable, or if the bind attempt fails on that server, then it will be attempted on the next server in the list, and binds will be re-tried on different servers until all servers have been exhausted. |
| Multi-Valued | No |
| Required | Yes |
| Admin Action Required | None. Modification requires no further action |
| Description | The base DNs for the local users whose authentication attempts may be passed through to an alternate server. If one or more base DNs are specified, then only binds attempted by users at or below one of those base DNs may be passed through to an alternate server. If no base DNs are specified, then all public naming contexts will be used as the default set of base DNs. |
| Default Value | None |
| Allowed Values | A valid DN. |
| Multi-Valued | Yes |
| Required | No |
| Admin Action Required | None. Modification requires no further action |
| Description | Specifies one or more DN mappings that may be used to transform bind DNs before attempting to bind to the external servers. Note that while there is a significant amount of overlap between the capabilities of the dn-map and bind-dn-pattern properties, there are also key differences between them. Both mechanisms can be used to construct the bind DN to use to authenticate to an external server using a combination of static text and attribute values from the target user's entry. However, a DN map can also use information from the original bind DN in constructing the remote bind DN, while a bind DN pattern can be used if you need to construct a remote bind DN that is not actually a valid LDAP distinguished name (e.g., if you want ot use a user principal name to authenticate to an Active Directory server). At most one of the dn-map, bind-dn-pattern, and search-filter-pattern properties may be present in the configuration. If none of these properties is present, then the bind DN used in the original bind request will also be used as the bind DN when authenticating to the remote server. |
| Default Value | None |
| Allowed Values | The DN of any DN Map. |
| Multi-Valued | Yes |
| Required | No |
| Admin Action Required | None. Modification requires no further action |
| Description | A pattern to use to construct the bind DN for the simple bind request to send to the remote server. This may consist of a combination of static text and attribute values and other directives enclosed in curly braces. For example, the value "cn={cn},ou=People,dc=example,dc=com" indicates that the remote bind DN should be constructed from the text "cn=" followed by the value of the local entry's cn attribute followed by the text "ou=People,dc=example,dc=com". If an attribute contains the value to use as the bind DN for pass-through authentication, then the pattern may simply be the name of that attribute in curly braces (e.g., if the seeAlso attribute contains the bind DN for the target user, then a bind DN pattern of "{seeAlso}" would be appropriate). Note that a bind DN pattern can be used to construct a bind DN that is not actually a valid LDAP distinguished name. For example, if authentication is being passed through to a Microsoft Active Directory server, then a bind DN pattern could be used to construct a user principal name (UPN) as an alternative to a distinguished name. Note that while there is a significant amount of overlap between the capabilities of the dn-map and bind-dn-pattern properties, there are also key differences between them. Both mechanisms can be used to construct the bind DN to use to authenticate to an external server using a combination of static text and attribute values from the target user's entry. However, a DN map can also use information from the original bind DN in constructing the remote bind DN, while a bind DN pattern can be used if you need to construct a remote bind DN that is not actually a valid LDAP distinguished name (e.g., if you want ot use a user principal name to authenticate to an Active Directory server). By default, any text provided in the bind-dn-pattern is copied verbatim into the constructed bind DN, with the exception of attribute names embedded in curly braces. Attributes are substituted using the value from the local server's copy of the entry of the user trying to authenticate (e.g., '{uid}' will be replaced with the value of the uid attribute). Each referenced attribute should have exactly one value. If any of the attributes is missing, or if any of the attributes has multiple values, then the bind DN pattern construction will fail. To include the '{' character in the constructed value, use '{{' in the bind DN pattern. Likewise, using '}}' in the pattern will cause '}' to appear in the constructed DN. Furthermore, a regular expression with a substitution pattern can be used to further manipulate an individual attribute value. The java.util.regex.Pattern and java.util.regex.Matcher classes are used to perform the substitution. The regular expression with replacement value uses this syntax '{attr-name:/regex/replacement/flags}'. 'attr-name' is an attribute name such as 'cn'. 'regex' is a regular expression using the syntax described in the java.util.regex.Pattern javadoc. The optional flags value can also be used to change how this regular expression is interpreted. 'replacement' is a replacement value that is passed to the java.util.regex.Matcher#replaceFirst or java.util.regex.Matcher#replaceAll method to perform the replacement. The 'g' (global) flag controls whether replaceFirst or replaceAll is called. 'flags' is an optional set of single character flags that control how the regular expression is interpreted and how the replacement is performed. The flags are:
Pattern pattern = Pattern.compile(regex, flagsMask); To apply modifiers to the values extracted, append ':' and then the name of the modifier to apply. For example, if attribute 'uid' is to be included in a bind DN pattern, but the value should be explicitly converted to uppercase, then you could use a pattern like: 'uid={uid:upperCase},ou=People,dc=example,dc=com'. The modifiers are:
At most one of the dn-map, bind-dn-pattern, and search-filter-pattern properties may be present in the configuration. If none of these properties is present, then the bind DN used in the original bind request will also be used as the bind DN when authenticating to the remote server. |
| Default Value | None |
| Allowed Values | A string |
| Multi-Valued | No |
| Required | No |
| Admin Action Required | None. Modification requires no further action |
| Description | The base DN to use when searching for the user entry using a filter constructed from the pattern defined in the search-filter-pattern property. If no base DN is specified, the null DN will be used as the search base DN. |
| Default Value | The null DN will be used as the search base DN. |
| Allowed Values | A valid DN. |
| Multi-Valued | No |
| Required | No |
| Admin Action Required | None. Modification requires no further action |
| Description | A pattern to use to construct a filter to use when searching an external server for the entry of the user as whom to bind. For example, "(mail={uid:ldapFilterEscape}@example.com)" would construct a search filter to search for a user whose entry in the local server contains a uid attribute whose value appears before "@example.com" in the mail attribute in the external server. Note that the "ldapFilterEscape" modifier should almost always be used with attributes specified in the pattern. By default, any text provided in the search-filter-pattern is copied verbatim into the constructed filter, with the exception of attribute names embedded in curly braces. Attributes are substituted using the value from the local server's copy of the entry of the user trying to authenticate (e.g., '{uid}' will be replaced with the value of the uid attribute). At most one referenced attribute may be multivalued in the local copy of the user's entry. If one attribute is multivalued then the target value will be multivalued with the same number of values minus any duplicates. For example a mapping of '{givenName} {sn}' would produce values ['Jim Smith', 'James Smith'] if givenName had values of ['Jim', 'James'] and sn had a value of 'Smith'. If the source entry has no value or if there are multiple multivalued attributes, the filter construction will fail. To include the '{' character in the constructed value, use '{{' in the filter pattern. Likewise, using '}}' in the pattern will cause '}' to appear in the constructed filter. Furthermore, a regular expression with a substitution pattern can be used to further manipulate an individual attribute value. The java.util.regex.Pattern and java.util.regex.Matcher classes are used to perform the substitution. The regular expression with replacement value uses this syntax '{attr-name:/regex/replacement/flags}'. 'attr-name' is an attribute name such as 'cn'. 'regex' is a regular expression using the syntax described in the java.util.regex.Pattern javadoc. The optional flags value can also be used to change how this regular expression is interpreted. 'replacement' is a replacement value that is passed to the java.util.regex.Matcher#replaceFirst or java.util.regex.Matcher#replaceAll method to perform the replacement. The 'g' (global) flag controls whether replaceFirst or replaceAll is called. 'flags' is an optional set of single character flags that control how the regular expression is interpreted and how the replacement is performed. The flags are:
Pattern pattern = Pattern.compile(regex, flagsMask); To apply modifiers to the values extracted, append ':' and then the name of the modifier to apply. For example, if attribute 'uid' is to be included in a search filter pattern, then modifier 'ldapFilterEscape' could be specified resulting in '(mail={uid:ldapFilterEscape}@example.com)' or '(mail={uid:/regex/replacement/flags:ldapFilterEscape}@example.com)' if a regular expression is to be used. The modifiers are:
At most one of the dn-map, bind-dn-pattern, and search-filter-pattern properties may be present in the configuration. If none of these properties is present, then the bind DN used in the original bind request will also be used as the bind DN when authenticating to the remote server. |
| Default Value | None |
| Allowed Values | A string |
| Multi-Valued | No |
| Required | No |
| Admin Action Required | None. Modification requires no further action |
| Description | Specifies the initial number of connections to establish to each external server against which authentication may be attempted. |
| Default Value | 1 |
| Allowed Values | An integer value. Lower limit is 1. |
| Multi-Valued | No |
| Required | Yes |
| Admin Action Required | None. Modification requires no further action |
| Description | Specifies the maximum number of connections to maintain to each external server against which authentication may be attempted. This value must be greater than or equal to the value for the initial-connections property. |
| Default Value | 10 |
| Allowed Values | An integer value. Lower limit is 1. |
| Multi-Valued | No |
| Required | Yes |
| Admin Action Required | None. Modification requires no further action |
plugin-type (Advanced Property)
| Description | Specifies the set of plug-in types for the plug-in, which specifies the times at which the plug-in is invoked. |
| Default Value | preoperationbind postoperationbind |
| Allowed Values | startup - Invoked during the Directory Server startup process. shutdown - Invoked during a graceful Directory Server shutdown. postconnect - Invoked whenever a new connection is established to the server. postdisconnect - Invoked whenever an existing connection is terminated (by either the client or the server). ldifimport - Invoked for each entry read during an LDIF import. ldifexport - Invoked for each operation to be written during an LDIF export. preparseabandon - Invoked prior to parsing an abandon request. preparseadd - Invoked prior to parsing an add request. preparsebind - Invoked prior to parsing a bind request. preparsecompare - Invoked prior to parsing a compare request. preparsedelete - Invoked prior to parsing a delete request. preparseextended - Invoked prior to parsing an extended request. preparsemodify - Invoked prior to parsing a modify request. preparsemodifydn - Invoked prior to parsing a modify DN request. preparsesearch - Invoked prior to parsing a search request. preparseunbind - Invoked prior to parsing an unbind request. preoperationadd - Invoked prior to performing the core add processing. preoperationbind - Invoked prior to performing the core bind processing. preoperationcompare - Invoked prior to performing the core compare processing. preoperationdelete - Invoked prior to performing the core delete processing. preoperationextended - Invoked prior to performing the core extended processing. preoperationmodify - Invoked prior to performing the core modify processing. preoperationmodifydn - Invoked prior to performing the core modify DN processing. preoperationsearch - Invoked prior to performing the core search processing. postoperationabandon - Invoked after completing the abandon processing. postoperationadd - Invoked after completing the core add processing but before sending the response to the client. postoperationbind - Invoked after completing the core bind processing but before sending the response to the client. postoperationcompare - Invoked after completing the core compare processing but before sending the response to the client. postoperationdelete - Invoked after completing the core delete processing but before sending the response to the client. postoperationextended - Invoked after completing the core extended processing but before sending the response to the client. postoperationmodify - Invoked after completing the core modify processing but before sending the response to the client. postoperationmodifydn - Invoked after completing the core modify DN processing but before sending the response to the client. postoperationsearch - Invoked after completing the core search processing but before sending the response to the client. postoperationunbind - Invoked after completing the unbind processing. preresponseadd - Invoked just before sending the add response to the client. preresponsebind - Invoked just before sending the bind response to the client. preresponsecompare - Invoked just before sending the compare response to the client. preresponsedelete - Invoked just before sending the delete response to the client. preresponseextended - Invoked just before sending the extended response to the client. preresponsemodify - Invoked just before sending the modify response to the client. preresponsemodifydn - Invoked just before sending the modify DN response to the client. preresponsesearch - Invoked just before sending the search result done response to the client. postresponseadd - Invoked after sending the add response to the client. postresponsebind - Invoked after sending the bind response to the client. postresponsecompare - Invoked after sending the compare response to the client. postresponsedelete - Invoked after sending the delete response to the client. postresponseextended - Invoked after sending the extended response to the client. postresponsemodify - Invoked after sending the modify response to the client. postresponsemodifydn - Invoked after sending the modify DN response to the client. postresponsesearch - Invoked after sending the search result done message to the client. postsynchronizationadd - Invoked after completing post-synchronization processing for an add operation. postsynchronizationdelete - Invoked after completing post-synchronization processing for a delete operation. postsynchronizationmodify - Invoked after completing post-synchronization processing for a modify operation. postsynchronizationmodifydn - Invoked after completing post-synchronization processing for a modify DN operation. searchresultentry - Invoked before sending a search result entry to the client. searchresultreference - Invoked before sending a search result reference to the client. subordinatemodifydn - Invoked in the course of moving or renaming an entry subordinate to the target of a modify DN operation. intermediateresponse - Invoked before sending an intermediate response message to the client. |
| Multi-Valued | Yes |
| Required | Yes |
| Admin Action Required | The Pass Through Authentication Plugin must be disabled and re-enabled for changes to this setting to take effect. In order for this modification to take effect, the component must be restarted, either by disabling and re-enabling it, or by restarting the server |
invoke-for-internal-operations (Advanced Property)
| Description | Indicates whether the plug-in should be invoked for internal operations. Any plug-in that can be invoked for internal operations must ensure that it does not create any new internal operations that can cause the same plug-in to be re-invoked. |
| Default Value | true |
| Allowed Values | true false |
| Multi-Valued | No |
| Required | No |
| Admin Action Required | None. Modification requires no further action |
connection-criteria (Advanced Property)
| Description | Specifies a set of connection criteria that must match the client associated with the bind request for the bind to be passed through to an alternate server. |
| Default Value | None |
| Allowed Values | The DN of any Connection Criteria. |
| Multi-Valued | No |
| Required | No |
| Admin Action Required | None. Modification requires no further action |
request-criteria (Advanced Property)
| Description | Specifies a set of request criteria that must match the bind request for the bind to be passed through to an alternate server. |
| Default Value | None |
| Allowed Values | The DN of any Request Criteria. |
| Multi-Valued | No |
| Required | No |
| Admin Action Required | None. Modification requires no further action |
To list the configured Plugins:
dsconfig list-plugins
[--property {propertyName}] ...
To view the configuration for an existing Plugin:
dsconfig get-plugin-prop
--plugin-name {name}
[--tab-delimited]
[--script-friendly]
[--property {propertyName}] ...
To update the configuration for an existing Plugin:
dsconfig set-plugin-prop
--plugin-name {name}
(--set|--add|--remove) {propertyName}:{propertyValue}
[(--set|--add|--remove) {propertyName}:{propertyValue}] ...
To create a new Pass Through Authentication Plugin:
dsconfig create-plugin
--plugin-name {name}
--type pass-through-authentication
--set enabled:{propertyValue}
--set server:{propertyValue}
[--set {propertyName}:{propertyValue}] ...
To delete an existing Plugin:
dsconfig delete-plugin
--plugin-name {name}