Directory Server (LDAP) - Distinguished names (DNs)

Distinguished names (DNs)

Every entry in the directory has a distinguished name (DN). The DN is the name that uniquely identifies an entry in the directory. A DN is made up of attribute=value pairs, separated by commas, for example:

cn=Ben Gray,ou=editing,o=New York Times,c=US
cn=Lucille White,ou=editing,o=New York Times,c=US
cn=Tom Brown,ou=reporting,o=New York Times,c=US

Any of the attributes defined in the directory schema can be used to make up a DN. The order of the component attribute value pairs is important. The DN contains one component for each level of the directory hierarchy from the root down to the level where the entry resides. LDAP DNs begin with the most specific attribute (usually some sort of name), and continue with progressively broader attributes, often ending with a country attribute. The first component of the DN is referred to as the Relative Distinguished Name (RDN). It identifies an entry distinctly from any other entries that have the same parent. In the examples above, the RDN "cn=Ben Gray" separates the first entry from the second entry, (with RDN "cn=Lucille White"). These two example DNs are otherwise equivalent. The attribute=value pair making up the RDN for an entry must also be present in the entry. (This is not true of the other components of the DN.)

Follow this example to create an entry for a person:

dn: cn=Tim Jones,o=ibm,c=us
objectclass: top
objectclass: person 
cn: Tim Jones 
sn: Jones 
telephonenumber: 555-555-1234

DN escaping rules

Some characters have special meaning in a DN. For example, = (equals) separates an attribute name and value, and , (comma) separates attribute=value pairs. The special characters are , (comma), = (equals), + (plus), < (less than), > (greater than), # (number sign), ; (semicolon), \ (backslash), and " (quotation mark, ASCII 34).

A special character can be escaped in an attribute value to remove the special meaning. To escape these special characters or other characters in an attribute value in a DN string, use the following methods:

