PingAuthorize Server Documentation Index
Configuration Reference Home

DN Map

Note: this component is designated "advanced", which means that objects of this type are not expected to be created or altered in most environments. If you believe that such a change is necessary, you may want to contact support in order to understand the potential impact of that change.

A DN Map constructs DN values from attributes and the DN of a source entry, and fixed text. It is used to construct the DN for an entry as well as values for attributes that store DNs such as isMemberOf.

A DN Maps includes a wild-card pattern for matching source DN values and a replacement value that uses fixed text, components of the matched source DN, and values of source entry attributes to construct a DN value.

↓Relations to This Component
↓Properties
↓dsconfig Usage

Properties

The properties supported by this managed object are as follows:


Basic Properties: Advanced Properties:
↓ description  None
↓ from-dn-pattern
↓ to-dn-pattern

Basic Properties

description

Description
A description for this DN Map
Default Value
None
Allowed Values
A string
Multi-Valued
No
Required
No
Admin Action Required
None. Modification requires no further action

from-dn-pattern

Description
Specifies the DN pattern to match when determining whether this map applies to a specific source DN. If the provided bind DN matches this pattern, then the to-dn-pattern will be used to perform the mapping. If the provided bind DN does not match this pattern, then no mapping will be performed. This pattern can be used to extract individual RDN components that are used to construct the target DN value. The '*' wild-card will match a single RDN component and can be used any number of times. The '**' wild-card will match zero or more RDN components and can be used at most once. If a literal '*' is required in a DN then it must be escaped as '2A'.

The wild-card values can be used in the to-dn-pattern attribute using "{}"s and their original index position in the pattern. For example, with the pattern '*,**,dc=com' and an input DN value of 'uid=jsmith,ou=people,dc=example,dc=com', '*' matches 'uid=jsmith' and '**' matches 'ou=people,dc=example'. In to-dn-pattern, '{1}' can be used to include 'uid=jsmith' and '{2}' can be used to include 'ou=people,dc=example' in the replacement value.

If the source entry does not have a DN value, then '**' can be used to match the missing DN value. The target DN value must then be constructed exclusively from fixed text and attributes from the source entry.

Default Value
None
Allowed Values
DNs matching this pattern will be replaced with a DN value constructed by to-dn-pattern.
Multi-Valued
No
Required
Yes
Admin Action Required
None. Modification requires no further action

to-dn-pattern

Description
Specifies a pattern for constructing the DN value using fixed text, DN components matching wild-card values in from-dn-pattern, and attribute values from the source entry. If a source DN matches the pattern specified in from-dn-pattern, then this pattern is used to construct the DN pattern. The text used in this DN pattern is substituted verbatim into the constructed pattern unless it is included in '{}'s. Values included in '{}' can either be wild-card DN components from the matched from-dn-pattern value, or they can be attribute values from the source entry.

A numeric index is used to select which DN wild-card value to select from the matching DN. The left-most wild-card DN component is {1}, the next wild-card component to its right is {2}, and so on. Attributes are substituted using their source value (e.g. {uid} will select the uid attribute from the source entry). Attributes must have exactly one value to be used in the DN construction. If the source entry has no value or multiple values for the specified attribute, the DN construction will fail.

Furthermore, a regular expression with a substitution pattern can be used to further manipulate an individual DN wild-card component or 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 the syntax '{attr-name:/regex/replacement/flags}'.

'attr-name' is either a DN substitution index such as '1' or 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.
The substitution value is constructed using Java code equivalent to:


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 'cn' is to be included in a constructed DN value then modifier 'dnEscape' could be specified resulting in 'cn={cn:dnEscape},dc=example,dc=com' or 'cn={cn:/regex/replacement/flags:dnEscape},dc=example,dc=com' if a regular expression is to be used. The modifiers are:

  • 'dnEscape' : Escape text for use in a DN value.
  • 'lowerCase' : Convert text to lower case.
  • 'trim' : Remove leading and trailing whitespace.
  • 'upperCase' : Convert text to upper case.
Here is an example to summarize these points. Suppose all DNs ending in dc=example,dc=com need to be mapped to o=example. The user entries are not direct leaf entries of the dc=example,dc=com entry, but the same hierarchy must be preserved. Furthermore, the RDN attribute is 'cn' but the target RDN attribute is uid and should be constructed using the initials of the first and last name followed by the user's employee number which is stored in the 'eid' attribute. For example, 'cn=John Smith,ou=people,dc=example,dc=com' should be mapped to 'uid=js12345,ou=people,o=example'.

The 'from-dn-pattern' matching pattern for this example is '*,**,dc=example,dc=com' (the {1} value matches 'cn=John Smith' and the {2} value matches 'ou=people'). The 'to-dn-pattern' pattern is more complicated. It is 'uid={givenname:/^(.)(.*)/$1/s}{sn:/^(.)(.*)/$1/s}{eid},{2},o=example'. The employee's initials are extracted from the 'givenname' and 'sn' attributes. The '^(.).*' regular expression used for these attributes matches the entire value and stores the initial character in the $1 variable, which is used for the replacement (the 's' flag is used to guard against the unlikely event that the user's 'givenname' or 'sn' attribute includes a newline character).

Default Value
None
Allowed Values
The pattern to use to construct the DN value.
Multi-Valued
No
Required
Yes
Admin Action Required
None. Modification requires no further action


dsconfig Usage

To list the configured DN Maps:

dsconfig list-dn-maps
     [--property {propertyName}] ...

To view the configuration for an existing DN Map:

dsconfig get-dn-map-prop
     --map-name {name}
     [--tab-delimited]
     [--script-friendly]
     [--property {propertyName}] ...

To update the configuration for an existing DN Map:

dsconfig set-dn-map-prop
     --map-name {name}
     (--set|--add|--remove) {propertyName}:{propertyValue}
     [(--set|--add|--remove) {propertyName}:{propertyValue}] ...

To create a new DN Map:

dsconfig create-dn-map
     --map-name {name}
     --set from-dn-pattern:{propertyValue}
     --set to-dn-pattern:{propertyValue}
     [--set {propertyName}:{propertyValue}] ...

To delete an existing DN Map:

dsconfig delete-dn-map
     --map-name {name}