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.

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:

• 'g' : Matcher#replaceAll is called instead of Matcher#replaceFirst to replace all matching values instead of just the first one.
• 'i' : the regex pattern is compiled with Pattern.CASE_INSENSITIVE.
• 'x' : the regex pattern is compiled with Pattern.COMMENTS.
• 's' : the regex pattern is compiled with Pattern.DOTALL.
• 'm' : the regex pattern is compiled with Pattern.MULTILINE.
• 'u' : the regex pattern is compiled with Pattern.UNICODE_CASE.
• 'd' : the regex pattern is compiled with Pattern.UNIX_LINES.

Pattern pattern = Pattern.compile(regex, flagsMask);
Matcher matcher = pattern.matcher(attributeValueInput);
String substitutionValueOutput = matcher.replaceFirst(replacement);

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:

• 'lowerCase' : Convert text to lower case.
• 'trim' : Remove leading and trailing whitespace.
• 'upperCase' : Convert text to upper case.

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.

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:

• 'g' : Matcher#replaceAll is called instead of Matcher#replaceFirst to replace all matching values instead of just the first one.
• 'i' : the regex pattern is compiled with Pattern.CASE_INSENSITIVE.
• 'x' : the regex pattern is compiled with Pattern.COMMENTS.
• 's' : the regex pattern is compiled with Pattern.DOTALL.
• 'm' : the regex pattern is compiled with Pattern.MULTILINE.
• 'u' : the regex pattern is compiled with Pattern.UNICODE_CASE.
• 'd' : the regex pattern is compiled with Pattern.UNIX_LINES.

Pattern pattern = Pattern.compile(regex, flagsMask);
Matcher matcher = pattern.matcher(attributeValueInput);
String substitutionValueOutput = matcher.replaceFirst(replacement);

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:

• 'ldapFilterEscape' : Escape text for use in an LDAP filter.
• 'lowerCase' : Convert text to lower case.
• 'trim' : Remove leading and trailing whitespace.
• 'upperCase' : Convert text to upper case.

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.