If a character to be escaped is one of the special characters, precede it by a backslash ('\' ASCII 92). This example shows a method of escaping a comma in an organization name:
```
CN=L. Eagle,O=Sue\, Grabbit and Runn,C=GB
```
This is the preferred method.
Otherwise replace the character to be escaped by a backslash and two hex digits, which form a single byte in the code of the character. The code of the character must be in UTF-8 code set.
```
CN=L. Eagle,O=Sue\2C Grabbit and Runn,C=GB
```
Surround the entire attribute value by "" (quotation marks) (ASCII 34), that are not part of the value. Between the quotation character pair, all characters are taken as is, except for the \ (backslash). The \ (backslash) can be used to escape a backslash (ASCII 92) or quotation marks (ASCII 34), any of the special characters previously mentioned, or hex pairs as in method 2. For example, to escape the quotation marks in cn=xyz"qrs"abc, it becomes cn=xyz\"qrs\"abc or to escape a \:
```
"you need to escape a single backslash this way \\"
```
Another example, "\Zoo" is illegal, because 'Z' cannot be escaped in this context.

Pseudo DNs

Pseudo DNs are used in access control definition and evaluation. The LDAP directory supports several pseudo DNs (for example, "group:CN=THIS" and "access-id:CN=ANYBODY"), which are used to refer to large numbers of DNs that share a common characteristic, in relation to either the operation being performed or the object on which the operation is being performed. For more information on access control, see Directory Server security.

Three pseudo DNs are supported by Directory Server:

access-id: CN=THIS
When specified as part of an ACL, this DN refers to the bindDN, which matches the DN on which the operation is performed. For example, if an operation is performed on the object "cn=personA, ou=IBM, c=US" and the bindDn is "cn=personA, ou=IBM, c=US", the permissions granted are a combination of those given to "CN=THIS" and those given to "cn=personA, ou=IBM, c=US".
group: CN=ANYBODY
When specified as part of an ACL, this DN refers to all users, even those that are unauthenticated. Users cannot be removed from this group, and this group cannot be removed from the database.
group: CN=AUTHENTICATED
This DN refers to any DN that has been authenticated by the directory. The method of authentication is not considered.

Note:

"CN=AUTHENTICATED" refers to a DN that has been authenticated anywhere on the server, regardless of where the object representing the DN is located. It should be used with caution, however. For example, under one suffix, "cn=Secret" could be a node called "cn=Confidential Material" which has an aclentry of "group:CN=AUTHENTICATED:normal:rsc". Under another suffix, "cn=Common" could be the node "cn=Public Material". If these two trees reside on the same server, a bind to "cn=Public Material" would be considered authenticated, and would get permission to the normal class on the "cn= Confidential Material" object.

Some examples of pseudo DNs:

Example 1

Consider the following ACL for object: cn=personA, c=US

AclEntry: access-id: CN=THIS:critical:rwsc
AclEntry: group: CN=ANYBODY: normal:rsc
AclEntry: group: CN=AUTHENTICATED: sensitive:rcs

User Binding as	Would receive
cn=personA, c=US	normal:rsc:sensitive:rcs:critical:rwsc
cn=personB, c=US	normal:rsc:sensitive:rsc
Anonymous	normal:rsc

In this example, personA receives permissions granted to the "CN=THIS" ID, and permissions given to both the "CN=ANYBODY" and "CN=AUTHENTICATED" pseudo DN groups.

Example 2

Consider the following ACL for object: cn=personA, c=US AclEntry: access-id:cn=personA, c=US: object:ad

AclEntry: access-id: CN=THIS:critical:rwsc
AclEntry: group: CN=ANYBODY: normal:rsc
AclEntry: group: CN=AUTHENTICATED: sensitive:rcs

For an operation performed on cn=personA, c=US:

User Binding as	Would receive
cn=personA, c=US	object:ad:critical:rwsc
cn=personB, c=US	normal:rsc:sensitive:rsc
Anonymous	normal:rsc

In this example, personA receives permissions granted to the "CN=THIS" ID, and those given to the DN itself "cn=personA, c=US". Note that the group permissions are not given because there is a more specific aclentry ("access-id:cn=personA, c=US") for the bind DN ("cn=personA, c=US").

Enhanced DN processing

A composite RDN of a DN can consist of multiple components connected by the '+' operators. The server enhances the support for searches on entries that have such a DN. A composite RDN can be specified in any order as the base for a search operation.

ldapsearch -b "cn=mike+ou=austin,o=ibm,c=us" "(objectclass=*)"

The server supports a DN normalization extended operation. DN normalization extended operations normalize DNs using the server schema. This extended operation might be useful for applications that use DNs. For more information about extended operations, see Controls and extended operations.

Distinguished name syntax

The formal syntax for a Distinguished Name (DN) is based on RFC 2253. The Backus Naur Form (BNF) syntax is defined as follows:

<name> ::= <name-component> ( <spaced-separator> )
          | <name-component> <spaced-separator> <name>

   <spaced-separator> ::= <optional-space>
                   <separator>
                   <optional-space>

   <separator> ::=  "," | ";"

   <optional-space> ::= ( <CR> ) *( " " )

   <name-component> ::= <attribute>
           | <attribute> <optional-space> "+"
             <optional-space> <name-component>

   <attribute> ::= <string>
           | <key> <optional-space> "=" <optional-space> <string>

   <key> ::= 1*( <keychar> ) | "OID." <oid> | "oid." <oid>
   <keychar> ::= letters, numbers, and space

   <oid> ::= <digitstring> | <digitstring> "." <oid>
   <digitstring> ::= 1*<digit>
   <digit> ::= digits 0-9

   <string> ::= *( <stringchar> | <pair> )
            | '"' *( <stringchar> | <special> | <pair> ) '"'
            | "#" <hex>


   <special> ::= "," | "=" | <CR> | "+" | "<" |  ">"
            | "#" | ";"

   <pair> ::= "\" ( <special> | "\" | '"')
   <stringchar> ::= any character except <special> or "\" or '"'


   <hex> ::= 2*<hexchar>
   <hexchar> ::= 0-9, a-f, A-F

A semicolon (;) character can be used to separate RDNs in a distinguished name, although the comma (,) character is the typical notation.

White-space characters (spaces) might be present on either side of the comma or semicolon. The white-space characters are ignored, and the semicolon is replaced with a comma.

In addition, space (' ' ASCII 32) characters can be present either before or after a '+' or '='. These space characters are ignored when parsing.

The following example is a distinguished name written using a notation that is designed to be convenient for common forms of names. First is a name containing three components. The first of the components is a compound RDN. A compound RDN contains more than one attribute:value pair and can be used to distinctly identify a specific entry in cases where a simple CN value might be ambiguous:

OU=Sales+CN=J. Smith,O=Widget Inc.,C=US