51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark ! CCPL HEADER START
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark ! This work is licensed under the Creative Commons
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark ! Attribution-NonCommercial-NoDerivs 3.0 Unported License.
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark ! To view a copy of this license, visit
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark ! or send a letter to Creative Commons, 444 Castro Street,
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark ! Suite 900, Mountain View, California, 94041, USA.
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark ! You can also obtain a copy of the license at
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark ! See the License for the specific language governing permissions
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark ! and limitations under the License.
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark ! If applicable, add the following below this CCPL HEADER, with the fields
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark ! enclosed by brackets "[]" replaced with your own identifying information:
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark ! Portions Copyright [yyyy] [name of copyright owner]
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark ! CCPL HEADER END
57d6342a74476c0bf2200992e778229d62ab1fa6mark ! Copyright 2011-2015 ForgeRock AS.
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark xmlns='http://docbook.org/ns/docbook' version='5.0' xml:lang='en'
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>OpenDJ comes with a Control Panel browser for managing entries and also
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark command-line tools for performing LDAP operations. This chapter demonstrates
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark how to use the command line tools to script LDAP operations.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <indexterm><primary>Searching data</primary></indexterm>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Searching the directory resembles searching for a phone number in
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark a paper phone book. You can look up a phone number because you know the
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark last name of a subscriber's entry. In other words, you use the value of
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark one attribute of the entry to find entries that have another attribute
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark you want.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Yet whereas a paper phone book has only one index (alphabetical order
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark by name), the directory has many indexes. For a search you therefore always
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark specify which index to use, by specifying which attribute(s) you are using
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark to lookup entries.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Your paper phone book might be divided into white pages for residential
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark subscribers, and yellow pages for businesses. If you are looking up an
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark individual's phone number, you limit your search to the white pages.
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark Directory services divide entries in various ways, often to separate
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark organizations, and to separate groups from user entries from printers for
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark example, but potentially in other ways. When searching you therefore also
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark specify where in the directory to search.</para>
ec40cc0dc62425cea5d63fd9d984f8614479de25mark thus takes at minimum a search base DN option and an LDAP filter.
ec40cc0dc62425cea5d63fd9d984f8614479de25mark The search base DN identifies where in the directory
ec40cc0dc62425cea5d63fd9d984f8614479de25mark to search for entries that match the filter.
ec40cc0dc62425cea5d63fd9d984f8614479de25mark For example, if you are looking for printers,
ec40cc0dc62425cea5d63fd9d984f8614479de25mark you might specify the base DN as
ec40cc0dc62425cea5d63fd9d984f8614479de25mark Perhaps you are visiting the <literal>GNB00</literal> office
ec40cc0dc62425cea5d63fd9d984f8614479de25mark and are looking for a printer.
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>ldapsearch --baseDN ou=Printers,dc=example,dc=com "(printerLocation=GNB00)"</userinput>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>In the example, the LDAP filter indicates to the directory that you
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark want to lookup printer entries where the <literal>printerLocation</literal>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>You also specify the host and port to access directory services,
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark what protocol to use (for example, LDAP/SSL, or StartTLS to protect
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark communication). If the directory service does not allow anonymous access
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark to the data you want to search, you also identify who is performing the
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark search and provide their credentials, such as a password or
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark certificate. Finally, you can specify a list of attributes to return.
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark If you do not specify attributes, then the search returns all user attributes
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark for the entry.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <itemizedlist>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Review the following examples in this section to get a sense of how
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark searches work.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <listitem><para><xref linkend="simple-filter-search"/></para></listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <listitem><para><xref linkend="complex-filter-search"/></para></listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <listitem><para><xref linkend="operational-attrs-search"/></para></listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <listitem><para><xref linkend="attr-desc-list-search"/></para></listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <listitem><para><xref linkend="escape-characters-in-filter"/></para></listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <listitem><para><xref linkend="extensible-match-search"/></para></listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <listitem><para><xref linkend="localized-search"/></para></listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </itemizedlist>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>The following example searches for entries with user IDs
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark (<literal>uid</literal>) containing <literal>jensen</literal>, returning
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark only DNs and user ID values.</para>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>ldapsearch --port 1389 --baseDN dc=example,dc=com "(uid=*jensen*)" uid</userinput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark<computeroutput>dn: uid=ajensen,ou=People,dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkuid: ajensen
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkdn: uid=bjensen,ou=People,dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkuid: bjensen
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkdn: uid=gjensen,ou=People,dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkuid: gjensen
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkdn: uid=jjensen,ou=People,dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkuid: jjensen
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkdn: uid=kjensen,ou=People,dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkuid: kjensen
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkdn: uid=rjensen,ou=People,dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkuid: rjensen
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkdn: uid=tjensen,ou=People,dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkuid: tjensen
08248b5c5b494aff8d1922e8e0b5777796d7450dmarkResult Code: 0 (Success)</computeroutput>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </example>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>The following example returns entries with <literal>uid</literal>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark containing <literal>jensen</literal> for users located in Santa Clara. The
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark command returns the attributes associated with the <literal>person</literal>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark object class.</para>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>ldapsearch \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --port 1389 \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --baseDN ou=people,dc=example,dc=com \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark "(&(uid=*jensen*)(l=Santa Clara))" \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark @person</userinput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark<computeroutput>dn: uid=ajensen,ou=People,dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkobjectClass: person
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkobjectClass: organizationalPerson
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkobjectClass: inetOrgPerson
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkobjectClass: posixAccount
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkobjectClass: top
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkcn: Allison Jensen
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarktelephoneNumber: +1 408 555 7892
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkdn: uid=gjensen,ou=People,dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkobjectClass: person
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkobjectClass: organizationalPerson
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkobjectClass: inetOrgPerson
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkobjectClass: posixAccount
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkobjectClass: top
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkcn: Gern Jensen
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarktelephoneNumber: +1 408 555 3299
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkdn: uid=kjensen,ou=People,dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkobjectClass: person
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkobjectClass: organizationalPerson
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkobjectClass: inetOrgPerson
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkobjectClass: posixAccount
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkobjectClass: top
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkcn: Kurt Jensen
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarktelephoneNumber: +1 408 555 6127
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkdn: uid=tjensen,ou=People,dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkobjectClass: person
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkobjectClass: organizationalPerson
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkobjectClass: inetOrgPerson
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkobjectClass: posixAccount
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkobjectClass: top
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkcn: Ted Jensen
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarktelephoneNumber: +1 408 555 8622
08248b5c5b494aff8d1922e8e0b5777796d7450dmark</computeroutput>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Complex filters can use both "and" syntax,
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <literal>(&(<replaceable>filtercomp</replaceable>)(<replaceable>filtercomp</replaceable>))</literal>,
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark and "or" syntax,
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <literal>(|(<replaceable>filtercomp</replaceable>)(<replaceable>filtercomp</replaceable>))</literal>.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </example>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Use <literal>+</literal> in the attribute list after the filter
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark to return all operational attributes. Alternatively, specify operational
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark attributes by name.</para>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>ldapsearch --port 1389 --baseDN dc=example,dc=com uid=bjensen +</userinput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark<computeroutput>dn: uid=bjensen,ou=People,dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarknumSubordinates: 0
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkstructuralObjectClass: inetOrgPerson
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkpwdPolicySubentry: cn=Default Password Policy,cn=Password Policies,cn=config
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarksubschemaSubentry: cn=schema
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkhasSubordinates: false
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkentryDN: uid=bjensen,ou=people,dc=example,dc=com
08248b5c5b494aff8d1922e8e0b5777796d7450dmarkentryUUID: fc252fd9-b982-3ed6-b42a-c76d2546312c</computeroutput>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </example>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <title>Search: Return Attributes for an Object Class</title>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Use <literal>@<replaceable>objectClass</replaceable></literal> in the
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark attribute list after the filter to return the attributes associated with
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark a particular object class.</para>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>ldapsearch --port 1389 --baseDN dc=example,dc=com uid=bjensen @person</userinput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark<computeroutput>dn: uid=bjensen,ou=People,dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkobjectClass: person
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkobjectClass: organizationalPerson
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkobjectClass: inetOrgPerson
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkobjectClass: posixAccount
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkobjectClass: top
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkcn: Barbara Jensen
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkcn: Babs Jensen
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarktelephoneNumber: +1 408 555 1862
08248b5c5b494aff8d1922e8e0b5777796d7450dmarksn: Jensen</computeroutput>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </example>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <title>Search: Escaping Search Filter Characters</title>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para><link xlink:href='http://tools.ietf.org/html/rfc4515'>RFC 4515:
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark Lightweight Directory Access Protocol (LDAP): String Representation
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark of Search Filters</link> mentions a number of characters that you must
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark handle with care when using them in search filters.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <itemizedlist>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark >value</replaceable>)</literal>, the following list indicates characters
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark that you must replace with a backslash ( <literal>\</literal> ) followed
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark by two hexadecimal digits when using them as part of the
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Replace <literal>*</literal> with <literal>\2a</literal>.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Replace <literal>(</literal> with <literal>\28</literal>.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Replace <literal>)</literal> with <literal>\29</literal>.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Replace <literal>\</literal> with <literal>\5c</literal>.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Replace NUL (0x00) with <literal>\00</literal>.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </itemizedlist>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>The following example shows a filter with escaped characters matching
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark an actual value.</para>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>ldapsearch --port 1389 --baseDN dc=example,dc=com \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark "(description=\28*\5c*\2a\29)" description</userinput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark<computeroutput>dn: uid=bjensen,ou=People,dc=example,dc=com
08248b5c5b494aff8d1922e8e0b5777796d7450dmarkdescription: (A \great\ description*)</computeroutput>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </example>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <example xml:id="extensible-match-search"><?dbfo keep-together="auto"?>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>OpenDJ supports extensible matching rules, meaning you can pass in
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark filters specifying a matching rule OID that extends your search beyond what
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark you can do with standard LDAP. One specific matching rule of this type that
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark OpenDJ supports is the generalized time based "later than" and "earlier
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark than" matching rules. See the example, <link
08248b5c5b494aff8d1922e8e0b5777796d7450dmark xlink:href="admin-guide#extensible-match-index-example"><citetitle>Configure
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark an Extensible Match Index</citetitle></link>, showing how to build an index
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark for these matching rules.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>You can use these matching rules to list, for example, all users who
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark have authenticated recently.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>First set up an attribute to store a last login timestamp.
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark You can do this by adding a schema file for the attribute.</para>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>ldapmodify \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --port 1389 \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindDN "cn=Directory Manager" \
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindPassword password
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkdn: cn=schema
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkchangetype: modify
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkadd: attributeTypes
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkattributeTypes: ( lastLoginTime-oid
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark NAME 'lastLoginTime'
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark DESC 'Last time the user logged in'
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark EQUALITY generalizedTimeMatch
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark ORDERING generalizedTimeOrderingMatch
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark SYNTAX 1.3.6.1.4.1.1466.115.121.1.24
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark SINGLE-VALUE
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark NO-USER-MODIFICATION
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark USAGE directoryOperation
08248b5c5b494aff8d1922e8e0b5777796d7450dmark X-ORIGIN 'OpenDJ example documentation' )</userinput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark<computeroutput>Processing MODIFY request for cn=schema
08248b5c5b494aff8d1922e8e0b5777796d7450dmarkMODIFY operation successful for DN cn=schema</computeroutput>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Configure the applicable password policy to write the last login
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark timestamp when a user authenticates. The following command configures the
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark default password policy to write the timestamp in generalized time format
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark to the <literal>lastLoginTime</literal> operational attribute on the user's
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark entry.</para>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>dsconfig \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark set-password-policy-prop \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --port 4444 \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindDN "cn=Directory Manager" \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindPassword password \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --policy-name "Default Password Policy" \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --set last-login-time-attribute:lastLoginTime \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --set last-login-time-format:"yyyyMMddHH'Z'" \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --trustAll \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --no-prompt</userinput>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Wait a while for users to authenticate again (or test it yourself) so
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark that OpenDJ writes the timestamps. The following search then returns users
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark who have authenticated in the last three months (13 weeks) after you
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark configured OpenDJ to keep the last login timestamps.</para>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>ldapsearch \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --port 1389 \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --baseDN dc=example,dc=com \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark "(lastLoginTime:1.3.6.1.4.1.26027.1.4.6:=13w)" mail</userinput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark<computeroutput>dn: uid=bjensen,ou=People,dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkmail: bjensen@example.com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkdn: uid=kvaughan,ou=People,dc=example,dc=com
08248b5c5b494aff8d1922e8e0b5777796d7450dmarkmail: kvaughan@example.com</computeroutput>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </example>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <example xml:id="localized-search"><?dbfo keep-together="auto"?>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>OpenDJ directory server supports many language subtypes. See the
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark ><citetitle>Localization</citetitle></link> for a list.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>When you perform a search you can request the language subtype by
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark OID or by language subtype string. For example, the following search gets
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark the French version of a common name. The example uses the
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <command>base64</command> command provided with OpenDJ directory server to
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark decode the attribute value.</para>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>ldapsearch \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --port 1389 \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --baseDN dc=example,dc=com \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark "(givenName:fr:=Fréderique)" cn\;lang-fr</userinput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark<computeroutput>dn: uid=fdupont,ou=People,dc=example,dc=com
08248b5c5b494aff8d1922e8e0b5777796d7450dmarkcn;lang-fr:: RnJlZMOpcmlxdWUgRHVwb250</computeroutput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>base64 decode -d RnJlZMOpcmlxdWUgRHVwb250</userinput>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <itemizedlist>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>At the end of the OID or language subtype, you further specify the
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark matching rule as follows:</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Add <literal>.2</literal> for less than or equal to</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Add <literal>.3</literal> for equal to (default)</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Add <literal>.4</literal> for greater than or equal to</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Add <literal>.5</literal> for greater than</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </itemizedlist>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </example>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>The following table describes the operators you can use in LDAP search
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark filters.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <xinclude:include href="/shared/table-filter-operators.xml" />
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </section>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <indexterm><primary>Comparing attribute values</primary></indexterm>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>The compare operation checks whether an attribute value you specify
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark matches the attribute value stored on one or more directory entries.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <title>Compare: Checking <literal>authPassword</literal></title>
ec40cc0dc62425cea5d63fd9d984f8614479de25mark In this example, Kirsten Vaughan uses the
ec40cc0dc62425cea5d63fd9d984f8614479de25mark to check whether the hashed password value matches the stored value
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>ldapcompare \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --port 1389 \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindDN "uid=kvaughan,ou=people,dc=example,dc=com" \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindPassword bribery \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark 'authPassword:MD5$dFHgpDxXUT8=$qlC4xMXvmVlusJLz9/WJ5Q==' \
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark uid=kvaughan,ou=people,dc=example,dc=com</userinput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark<computeroutput>Comparing type authPassword with value
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark uid=kvaughan,ou=people,dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkCompare operation returned true for entry
08248b5c5b494aff8d1922e8e0b5777796d7450dmark uid=kvaughan,ou=people,dc=example,dc=com</computeroutput>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </example>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </section>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <indexterm><primary>Updating data</primary></indexterm>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <indexterm><primary>LDIF</primary><secondary>Examples</secondary></indexterm>
ec40cc0dc62425cea5d63fd9d984f8614479de25mark Authorized users can change directory data using
ec40cc0dc62425cea5d63fd9d984f8614479de25mark the LDAP add, modify, modify DN, and delete operations.
ec40cc0dc62425cea5d63fd9d984f8614479de25mark You can use the
ec40cc0dc62425cea5d63fd9d984f8614479de25mark ><command>ldapmodify</command></link> command to make changes.
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>With the <command>ldapmodify -a</command> command, authorized users
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark can add entire entries from the same sort of LDIF file used to import
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark and export data.</para>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark<computeroutput>dn: cn=Arsene Lupin,ou=Special Users,dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkobjectClass: person
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkobjectClass: top
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkcn: Arsene Lupin
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarktelephoneNumber: +33 1 23 45 67 89
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkdn: cn=Horace Velmont,ou=Special Users,dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkobjectClass: person
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkobjectClass: top
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkcn: Horace Velmont
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarktelephoneNumber: +33 1 12 23 34 45
08248b5c5b494aff8d1922e8e0b5777796d7450dmarksn: Velmont</computeroutput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>ldapmodify \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --defaultAdd \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --port 1389 \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindDN "uid=kvaughan,ou=people,dc=example,dc=com" \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindPassword bribery \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark<computeroutput>Processing ADD request for cn=Arsene Lupin,ou=Special Users,dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkADD operation successful for DN
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark cn=Arsene Lupin,ou=Special Users,dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkProcessing ADD request for cn=Horace Velmont,ou=Special Users,dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkADD operation successful for DN
08248b5c5b494aff8d1922e8e0b5777796d7450dmark cn=Horace Velmont,ou=Special Users,dc=example,dc=com</computeroutput>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </example>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </section>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>With the <command>ldapmodify</command> command, authorized users
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark can change the values of attributes in the directory using LDIF as specified
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark in <link xlink:href='http://tools.ietf.org/html/rfc2849'>RFC 2849</link>.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>The following example adds a description and JPEG photo to Sam
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark Carter's entry.</para>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark<computeroutput>dn: uid=scarter,ou=people,dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkchangetype: modify
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkadd: description
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkdescription: Accounting Manager
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkadd: jpegphoto
08248b5c5b494aff8d1922e8e0b5777796d7450dmarkjpegphoto:<file:///tmp/Samantha-Carter.jpg</computeroutput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>ldapmodify \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --port 1389 \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindDN "uid=kvaughan,ou=people,dc=example,dc=com" \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindPassword bribery \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark<computeroutput>Processing MODIFY request for uid=scarter,ou=people,dc=example,dc=com
08248b5c5b494aff8d1922e8e0b5777796d7450dmarkMODIFY operation successful for DN uid=scarter,ou=people,dc=example,dc=com</computeroutput>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </example>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>The following example replaces the description on Sam Carter's
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark entry.</para>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark<computeroutput>dn: uid=scarter,ou=people,dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkchangetype: modify
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkreplace: description
08248b5c5b494aff8d1922e8e0b5777796d7450dmarkdescription: Accounting Director</computeroutput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>ldapmodify \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --port 1389 \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindDN "uid=kvaughan,ou=people,dc=example,dc=com" \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindPassword bribery \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark<computeroutput>Processing MODIFY request for uid=scarter,ou=people,dc=example,dc=com
08248b5c5b494aff8d1922e8e0b5777796d7450dmarkMODIFY operation successful for DN uid=scarter,ou=people,dc=example,dc=com</computeroutput>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </example>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>The following example deletes the JPEG photo on Sam Carter's
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark entry.</para>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>cat /path/to/scarter-deljpeg.ldif</userinput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark<computeroutput>dn: uid=scarter,ou=people,dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkchangetype: modify
08248b5c5b494aff8d1922e8e0b5777796d7450dmarkdelete: jpegphoto</computeroutput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>ldapmodify \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --port 1389 \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindDN "uid=kvaughan,ou=people,dc=example,dc=com" \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindPassword bribery \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark<computeroutput>Processing MODIFY request for uid=scarter,ou=people,dc=example,dc=com
08248b5c5b494aff8d1922e8e0b5777796d7450dmarkMODIFY operation successful for DN uid=scarter,ou=people,dc=example,dc=com</computeroutput>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </example>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <example xml:id="modify-optimistic-concurrency"><?dbfo keep-together="auto"?>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Imagine you are writing an application that lets end users update
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark user profiles through a browser. You store user profiles as OpenDJ entries.
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark Your end users can look up user profiles and modify them. Your application
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark assumes that the end users can tell the right information when they see it,
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark and so aims to update profiles exactly as users see them on their
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark screens.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Consider two users, Alice and Bob, both busy and often interrupted.
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark Alice has Babs Jensen's new phone and room numbers. Bob has Babs's new
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark location and description. Both assume that they have all the information
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark that has changed. What can you do to make sure that your application
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark applies the right changes when Alice and Bob simulaneously update Babs
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark Jensen's profile?</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>OpenDJ offers a couple of features to help you in this situation.
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark One of the features is the <link
57d6342a74476c0bf2200992e778229d62ab1fa6mark xlink:href="reference#assertion-request-control">LDAP Assertion
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark Control</link>, used to tell OpenDJ to perform the modify only if
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark an assertion you make stays true. The other feature is OpenDJ's support
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark for <link xlink:href="http://tools.ietf.org/html/rfc2616#section-3.11"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark xlink:show="new">entity tag</link> (ETag) attributes, making it easy to
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark check whether the entry in the directory is the same as the entry you
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark read.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Alice and Bob both get Babs's entry. In LDIF the relevant
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark attributes from the entry look like this. Notice the ETag.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <programlisting language="ldif">dn: uid=bjensen,ou=People,dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarktelephoneNumber: +1 408 555 1862
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkroomNumber: 0209
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkl: Cupertino
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkETag: 000000007a1999df</programlisting>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Bob prepares his changes in your application. Bob is almost ready
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark to submit the new location and description when Carol stops by to ask Bob
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark a few questions.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Alice starts just after Bob, but manages to submit her changes
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark without getting interrupted. Now Babs's entry looks like this.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <programlisting language="ldif">dn: uid=bjensen,ou=People,dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkdescription: Updated by Alice
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarktelephoneNumber: +47 2108 1746
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkroomNumber: 1389
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkl: Cupertino
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkETag: 00000000aec2c1e9</programlisting>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>In your application, you use the ETag attribute value with the
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark assertion control to prevent Bob's update from going through when the
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark ETag value has changed. Your application tries the equivalent of the
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark following commands with Bob's updates.</para>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark<computeroutput>dn: uid=bjensen,ou=People,dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkchangetype: modify
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkl: Grenoble
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkadd: description
08248b5c5b494aff8d1922e8e0b5777796d7450dmarkdescription: Employee of the Month</computeroutput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>ldapmodify \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindDN "cn=Directory Manager" \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindPassword password \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --port 1389 \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --assertionFilter "(ETag=000000007a1999df)"</userinput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark<computeroutput>Processing MODIFY request for uid=bjensen,ou=People,dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkMODIFY operation failed
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkResult Code: 122 (Assertion Failed)
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkAdditional Information: Entry uid=bjensen,ou=People,dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark cannot be modified because the request contained an LDAP assertion control
08248b5c5b494aff8d1922e8e0b5777796d7450dmark and the associated filter did not match the contents of the that entry</computeroutput>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Your application therefore reloads Babs's entry, also getting the new
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark ETag value, <literal>00000000aec2c1e9</literal>, and lets Bob try again.
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark This time Bob's changes do not collide with other changes. Babs's entry is
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark successfully updated.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <programlisting language="ldif">dn: uid=bjensen,ou=People,dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkdescription: Employee of the Month
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarktelephoneNumber: +47 2108 1746
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkroomNumber: 1389
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkl: Grenoble
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkETag: 00000000e882c35e</programlisting>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </example>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </section>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <indexterm>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </indexterm>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Some client applications send updates including attributes with names
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark that differ from the attribute names defined in OpenDJ. Other client
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark applications might try to update attributes they should not update, such
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark as the operational attributes <literal>creatorsName</literal>,
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <literal>createTimestamp</literal>, <literal>modifiersName</literal>,
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark and <literal>modifyTimestamp</literal>. Ideally you would fix the client
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark application behavior, but that is not always feasible.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>You can configure the attribute cleanup plugin to filter add and
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark modify requests, renaming attributes in requests using incorrect names,
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark and removing attributes that applications should not change.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>The following example renames incoming <literal>email</literal>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark attributes to <literal>mail</literal> attributes. First, configure the
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark attribute cleanup plugin to rename the inbound attribute.</para>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>dsconfig \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark create-plugin \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --port 4444 \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindDN "cn=Directory Manager" \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindPassword password \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --type attribute-cleanup \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --plugin-name "Rename email to mail" \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --set enabled:true \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --set rename-inbound-attributes:email:mail \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --trustAll \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --no-prompt</userinput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark<computeroutput>dn: uid=newuser,ou=People,dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkuid: newuser
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkobjectClass: person
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkobjectClass: organizationalPerson
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkobjectClass: inetOrgPerson
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkobjectClass: top
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkcn: New User
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkemail: newuser@example.com
08248b5c5b494aff8d1922e8e0b5777796d7450dmarkuserPassword: changeme</computeroutput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>ldapmodify \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --port 1389 \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindDN "cn=Directory Manager" \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindPassword password \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --defaultAdd \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark<computeroutput>Processing ADD request for uid=newuser,ou=People,dc=example,dc=com
08248b5c5b494aff8d1922e8e0b5777796d7450dmarkADD operation successful for DN uid=newuser,ou=People,dc=example,dc=com</computeroutput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>ldapsearch --port 1389 --baseDN dc=example,dc=com uid=newuser mail</userinput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark<computeroutput>dn: uid=newuser,ou=People,dc=example,dc=com
08248b5c5b494aff8d1922e8e0b5777796d7450dmarkmail: newuser@example.com</computeroutput>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </example>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>The following example prevents client applications from adding or
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <literal>createTimestamp</literal>, <literal>modifiersName</literal>,
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark and <literal>modifyTimestamp</literal> attributes. First, set up the
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark attribute cleanup plugin.</para>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>dsconfig \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark create-plugin \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --port 4444 \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindDN "cn=Directory Manager" \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindPassword password \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --type attribute-cleanup \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --plugin-name "Remove attrs" \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --set enabled:true \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --set remove-inbound-attributes:creatorsName \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --set remove-inbound-attributes:createTimestamp \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --set remove-inbound-attributes:modifiersName \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --set remove-inbound-attributes:modifyTimestamp \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --trustAll \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --no-prompt</userinput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark<computeroutput>dn: uid=badattr,ou=People,dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkuid: newuser
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkobjectClass: person
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkobjectClass: organizationalPerson
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkobjectClass: inetOrgPerson
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkobjectClass: top
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkcn: Bad Attr
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkmail: badattr@example.com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkuserPassword: changeme
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkcreatorsName: cn=Bad Attr
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkcreateTimestamp: Never in a million years.
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkmodifiersName: cn=Directory Manager,cn=Root DNs,cn=config
08248b5c5b494aff8d1922e8e0b5777796d7450dmarkmodifyTimestamp: 20110930164937Z</computeroutput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>ldapmodify \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --port 1389 \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindDN "cn=Directory Manager" \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindPassword password \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --defaultAdd \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark<computeroutput>Processing ADD request for uid=badattr,ou=People,dc=example,dc=com
08248b5c5b494aff8d1922e8e0b5777796d7450dmarkADD operation successful for DN uid=badattr,ou=People,dc=example,dc=com</computeroutput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>ldapsearch --port 1389 --baseDN dc=example,dc=com uid=badattr +</userinput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark<computeroutput>dn: uid=badattr,ou=People,dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarknumSubordinates: 0
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkstructuralObjectClass: inetOrgPerson
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkpwdPolicySubentry: cn=Default Password Policy,cn=Password Policies,cn=config
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarksubschemaSubentry: cn=schema
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkhasSubordinates: false
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkentryDN: uid=badattr,ou=people,dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkentryUUID: 35e5cb0e-e929-49d8-a50f-2df036d60db9
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkpwdChangedTime: 20110930165959.135Z
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkcreatorsName: cn=Directory Manager,cn=Root DNs,cn=config
08248b5c5b494aff8d1922e8e0b5777796d7450dmarkcreateTimestamp: 20110930165959Z</computeroutput>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </example>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </section>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>The Relative Distinguished Name (RDN) refers to the part of an
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark entry's DN that distinguishes it from all other DNs at the same level
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark in the directory tree. For example <literal>uid=bjensen</literal> is
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark the RDN of the entry having DN
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <literal>uid=bjensen,ou=People,dc=example,dc=com</literal>.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>With the <command>ldapmodify</command> command, authorized users
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark can rename entries in the directory.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>When you change the RDN of the entry, you are renaming the entry,
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark modifying the value of the naming attribute, but also modifying the entry's
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark DN.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Sam Carter is changing her last name to Jensen, and changing her
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark login from <literal>scarter</literal> to <literal>sjensen</literal>.
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark The following example renames and changes Sam Carter's entry accordingly.
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark Notice the boolean field, <literal>deleteoldrdn: 1</literal>, which
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark indicates that the previous RDN, <literal>uid: scarter</literal>, should
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark be removed. (Setting <literal>deleteoldrdn: 0</literal> instead would
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark preserve <literal>uid: scarter</literal> on the entry.)</para>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>cat /path/to/scarter-sjensen.ldif</userinput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark<computeroutput>dn: uid=scarter,ou=people,dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkchangetype: modrdn
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarknewrdn: uid=sjensen
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkdeleteoldrdn: 1
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkdn: uid=sjensen,ou=people,dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkchangetype: modify
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkreplace: cn
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkcn: Sam Jensen
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkreplace: sn
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkreplace: homeDirectory
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkreplace: mail
08248b5c5b494aff8d1922e8e0b5777796d7450dmarkmail: sjensen@example.com</computeroutput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>ldapmodify \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --port 1389 \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindDN "uid=kvaughan,ou=people,dc=example,dc=com" \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindPassword bribery \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark<computeroutput>Processing MODIFY DN request for uid=scarter,ou=people,dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkMODIFY DN operation successful for DN uid=scarter,ou=people,dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkProcessing MODIFY request for uid=sjensen,ou=people,dc=example,dc=com
08248b5c5b494aff8d1922e8e0b5777796d7450dmarkMODIFY operation successful for DN uid=sjensen,ou=people,dc=example,dc=com</computeroutput>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </example>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </section>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>When you rename an entry with child entries, the directory has
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark to move all the entries underneath.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>The modify DN operation only works when moving entries in the same
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark backend, under the same suffix. Also, depending on the number of entries
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark you move, this can be a resource-intensive operation.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>With the <command>ldapmodify</command> command, authorized users
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark can move entries in the directory.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <example xml:id="move-entry-example"><?dbfo keep-together="auto"?>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <title>Move: Merging Customer and Employees Under
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>The following example moves
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <literal>ou=People,dc=example,dc=com</literal>, and then moves each
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark employee under <literal>ou=Employees,dc=example,dc=com</literal>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark under <literal>ou=People,dc=example,dc=com</literal> as well, finally
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark removing the empty <literal>ou=Employees,dc=example,dc=com</literal>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark container. Here, <literal>deleteoldrdn: 1</literal> indicates that the
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark old RDN, <literal>ou: Customers</literal>, should be removed from the
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark entry. For employees, <literal>deleteoldrdn: 0</literal> indicates that
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark old RDNs, in this case <literal>uid</literal> attribute values, should
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark be preserved.</para>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark<computeroutput>dn: ou=Customers,dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkchangetype: modrdn
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarknewrdn: ou=People
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkdeleteoldrdn: 1
08248b5c5b494aff8d1922e8e0b5777796d7450dmarknewsuperior: dc=example,dc=com</computeroutput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>ldapmodify \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --port 1389 \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindDN "cn=Directory Manager" \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindPassword password \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark<computeroutput>Processing MODIFY DN request for ou=Customers,dc=example,dc=com
08248b5c5b494aff8d1922e8e0b5777796d7450dmarkMODIFY DN operation successful for DN ou=Customers,dc=example,dc=com</computeroutput>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark# For each employee, construct a spec to move under ou=People.
08248b5c5b494aff8d1922e8e0b5777796d7450dmarkwhile (<>)
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark # Next line folded for readability only. Should not be split.
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark $_ =~ s/dn: (.*?)(,.*)/dn: $1$2\nchangetype: moddn\nnewrdn: $1\n
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark deleteoldrdn: 0\nnewsuperior: ou=People,dc=example,dc=com/;
08248b5c5b494aff8d1922e8e0b5777796d7450dmark}</computeroutput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>ldapsearch --port 1389 --baseDN ou=Employees,dc=example,dc=com uid=* - \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark | move-employees.pl > /tmp/move-employees.ldif</userinput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>head -n 6 /tmp/move-employees.ldif</userinput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark<computeroutput>dn: uid=abarnes,ou=Employees,dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkchangetype: moddn
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarknewrdn: uid=abarnes
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkdeleteoldrdn: 0
08248b5c5b494aff8d1922e8e0b5777796d7450dmarknewsuperior: ou=People,dc=example,dc=com</computeroutput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>ldapmodify \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --port 1389 \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindDN "cn=Directory Manager" \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindPassword password \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark<computeroutput>Processing MODIFY DN request for uid=abarnes,ou=Employees,dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkMODIFY DN operation successful for DN uid=abarnes,ou=Employees,dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkProcessing MODIFY DN request for uid=abergin,ou=Employees,dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkMODIFY DN operation successful for DN uid=abergin,ou=Employees,dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkProcessing MODIFY DN request for uid=wlutz,ou=Employees,dc=example,dc=com
08248b5c5b494aff8d1922e8e0b5777796d7450dmarkMODIFY DN operation successful for DN uid=wlutz,ou=Employees,dc=example,dc=com</computeroutput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>ldapdelete \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --port 1389 \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindDN "cn=Directory Manager" \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindPassword password \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark ou=Employees,dc=example,dc=com</userinput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark<computeroutput>Processing DELETE request for ou=Employees,dc=example,dc=com
08248b5c5b494aff8d1922e8e0b5777796d7450dmarkDELETE operation successful for DN ou=Employees,dc=example,dc=com</computeroutput>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </example>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </section>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>With the <command>ldapmodify</command> command, authorized users
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark can delete entries from the directory.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>The following example uses the subtree delete option to remove
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark all Special Users from the directory.</para>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>ldapdelete \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --port 1389 \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindDN "cn=Directory Manager" \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindPassword password \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --deleteSubtree "ou=Special Users,dc=example,dc=com"</userinput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark<computeroutput>Processing DELETE request for ou=Special Users,dc=example,dc=com
08248b5c5b494aff8d1922e8e0b5777796d7450dmarkDELETE operation successful for DN ou=Special Users,dc=example,dc=com</computeroutput>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </example>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </section>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </section>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <indexterm><primary>Passwords</primary><secondary>Changing</secondary></indexterm>
ec40cc0dc62425cea5d63fd9d984f8614479de25mark authorized users can change and reset user passwords.
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <indexterm>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </indexterm>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>The following example shows Kirsten Vaughan resetting Sam Carter's
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark password. Kirsten has the appropriate privilege to reset Sam's
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark password.</para>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>ldappasswordmodify \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --useStartTLS \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --port 1389 \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindDN "uid=kvaughan,ou=people,dc=example,dc=com" \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindPassword bribery \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --authzID "dn:uid=scarter,ou=people,dc=example,dc=com" \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --newPassword ChangeMe</userinput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark<computeroutput>The LDAP password modify operation was successful</computeroutput>
2acfdfe826160ae86770371c4d751c30a79db51dmark the LDAP Password Modify extended operation.
2acfdfe826160ae86770371c4d751c30a79db51dmark If this extended operation is performed on a connection
2acfdfe826160ae86770371c4d751c30a79db51dmark that is already associated with a user
2acfdfe826160ae86770371c4d751c30a79db51dmark —in other words, when a user first does a bind on the connection,
2acfdfe826160ae86770371c4d751c30a79db51dmark and then requests the LDAP Password Modify extended operation—
2acfdfe826160ae86770371c4d751c30a79db51dmark then the operation is performed as the user associated with the connection.
2acfdfe826160ae86770371c4d751c30a79db51dmark If the user associated with the connection
2acfdfe826160ae86770371c4d751c30a79db51dmark is not the user whose password is being changed,
2acfdfe826160ae86770371c4d751c30a79db51dmark then OpenDJ considers it a password reset.
2acfdfe826160ae86770371c4d751c30a79db51dmark Whenever one user changes another user's password,
2acfdfe826160ae86770371c4d751c30a79db51dmark OpenDJ considers it a password reset.
2acfdfe826160ae86770371c4d751c30a79db51dmark Often password policies specify that users
2acfdfe826160ae86770371c4d751c30a79db51dmark must change their passwords again after a password reset.
2acfdfe826160ae86770371c4d751c30a79db51dmark If you want your application to change a user's password,
2acfdfe826160ae86770371c4d751c30a79db51dmark rather than reset a user's password,
2acfdfe826160ae86770371c4d751c30a79db51dmark have your application request the password change
2acfdfe826160ae86770371c4d751c30a79db51dmark as the user whose password is changing.
2acfdfe826160ae86770371c4d751c30a79db51dmark To change the password as the user, you can
2acfdfe826160ae86770371c4d751c30a79db51dmark bind as the user whose password should be changed,
ec40cc0dc62425cea5d63fd9d984f8614479de25mark >LDAP Password Modify extended operation</link>
2acfdfe826160ae86770371c4d751c30a79db51dmark with an authorization ID but without performing a bind,
2acfdfe826160ae86770371c4d751c30a79db51dmark or use proxied authorization.
2acfdfe826160ae86770371c4d751c30a79db51dmark For instructions on using proxied authorization, see the section on
2acfdfe826160ae86770371c4d751c30a79db51dmark ><citetitle>Configuring Proxied Authorization</citetitle></link>.
ec40cc0dc62425cea5d63fd9d984f8614479de25mark You could also accomplish password reset with the
ec40cc0dc62425cea5d63fd9d984f8614479de25mark although <command>set-password-is-reset</command> is a hidden option,
ec40cc0dc62425cea5d63fd9d984f8614479de25mark supported only for testing.
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>manage-account \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark set-password-is-reset \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindDN "cn=Directory Manager" \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindPassword password \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --targetDN uid=scarter,ou=people,dc=example,dc=com \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --operationValue true</userinput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark<computeroutput>Password Is Reset: true</computeroutput></screen>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </example>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>You can use the <command>ldappasswordmodify</command> command to
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark change your password, as long as you know your current password.</para>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>ldappasswordmodify \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --port 1389 \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --authzID "dn:uid=bjensen,ou=people,dc=example,dc=com" \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --currentPassword hifalutin \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --newPassword secret12</userinput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark<computeroutput>The LDAP password modify operation was successful</computeroutput>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>The same operation works for <literal>cn=Directory
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>ldappasswordmodify \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --port 1389 \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --authzID "dn:cn=Directory Manager" \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --currentPassword password \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --newPassword secret12</userinput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark<computeroutput>The LDAP password modify operation was successful</computeroutput>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </example>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>OpenDJ expects passwords to be UTF-8 encoded (base64 encoded when
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark included in LDIF).</para>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>ldappasswordmodify \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --port 1389 \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindDN uid=bjensen,ou=People,dc=example,dc=com \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindPassword hifalutin \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --currentPassword hifalutin \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --newPassword pàsswȏrd</userinput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark<computeroutput>The LDAP password modify operation was successful</computeroutput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>ldapsearch \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --port 1389 \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindDN uid=bjensen,ou=People,dc=example,dc=com \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindPassword pàsswȏrd \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --baseDN dc=example,dc=com \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark "(uid=bjensen)" cn</userinput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark<computeroutput>dn: uid=bjensen,ou=People,dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkuserPassword: {SSHA}k0eEeCxj9YRXUp8yJn0Z/mwqe+wrcFb1N1gg2g==
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkcn: Barbara Jensen
08248b5c5b494aff8d1922e8e0b5777796d7450dmarkcn: Babs Jensen</computeroutput>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </example>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </section>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <indexterm><primary>Ports</primary><secondary>Settings for tools</secondary></indexterm>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>You can use <filename>~/.opendj/tools.properties</filename> to set
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark the defaults for bind DN, host name, and port number as in the following
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark example.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <programlisting language="ini">hostname=directory.example.com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkbindDN=uid=kvaughan,ou=People,dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>The location on Windows is
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <filename>%UserProfile%/.opendj/tools.properties</filename>.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </section>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <indexterm><primary>Authenticating</primary></indexterm>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Authentication is the act of confirming the identity of a principal.
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark Authorization is the act of determining whether to grant or to deny access to
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark a principal. Authentication is done to make authorization decisions.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>As explained in <link xlink:href="admin-guide#chap-privileges-acis"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark xlink:role="http://docbook.org/xlink/role/olink"><citetitle>Configuring
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark Privileges & Access Control</citetitle></link>, OpenDJ directory server
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark implements fine-grained access control for authorization. What is authorized
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark depends on who is requesting the operation. Directory servers like OpenDJ must
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark first therefore authenticate the principals using the clients before they can
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark authorize or deny access. The LDAP bind operation, where a directory client
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark authenticates with the directory server, is therefore the first LDAP operation
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark in every LDAP session.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Clients bind by providing both a means to find their principal's entry
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark in the directory and also providing some credentials that the directory server
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark can check against their entry.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>In the simplest bind operation, the client provides a zero-length
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark name and a zero-length password. This results in an anonymous bind, meaning
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark the client is authenticated as an anonymous user of the directory. In the
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark simplest examples in <xref linkend="search-ldap" />, notice that no
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark authentication information is provided. The examples work because the
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark client commands default to requesting anonymous binds when you provide no
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark credentials, and because access controls for the sample data allow anonymous
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark clients to read, search, and compare some directory data.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>In a simple bind operation, the client provides an LDAP name, such as
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark the DN identifying its entry, and the corresponding password stored on the
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <literal>userPassword</literal> attribute of the entry. In
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <xref linkend="write-ldap" />, notice that to change directory data the
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark client provides the bind DN and bind password of a user who has permission
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark to change directory data. The commands do not work with a bind DN and bind
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark password because access controls for the sample data only allow authorized
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark users to change directory data.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Users rarely provide client applications with DNs, however. Instead
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark users might provide a client application with an identity string like a user
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark ID or an email address for example. Depending on how the DNs are constructed,
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark the client application can either build the DN directly from the user's
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark identity string, or use a session where the bind has been done with some
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark other identity to search for the user entry based on the user's identity
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark string. Given the DN constructed or found, the client application can then
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark perform a simple bind.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>For example, suppose Babs Jensen enters her email address,
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <literal>bjensen@example.com</literal>, and her password in order to log in.
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark The client application might search for the entry matching
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <literal>(mail=bjensen@example.com)</literal> under base DN
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <literal>dc=example,dc=com</literal>. Alternatively, the client application
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark might know to extract the user ID <literal>bjensen</literal> from the address,
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark and then build the corresponding DN,
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <literal>uid=bjensen,ou=people,dc=example,dc=com</literal> in order to
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark bind.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <indexterm><primary>Identity mappers</primary></indexterm>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>When an identifier string provided by the user can readily be mapped to
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark the user's entry DN, OpenDJ directory server can do the translation between
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark the identifier string and the entry DN. This translation is the job of a
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark component called an identity mapper. Identity mappers are used to perform
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark PLAIN SASL authentication (with a user name and password), SASL GSSAPI
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark authentication (Kerberos V5), SASL CRAM MD5 and DIGEST MD5 authentication.
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark They also handle authorization IDs during password modify extended operations
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark and proxied authorization.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>One use of PLAIN SASL is to translate user names from HTTP Basic
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark authentication to LDAP authentication. The following example shows PLAIN SASL
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark authentication using the default Exact Match identity mapper. In this
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark (contrived) example, Babs Jensen reads the hashed value of her password.
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark (According to the access controls in the example data, Babs must authenticate
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark to read her password.) Notice the authentication ID is her user ID,
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <literal>u:bjensen</literal>, rather than the DN of her entry.</para>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>ldapsearch \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --port 1389 \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --useStartTLS \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --baseDN dc=example,dc=com \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --saslOption mech=PLAIN \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --saslOption authid=u:bjensen \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindPassword hifalutin \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark "(cn=Babs Jensen)" cn userPassword</userinput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark<computeroutput>dn: uid=bjensen,ou=People,dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkcn: Barbara Jensen
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkcn: Babs Jensen
08248b5c5b494aff8d1922e8e0b5777796d7450dmarkuserPassword: {SSHA}7S4Si+vPE513cYQ7otiqb8hjiCzU7XNTv0RPBA==</computeroutput>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>The Exact Match identity mapper searches for a match between the string
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark provided (here, <literal>bjensen</literal>) and the value of a specified
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark attribute (by default the <literal>uid</literal> attribute). If
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark you know users are entering their email addresses, you could create an
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark exact match identity mapper for email addresses, and then use that for PLAIN
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark SASL authentication as in the following example.</para>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>dsconfig \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark create-identity-mapper \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --port 4444 \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindDN "cn=Directory Manager" \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindPassword password \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --mapper-name "Email Mapper" \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --type exact-match \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --set match-attribute:mail \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --set enabled:true \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --no-prompt</userinput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>dsconfig \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark set-sasl-mechanism-handler-prop \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --port 4444 \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindDN "cn=Directory Manager" \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindPassword password \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --handler-name PLAIN \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --set identity-mapper:"Email Mapper" \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --no-prompt</userinput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>ldapsearch \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --port 1389 \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --useStartTLS \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --baseDN dc=example,dc=com \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --saslOption mech=PLAIN \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --saslOption authid=u:bjensen@example.com \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindPassword hifalutin \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark "(cn=Babs Jensen)" cn userPassword</userinput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark<computeroutput>dn: uid=bjensen,ou=People,dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkcn: Barbara Jensen
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkcn: Babs Jensen
08248b5c5b494aff8d1922e8e0b5777796d7450dmarkuserPassword: {SSHA}7S4Si+vPE513cYQ7otiqb8hjiCzU7XNTv0RPBA==</computeroutput>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>The Regular Expression identity mapper uses a regular expression to
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark extract a substring from the string provided, and then searches for a match
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark between the substring and the value of a specified attribute. In the case
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark of example data where an email address is <replaceable>user ID</replaceable>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark + @ + <replaceable>domain</replaceable>, you can use the default Regular
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark Expression identity mapper in the same way as the email mapper from the
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark previous example. The default regular expression pattern is
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <literal>^([^@]+)@.+$</literal>, and the part of the identity string matching
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <literal>([^@]+)</literal> is used to find the entry by user ID.</para>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>dsconfig \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark set-sasl-mechanism-handler-prop \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --port 4444 \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindDN "cn=Directory Manager" \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindPassword password \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --handler-name PLAIN \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --set identity-mapper:"Regular Expression" \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --no-prompt</userinput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>ldapsearch \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --port 1389 \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --useStartTLS \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --baseDN dc=example,dc=com \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --saslOption mech=PLAIN \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --saslOption authid=u:bjensen@example.com \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindPassword hifalutin \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark "(cn=Babs Jensen)" cn userPassword</userinput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark<computeroutput>dn: uid=bjensen,ou=People,dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkcn: Barbara Jensen
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkcn: Babs Jensen
08248b5c5b494aff8d1922e8e0b5777796d7450dmarkuserPassword: {SSHA}7S4Si+vPE513cYQ7otiqb8hjiCzU7XNTv0RPBA==</computeroutput>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Try the <command>dsconfig</command> command interactively to experiment
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark with <literal>match-pattern</literal> and <literal>replace-pattern</literal>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark settings for the Regular Expression identity mapper. The
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <literal>match-pattern</literal> can be any regular expression supported by
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </section>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <indexterm><primary>Proxied authorization</primary></indexterm>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Proxied authorization provides a standard control as defined in <link
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark xlink:href='http://tools.ietf.org/html/rfc4370'>RFC 4370</link> (and an
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark earlier Internet-Draft) for binding with the user credentials of a proxy, who
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark carries out LDAP operations on behalf of other users. You might use proxied
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark authorization, for example, to have your application bind with its
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark credentials, and then carry out operations as the users who login to the
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark application.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Suppose you have an administrative directory client application that
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark has an entry in the directory with DN
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <literal>cn=My App,ou=Apps,dc=example,dc=com</literal>. You can give that
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark application the access rights and privileges to use proxied authorization.
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark The default access control for OpenDJ permits authenticated users to use
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark the proxied authorization control.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Suppose also that when directory administrator, Kirsten Vaughan, logs
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark in to your application to change Babs Jensen's entry, your application looks
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark up Kirsten's entry, and finds that she has DN
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <literal>uid=kvaughan,ou=People,dc=example,dc=com</literal>. For the example
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark commands in the following procedure. My App uses proxied authorization to
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark make a change to Babs's entry as Kirsten.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Grant access to applications that can use proxied authorization.</para>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>ldapmodify \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --port 1389 \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindDN "cn=Directory Manager" \
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindPassword password
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkdn: dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkchangetype: modify
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkaci: (target="ldap:///dc=example,dc=com") (targetattr ="*
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark ")(version 3.0; acl "Allow apps proxied auth"; allow(all, proxy
08248b5c5b494aff8d1922e8e0b5777796d7450dmark )(userdn = "ldap:///cn=*,ou=Apps,dc=example,dc=com");)</userinput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark<computeroutput>Processing MODIFY request for dc=example,dc=com
08248b5c5b494aff8d1922e8e0b5777796d7450dmarkMODIFY operation successful for DN dc=example,dc=com</computeroutput>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Grant the privilege to use proxied authorization to My App.</para>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>ldapmodify \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --port 1389 \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindDN "cn=Directory Manager" \
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindPassword password
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkdn: cn=My App,ou=Apps,dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkchangetype: modify
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkadd: ds-privilege-name
08248b5c5b494aff8d1922e8e0b5777796d7450dmarkds-privilege-name: proxied-auth</userinput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark<computeroutput>Processing MODIFY request for cn=My App,ou=Apps,dc=example,dc=com
08248b5c5b494aff8d1922e8e0b5777796d7450dmarkMODIFY operation successful for DN cn=My App,ou=Apps,dc=example,dc=com</computeroutput>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Test that My App can use proxied authorization.</para>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>ldapmodify \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --port 1389 \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindDN "cn=My App,ou=Apps,dc=example,dc=com" \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindPassword password \
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --proxyAs "dn:uid=kvaughan,ou=People,dc=example,dc=com"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkdn: uid=bjensen,ou=People,dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkchangetype: modify
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkreplace: description
08248b5c5b494aff8d1922e8e0b5777796d7450dmarkdescription: Changed through proxied auth</userinput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark<computeroutput>Processing MODIFY request for uid=bjensen,ou=People,dc=example,dc=com
08248b5c5b494aff8d1922e8e0b5777796d7450dmarkMODIFY operation successful for DN uid=bjensen,ou=People,dc=example,dc=com</computeroutput>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </procedure>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>If you need to map authorization identifiers using the
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <literal>u:</literal> form rather than using <literal>dn:</literal>, you can
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark set the identity mapper with the global configuration setting,
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <literal>proxied-authorization-identity-mapper</literal>. For example, if you
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark get user ID values from the client, such as <literal>bjensen</literal>, you
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark can use the Exact Match Identity Mapper to match those to DNs based on an
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark attribute of the entry. Use the <command>dsconfig</command> command
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark interactively to investigate the settings you need.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </section>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>One alternative to simple binds with user name/password combinations
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark consists in storing a digital certificate on the user entry, and then using
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark the certificate as credentials during the bind. You can use this mechanism for
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark example to let applications bind without using passwords.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Simply by setting up a secure connection with a certificate, the client
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark is in effect authenticating to the server. The server must close the
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark connection if it cannot trust the client certificate. However, the process
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark of establishing a secure connection does not in itself identify the client
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark to OpenDJ directory server.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Instead when binding with a certificate, the client must request the
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark SASL External mechanism by which OpenDJ directory server maps the certificate
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark to the client entry in the directory. When it finds a match, OpenDJ sets the
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark authorization identity for the connection to that of the client, and the bind
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark is successful.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>For the whole process of authenticating with a certificate to work
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark smoothly, OpenDJ and the client must trust each others' certificates, the
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark client certificate must be stored on the client entry in the directory, and
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark OpenDJ must be configured to map the certificate to the client entry.</para>
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark <itemizedlist>
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark This section includes the following procedures and examples.
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark <listitem>
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark </listitem>
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark <listitem>
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark </listitem>
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark <listitem>
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark </listitem>
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark <listitem>
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark </listitem>
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark </itemizedlist>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <title>To Add Certificate Information to an Entry</title>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Before trying to bind to OpenDJ directory server using a certificate,
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark create a certificate, and then add the certificate attributes to the
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark entry.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para><link xlink:href="http://opendj.forgerock.org/Example.ldif"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark xlink:show="new">Example.ldif</link> includes an entry for
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <literal>cn=My App,ou=Apps,dc=example,dc=com</literal>. Examples in this
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark section use that entry, and use the Java <command>keytool</command> command
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark to manage the certificate.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Create a certificate using the DN of the client entry as the
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark distinguished name string.</para>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>keytool \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark -alias myapp-cert \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark -keyalg rsa \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark -dname "cn=My App,ou=Apps,dc=example,dc=com" \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark -keystore keystore \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark -storepass changeit \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark -keypass changeit</userinput>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>If you cannot get the certificate signed by a Certificate Authority,
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark self-sign the certificate.</para>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>keytool \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark -selfcert \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark -alias myapp-cert \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark -validity 7300 \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark -keystore keystore \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark -storepass changeit \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark -keypass changeit</userinput>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Make note of the certificate fingerprints.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Later in this procedure you update the client application entry with
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark the MD5 fingerprint, which in this example is
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <literal>48:AC:F9:13:11:E0:AB:C4:65:A2:83:9E:DB:FE:0C:37</literal>.</para>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>keytool \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark -alias myapp-cert \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark -keystore keystore \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark -storepass changeit</userinput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark<computeroutput>Alias name: myapp-cert
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkCreation date: Jan 18, 2013
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkEntry type: PrivateKeyEntry
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkCertificate chain length: 1
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkCertificate[1]:
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkOwner: CN=My App, OU=Apps, DC=example, DC=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkIssuer: CN=My App, OU=Apps, DC=example, DC=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkSerial number: 5ae2277
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkValid from: Fri Jan 18 18:27:09 CET 2013 until: Thu Jan 13 18:27:09 CET 2033
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkCertificate fingerprints:
08248b5c5b494aff8d1922e8e0b5777796d7450dmark MD5: 48:AC:F9:13:11:E0:AB:C4:65:A2:83:9E:DB:FE:0C:37
08248b5c5b494aff8d1922e8e0b5777796d7450dmark SHA1: F9:61:54:37:AA:C1:BC:92:45:07:64:4B:23:6C:BC:C9:CD:1D:44:0F
08248b5c5b494aff8d1922e8e0b5777796d7450dmark SHA256: 2D:B1:58:CD:33:40:E9:...:FD:61:EA:C9:FF:6A:19:93:FE:E4:84:E3
08248b5c5b494aff8d1922e8e0b5777796d7450dmark Signature algorithm name: SHA256withRSA
08248b5c5b494aff8d1922e8e0b5777796d7450dmark Version: 3
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkExtensions:
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark#1: ObjectId: 2.5.29.14 Criticality=false
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkSubjectKeyIdentifier [
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkKeyIdentifier [
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark0000: 54 C0 C5 9C 73 37 85 4B F2 3B D3 37 FD 45 0A AB T...s7.K.;.7.E..
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark0010: C9 6B 32 95 .k2.
08248b5c5b494aff8d1922e8e0b5777796d7450dmark]</computeroutput>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Export the certificate to a file in binary format.</para>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>keytool \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark -alias myapp-cert \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark -keystore keystore \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark -storepass changeit \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark -keypass changeit \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark<computeroutput>Certificate stored in file </path/to/myapp-cert.crt></computeroutput>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Modify the entry to add attributes related to the certificate.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>By default, you need the <literal>userCertificate</literal>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark value.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>If you want OpenDJ to map the certificate to its fingerprint, use
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <literal>ds-certificate-fingerprint</literal>. This example uses the MD5
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark fingerprint, which corresponds to the default setting for the Fingerprint
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark Certificate Mapper.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>If you want to map the certificate subject DN to an attribute of the
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark entry, use <literal>ds-certificate-subject-dn</literal>.</para>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark<computeroutput>dn: cn=My App,ou=Apps,dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkchangetype: modify
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkadd: objectclass
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkobjectclass: ds-certificate-user
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkadd: ds-certificate-fingerprint
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkds-certificate-fingerprint: 48:AC:F9:13:11:E0:AB:C4:65:A2:83:9E:DB:FE:0C:37
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkadd: ds-certificate-subject-dn
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkds-certificate-subject-dn: CN=My App, OU=Apps, DC=example, DC=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkadd: userCertificate;binary
08248b5c5b494aff8d1922e8e0b5777796d7450dmarkuserCertificate;binary:<file:///path/to/myapp-cert.crt</computeroutput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>ldapmodify \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --port 1389 \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindDN "cn=Directory Manager" \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindPassword password \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark<computeroutput>Processing MODIFY request for cn=My App,ou=Apps,dc=example,dc=com
08248b5c5b494aff8d1922e8e0b5777796d7450dmarkMODIFY operation successful for DN cn=My App,ou=Apps,dc=example,dc=com</computeroutput>
8adbd87b84c38ef1b33c97d49ae6d49f95ac53e0mark$ <userinput>ldapsearch \
8adbd87b84c38ef1b33c97d49ae6d49f95ac53e0mark --port 1389 \
8adbd87b84c38ef1b33c97d49ae6d49f95ac53e0mark --baseDN dc=example,dc=com \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark "(cn=My App)"</userinput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark<computeroutput>dn: cn=My App,ou=Apps,dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkds-certificate-fingerprint: 4B:F5:CF:2C:2D:B3:86:14:FF:43:A8:37:17:DD:E7:55
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkuserCertificate;binary:: MIIDOzCCAiOgAwIBAgIESfC6IjANBgkqhkiG9w0BAQsFADBOMRMwEQY
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark KCZImiZPyLGQBGRYDY29tMRcwFQYKCZImiZPyLGQBGRYHZXhhbXBsZTENMAsGA1UECxMEQXBwczEPMA
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark 0GA1UEAxMGTXkgQXBwMB4XDTEzMDExNzE3MTEwM1oXDTEzMDQxNzE3MTEwM1owTjETMBEGCgmSJomT8
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark ixkARkWA2NvbTEXMBUGCgmSJomT8ixkARkWB2V4YW1wbGUxDTALBgNVBAsTBEFwcHMxDzANBgNVBAMT
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark Bk15IEFwcDCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAJQYq+jG4ZQdNkyBT4OQBZ0sFkl
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark X5o2yBViDMGl1sSWIRGLpFwu6iq1chndPBJYTC+FkT66yEEOwWOpSfcYdFHkMQP0qp5A8mgP6bYkeH1
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark ROvQ1nhLs0ILuksR10CVIQ5b1zv6bGEFhA9gSKmpHfQOSt9PXq8+kuz+4RgZk9Il28tgDNMm91wSJr7
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark kqi5g7a2a7Io5s9L2FeLhVSBYwinWQnASk8nENrhcE0hHkrpGsaxdhIQBQQvm+SRC0dI4E9iwBGI3Lw
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark lV3a4KTa5DlYD6cDREI6B8XlSdc1DaIhwC8CbsE0WJQoCERSURdjkuHrPck6f69HKUFRiC7JMT3dFbs
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark CAwEAAaMhMB8wHQYDVR0OBBYEFFTAxZxzN4VL8jvTN/1FCqvJazKVMA0GCSqGSIb3DQEBCwUAA4IBAQ
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark BXsAIEw7I5XUzLFHvXb2N0hmW/Vmhb/Vlv9LTT8JcCRJy4zaiyS9Q+Sp9zQUkrXauFnNAhJLwpAymjZ
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark MCOq1Th1bw9LnIzbccPQ/1+ZHLKDU5pgnc5BcvaV6Zl6COLLH2OOt0XMZ/OrODBV1M6STfhChqcowff
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark xp72pWMQe+kpZfzjeDBk4kK2hUNTZsimB9qRyrDAMCIXdmdmFv1o07orxjy8c/6S1329swiiVqFckBR
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark aXIa8wCcXjpQbZacDODeKk6wZIKxw4miLg1YByCMa7vkUfz+Jj+JHgbHjyoT/G82mtDbX02chLgXbDm
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark xJPFN3mwAC7NEkSPbqd35nJlf3
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkobjectClass: person
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkobjectClass: inetOrgPerson
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkobjectClass: organizationalPerson
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkobjectClass: ds-certificate-user
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkobjectClass: top
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkds-certificate-subject-dn: CN=My App, OU=Apps, DC=example, DC=com
08248b5c5b494aff8d1922e8e0b5777796d7450dmarksn: App</computeroutput>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>When using a self-signed certificate, import the client certificate
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark into the trust store for OpenDJ.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>When the client presents its certificate to OpenDJ, by default OpenDJ
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark has to be able to trust the client certificate before it can accept the
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark connection. If OpenDJ cannot trust the client certificate, it cannot
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark establish a secure connection.</para>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>keytool \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark -alias myapp-cert \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark -storepass `cat /path/to/opendj/config/keystore.pin`</userinput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark<computeroutput>Owner: CN=My App, OU=Apps, DC=example, DC=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkIssuer: CN=My App, OU=Apps, DC=example, DC=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkSerial number: 5ae2277
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkValid from: Fri Jan 18 18:27:09 CET 2013 until: Thu Jan 13 18:27:09 CET 2033
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkCertificate fingerprints:
08248b5c5b494aff8d1922e8e0b5777796d7450dmark MD5: 48:AC:F9:13:11:E0:AB:C4:65:A2:83:9E:DB:FE:0C:37
08248b5c5b494aff8d1922e8e0b5777796d7450dmark SHA1: F9:61:54:37:AA:C1:BC:92:45:07:64:4B:23:6C:BC:C9:CD:1D:44:0F
08248b5c5b494aff8d1922e8e0b5777796d7450dmark SHA256: 2D:B1:58:CD:33:40:E9:...:FD:61:EA:C9:FF:6A:19:93:FE:E4:84:E3
08248b5c5b494aff8d1922e8e0b5777796d7450dmark Signature algorithm name: SHA256withRSA
08248b5c5b494aff8d1922e8e0b5777796d7450dmark Version: 3
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkExtensions:
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark#1: ObjectId: 2.5.29.14 Criticality=false
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkSubjectKeyIdentifier [
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkKeyIdentifier [
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark0000: 54 C0 C5 9C 73 37 85 4B F2 3B D3 37 FD 45 0A AB T...s7.K.;.7.E..
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark0010: C9 6B 32 95 .k2.
08248b5c5b494aff8d1922e8e0b5777796d7450dmarkTrust this certificate? [no]:</computeroutput> <userinput>yes</userinput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark<computeroutput>Certificate was added to keystore</computeroutput>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>When using a certificate signed by a CA whose certificate is not
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark delivered with the Java runtime environment<footnote>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para><filename>$JAVA_HOME/jre/lib/security/cacerts</filename> holds the
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark certificates for many CAs. To get the full list, use the following
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark command.</para>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>keytool \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark -storepass changeit</userinput>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark into the Java runtime environment trust store, or into the OpenDJ trust
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark store as shown in the following example.</para>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>keytool \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark -alias ca-cert \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark -storepass `cat /path/to/opendj/config/keystore.pin`</userinput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark<computeroutput>Owner: EMAILADDRESS=admin@example.com, CN=Example CA, O=Example Corp, C=FR
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkIssuer: EMAILADDRESS=admin@example.com, CN=Example CA, O=Example Corp, C=FR
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkSerial number: d4586ea05c878b0c
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkValid from: Tue Jan 29 09:30:31 CET 2013 until: Mon Jan 24 09:30:31 CET 2033
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkCertificate fingerprints:
08248b5c5b494aff8d1922e8e0b5777796d7450dmark MD5: 8A:83:61:9B:E7:18:A2:21:CE:92:94:96:59:68:60:FA
08248b5c5b494aff8d1922e8e0b5777796d7450dmark SHA1: 01:99:18:38:3A:57:D7:92:7B:D6:03:8C:7B:E4:1D:37:45:0E:29:DA
08248b5c5b494aff8d1922e8e0b5777796d7450dmark SHA256: 5D:20:F1:86:CC:CD:64:50:1E:54:...:DF:15:43:07:69:44:00:FB:36:CF
08248b5c5b494aff8d1922e8e0b5777796d7450dmark Signature algorithm name: SHA1withRSA
08248b5c5b494aff8d1922e8e0b5777796d7450dmark Version: 3
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkExtensions:
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark#1: ObjectId: 2.5.29.35 Criticality=false
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkAuthorityKeyIdentifier [
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkKeyIdentifier [
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark0000: 30 07 67 7D 1F 09 B6 E6 90 85 95 58 94 37 FD 31 0.g........X.7.1
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark0010: 03 D4 56 7B ..V.
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark[EMAILADDRESS=admin@example.com, CN=Example CA, O=Example Corp, C=FR]
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkSerialNumber: [ d4586ea0 5c878b0c]
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark#2: ObjectId: 2.5.29.19 Criticality=false
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkBasicConstraints:[
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark PathLen:2147483647
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark#3: ObjectId: 2.5.29.14 Criticality=false
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkSubjectKeyIdentifier [
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkKeyIdentifier [
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark0000: 30 07 67 7D 1F 09 B6 E6 90 85 95 58 94 37 FD 31 0.g........X.7.1
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark0010: 03 D4 56 7B ..V.
08248b5c5b494aff8d1922e8e0b5777796d7450dmarkTrust this certificate? [no]:</computeroutput> <userinput>yes</userinput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark<computeroutput>Certificate was added to keystore</computeroutput>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>If you updated the OpenDJ trust store to add a certificate, restart
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark OpenDJ to make sure it reads the updated trust store and can recognize the
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark certificate.</para>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark<computeroutput>Stopping Server...
08248b5c5b494aff8d1922e8e0b5777796d7450dmark... The Directory Server has started successfully</computeroutput>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </procedure>
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark The Java <command>keytool</command> command does not support
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark importing trusted certificates into a PKCS #12 format store.
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark Yet, Java does support
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark creating a PKCS #12 format key store,
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark and using an existing PKCS #12 format store as a trust store.
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark You can use a PKCS #12 store as an OpenDJ trust store.
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark The following example shows how to try the full procedure
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark by using the keytool command with OpenDJ server and commands.
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark Create key pair:
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark$ keytool \
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark -alias myapp-cert \
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark -keyalg rsa \
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark -dname "cn=My App,ou=Apps,dc=example,dc=com" \
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark -storepass changeit \
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark -keypass changeit \
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark -storetype pkcs12
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark Sign certificate:
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark$ keytool \
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark -selfcert \
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark -alias myapp-cert \
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark -validity 7300 \
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark -storepass changeit \
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark -keypass changeit \
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark -storetype pkcs12
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark Note certificate fingerprints:
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark$ keytool \
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark -alias myapp-cert \
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark -storepass changeit \
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark -storetype pkcs12
03a36f717f3d2ff1c4e80f593862b364b21a2e72markAlias name: myapp-cert
03a36f717f3d2ff1c4e80f593862b364b21a2e72markCreation date: Apr 10, 2014
03a36f717f3d2ff1c4e80f593862b364b21a2e72markEntry type: PrivateKeyEntry
03a36f717f3d2ff1c4e80f593862b364b21a2e72markCertificate chain length: 1
03a36f717f3d2ff1c4e80f593862b364b21a2e72markCertificate[1]:
03a36f717f3d2ff1c4e80f593862b364b21a2e72markOwner: CN=My App, OU=Apps, DC=example, DC=com
03a36f717f3d2ff1c4e80f593862b364b21a2e72markIssuer: CN=My App, OU=Apps, DC=example, DC=com
03a36f717f3d2ff1c4e80f593862b364b21a2e72markSerial number: 1b93b494
03a36f717f3d2ff1c4e80f593862b364b21a2e72markValid from: Thu Apr 10 08:25:01 CEST 2014 until: Wed Apr 05 08:25:01 CEST 2034
03a36f717f3d2ff1c4e80f593862b364b21a2e72markCertificate fingerprints:
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark MD5: 2B:8D:27:D6:1D:D1:A5:5F:14:E7:A8:C1:96:F9:C1:9F
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark SHA1: 1D:A2:BF:A6:29:8C:13:81:A4:E5:77:9E:D5:67:CD:C8:E6:AD:6E:A3
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark SHA256: 80:47:B8:5C:E7:22:BB:4E:5E:48:8B:84:38:9F:E8:2C:7C:87:6E:9C:20:A2:E2:5F:A7:7A:10:0E:C8:AE:60:85
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark Signature algorithm name: SHA256withRSA
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark Version: 3
03a36f717f3d2ff1c4e80f593862b364b21a2e72markExtensions:
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark#1: ObjectId: 2.5.29.14 Criticality=false
03a36f717f3d2ff1c4e80f593862b364b21a2e72markSubjectKeyIdentifier [
03a36f717f3d2ff1c4e80f593862b364b21a2e72markKeyIdentifier [
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark0000: 93 C5 DE 6A 5D D4 84 99 38 A8 6D 9D BF B9 FF 5E ...j]...8.m....^
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark0010: B5 05 F1 87 ....
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark Export certificate:
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark$ keytool \
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark -alias myapp-cert \
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark -storepass changeit \
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark -keypass changeit \
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark -storetype pkcs12
03a36f717f3d2ff1c4e80f593862b364b21a2e72markCertificate stored in file <myapp-cert.crt>
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark Update My App entry with certificate:
03a36f717f3d2ff1c4e80f593862b364b21a2e72markdn: cn=My App,ou=Apps,dc=example,dc=com
03a36f717f3d2ff1c4e80f593862b364b21a2e72markchangetype: modify
03a36f717f3d2ff1c4e80f593862b364b21a2e72markadd: objectclass
03a36f717f3d2ff1c4e80f593862b364b21a2e72markobjectclass: ds-certificate-user
03a36f717f3d2ff1c4e80f593862b364b21a2e72markadd: ds-certificate-fingerprint
03a36f717f3d2ff1c4e80f593862b364b21a2e72markds-certificate-fingerprint: 2B:8D:27:D6:1D:D1:A5:5F:14:E7:A8:C1:96:F9:C1:9F
03a36f717f3d2ff1c4e80f593862b364b21a2e72markadd: ds-certificate-subject-dn
03a36f717f3d2ff1c4e80f593862b364b21a2e72markds-certificate-subject-dn: CN=My App, OU=Apps, DC=example, DC=com
03a36f717f3d2ff1c4e80f593862b364b21a2e72markadd: userCertificate;binary
03a36f717f3d2ff1c4e80f593862b364b21a2e72markuserCertificate;binary:<file:///path/to/myapp-cert.crt
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark XML comments cannot include two dashes in a row,
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark so change - - in the following examples before trying these.
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark$ ldapmodify \
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark - -port 1389 \
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark - -bindDN "cn=Directory Manager" \
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark - -bindPassword password \
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark - -filename /path/to/addcert.ldif
03a36f717f3d2ff1c4e80f593862b364b21a2e72markProcessing MODIFY request for cn=My App,ou=Apps,dc=example,dc=com
03a36f717f3d2ff1c4e80f593862b364b21a2e72markMODIFY operation successful for DN cn=My App,ou=Apps,dc=example,dc=com
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark$ ldapsearch \
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark - -port 1389 \
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark - -baseDN dc=example,dc=com \
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark "(cn=My App)"
03a36f717f3d2ff1c4e80f593862b364b21a2e72markdn: cn=My App,ou=Apps,dc=example,dc=com
03a36f717f3d2ff1c4e80f593862b364b21a2e72markobjectClass: person
03a36f717f3d2ff1c4e80f593862b364b21a2e72markobjectClass: inetOrgPerson
03a36f717f3d2ff1c4e80f593862b364b21a2e72markobjectClass: organizationalPerson
03a36f717f3d2ff1c4e80f593862b364b21a2e72markobjectClass: ds-certificate-user
03a36f717f3d2ff1c4e80f593862b364b21a2e72markobjectClass: top
03a36f717f3d2ff1c4e80f593862b364b21a2e72markuserCertificate;binary:: MIIDOzCCAiOgAwIBAgIEG5O0lDANBgkqhkiG9w0BAQsFADBOMRMwEQY
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark KCZImiZPyLGQBGRYDY29tMRcwFQYKCZImiZPyLGQBGRYHZXhhbXBsZTENMAsGA1UECxMEQXBwczEPMA
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark 0GA1UEAxMGTXkgQXBwMB4XDTE0MDQxMDA2MjUwMVoXDTM0MDQwNTA2MjUwMVowTjETMBEGCgmSJomT8
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark ixkARkWA2NvbTEXMBUGCgmSJomT8ixkARkWB2V4YW1wbGUxDTALBgNVBAsTBEFwcHMxDzANBgNVBAMT
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark Bk15IEFwcDCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAJFg2rAIy3EyJWXWnBgqGTP9bSe
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark AeykCC1lOF+AKDkybAn4igB6JDB+0V1n80G28TZrswnCxQj5G7KJg47OjvRG8ZKuMq96++sd9uKeIVU
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark a+Ekl9lXzGmMXopVYOFyAWeciKQMGnMdNcaKXReoKU5QlR+nUeIYZKNCDMqwjVL7E3UibDQKfvyZ9B+
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark O5CVfWWceVIw1A8xThtARipPppA0h3gopo760llhj/7urHmj84HkLWJqqOHEdujfO61q8tu0Hpld928
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark BjkF/BcnzANkqrbnoc/v3ggsIVyIOoe+NqYkpoGz7phEBcap+/5EuR6tudlsXjaNyNmH4Ge8ictdlWU
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark CAwEAAaMhMB8wHQYDVR0OBBYEFJPF3mpd1ISZOKhtnb+5/161BfGHMA0GCSqGSIb3DQEBCwUAA4IBAQ
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark A3KEYJaEXXf5nzOfJXEX02tV+Fi9Chc7Cor37ldRYBQjjIqBr0Gsk9NbHwWPQE1mQ24aHcS2wqgQ+rT
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark KxLWOC6WPrjwaL7Wx5jojqEc6utg7zqomvtDzxwqirdgnh5Fm+2QtRy3muC6WmjjsK6CMh5FrH/O9b9
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark C9tqGMy4ukUVHpEIZ/sUiS8LvxsYUO+UPuV2A7OcWG3yOZD/lBoGm+o3Oh7NXM1vXXoZzU8PAP/HCF3
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark DrLICKWO/imI8kvOTyrdjf2FSoEEXa4OXiXeh/ZXa/zWRSuYB1WJ/cg/aYRjCy1CJIDtpP9eRp3cJVE
03a36f717f3d2ff1c4e80f593862b364b21a2e72markds-certificate-fingerprint: 2B:8D:27:D6:1D:D1:A5:5F:14:E7:A8:C1:96:F9:C1:9F
03a36f717f3d2ff1c4e80f593862b364b21a2e72markds-certificate-subject-dn: CN=My App, OU=Apps, DC=example, DC=com
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark Configure PKCS #12 trust store.
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark$ dsconfig \
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark set-trust-manager-provider-prop \
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark - -port 4444 \
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark - -bindDN "cn=Directory Manager" \
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark - -bindPassword password \
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark - -provider-name PKCS12 \
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark - -set enabled:true \
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark - -set trust-store-pin:changeit \
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark - -no-prompt \
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark - -trustAll
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark$ dsconfig \
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark get-trust-manager-provider-prop \
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark - -port 4444 \
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark - -bindDN "cn=Directory Manager" \
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark - -bindPassword password \
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark - -provider-name PKCS12 \
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark - -no-prompt \
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark - -trustAll
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark$ stop-ds - -restart
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark Configure LDAPS connection handler to use PKCS #12 trust store.
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark$ dsconfig \
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark set-connection-handler-prop \
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark - -port 4444 \
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark - -bindDN "cn=Directory Manager" \
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark - -bindPassword password \
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark - -handler-name "LDAPS Connection Handler" \
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark - -set trust-manager-provider:PKCS12 \
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark - -no-prompt \
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark - -trustAll
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark Create JKS key store from PKCS #12 key store.
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark$ keytool \
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark -importkeystore \
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark -srckeystore /path/to/opendj/config/truststore.p12 \
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark -srcstoretype pkcs12 \
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark -srcstorepass changeit \
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark -srckeypass changeit \
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark -srcalias myapp-cert \
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark -destkeystore keystore \
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark -deststoretype jks \
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark -deststorepass changeit \
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark -destkeypass changeit \
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark[Storing keystore]
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark$ keytool \
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark -keystore keystore \
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark -storepass changeit \
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark -keypass changeit
03a36f717f3d2ff1c4e80f593862b364b21a2e72markKeystore type: JKS
03a36f717f3d2ff1c4e80f593862b364b21a2e72markKeystore provider: SUN
03a36f717f3d2ff1c4e80f593862b364b21a2e72markYour keystore contains 1 entry
03a36f717f3d2ff1c4e80f593862b364b21a2e72markmyapp-cert, Apr 10, 2014, PrivateKeyEntry,
03a36f717f3d2ff1c4e80f593862b364b21a2e72markCertificate fingerprint (SHA1): 1D:A2:BF:A6:29:8C:13:81:A4:E5:77:9E:D5:67:CD:C8:E6:AD:6E:A3
03a36f717f3d2ff1c4e80f593862b364b21a2e72markmark@Mark-Craigs-MacBook-Pro bin$ keytool -list -keystore keystore -storepass changeit -keypass changeit -v
03a36f717f3d2ff1c4e80f593862b364b21a2e72markKeystore type: JKS
03a36f717f3d2ff1c4e80f593862b364b21a2e72markKeystore provider: SUN
03a36f717f3d2ff1c4e80f593862b364b21a2e72markYour keystore contains 1 entry
03a36f717f3d2ff1c4e80f593862b364b21a2e72markAlias name: myapp-cert
03a36f717f3d2ff1c4e80f593862b364b21a2e72markCreation date: Apr 10, 2014
03a36f717f3d2ff1c4e80f593862b364b21a2e72markEntry type: PrivateKeyEntry
03a36f717f3d2ff1c4e80f593862b364b21a2e72markCertificate chain length: 1
03a36f717f3d2ff1c4e80f593862b364b21a2e72markCertificate[1]:
03a36f717f3d2ff1c4e80f593862b364b21a2e72markOwner: CN=My App, OU=Apps, DC=example, DC=com
03a36f717f3d2ff1c4e80f593862b364b21a2e72markIssuer: CN=My App, OU=Apps, DC=example, DC=com
03a36f717f3d2ff1c4e80f593862b364b21a2e72markSerial number: 1b93b494
03a36f717f3d2ff1c4e80f593862b364b21a2e72markValid from: Thu Apr 10 08:25:01 CEST 2014 until: Wed Apr 05 08:25:01 CEST 2034
03a36f717f3d2ff1c4e80f593862b364b21a2e72markCertificate fingerprints:
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark MD5: 2B:8D:27:D6:1D:D1:A5:5F:14:E7:A8:C1:96:F9:C1:9F
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark SHA1: 1D:A2:BF:A6:29:8C:13:81:A4:E5:77:9E:D5:67:CD:C8:E6:AD:6E:A3
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark SHA256: 80:47:B8:5C:E7:22:BB:4E:5E:48:8B:84:38:9F:E8:2C:7C:87:6E:9C:20:A2:E2:5F:A7:7A:10:0E:C8:AE:60:85
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark Signature algorithm name: SHA256withRSA
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark Version: 3
03a36f717f3d2ff1c4e80f593862b364b21a2e72markExtensions:
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark#1: ObjectId: 2.5.29.14 Criticality=false
03a36f717f3d2ff1c4e80f593862b364b21a2e72markSubjectKeyIdentifier [
03a36f717f3d2ff1c4e80f593862b364b21a2e72markKeyIdentifier [
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark0000: 93 C5 DE 6A 5D D4 84 99 38 A8 6D 9D BF B9 FF 5E ...j]...8.m....^
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark0010: B5 05 F1 87 ....
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark*******************************************
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark*******************************************
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark Verify SSL mutual auth.
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark$ ldapsearch \
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark - -port 1636 \
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark - -baseDN dc=example,dc=com \
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark - -useSSL \
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark - -useSASLExternal \
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark - -certNickName myapp-cert \
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark - -keyStorePath keystore \
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark - -keyStorePassword changeit \
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark - -trustStorePasswordFile /path/to/opendj/config/keystore.pin \
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark "(cn=My App)" userPassword
03a36f717f3d2ff1c4e80f593862b364b21a2e72markdn: cn=My App,ou=Apps,dc=example,dc=com
03a36f717f3d2ff1c4e80f593862b364b21a2e72markuserPassword: {SSHA}9jjvsv9wlTW7Ikflzc2/wMNBjAN6G4CbbTKYIw==
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark Add the PKCS #12 format store to OpenDJ's configuration.
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark By default, OpenDJ expects the store
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark to be <filename>/path/to/opendj/config/truststore.p12</filename>.
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark The following example uses that default.
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark$ <userinput>cp /path/to/<replaceable>pkcs12-store</replaceable> /path/to/opendj/config/truststore.p12</userinput>
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark Here, <replaceable>pkcs12-store</replaceable> is the file name
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark of the PKCS #12 format store.
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark Configure the OpenDJ PKCS12 trust manager provider
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark to use the PKCS #12 store,
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark and restart OpenDJ server to force it to read the store.
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark In the following example the store password is <literal>changeit</literal>.
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark$ <userinput>dsconfig \
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark set-trust-manager-provider-prop \
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark --port 4444 \
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark --bindDN "cn=Directory Manager" \
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark --bindPassword password \
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark --provider-name PKCS12 \
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark --set enabled:true \
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark --set trust-store-pin:changeit \
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark --no-prompt \
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark --trustAll</userinput>
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark Configure a connection handler to use the PKCS12 trust manager provider.
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark The following example configures the LDAPS connection handler.
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark$ <userinput>dsconfig \
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark set-connection-handler-prop \
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark --port 4444 \
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark --bindDN "cn=Directory Manager" \
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark --bindPassword password \
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark --handler-name "LDAPS Connection Handler" \
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark --set trust-manager-provider:PKCS12 \
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark --no-prompt \
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark --trustAll</userinput>
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark Verify SSL mutual authentication to check your work.
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark The following example assumes the client certificate for My App
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark is present in the PKCS #12 store,
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark and that the certificate has been added to the entry for My App
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark$ <userinput>ldapsearch \
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark --port 1636 \
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark --baseDN dc=example,dc=com \
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark --useSSL \
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark --useSASLExternal \
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark --certNickName myapp-cert \
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark --keyStorePath keystore \
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark --keyStorePassword changeit \
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark --trustStorePasswordFile /path/to/opendj/config/keystore.pin \
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark "(cn=My App)" userPassword</userinput>
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark<computeroutput>dn: cn=My App,ou=Apps,dc=example,dc=com
03a36f717f3d2ff1c4e80f593862b364b21a2e72markuserPassword: {SSHA}9jjvsv9wlTW7Ikflzc2/wMNBjAN6G4CbbTKYIw==</computeroutput>
03a36f717f3d2ff1c4e80f593862b364b21a2e72mark </procedure>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <variablelist>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>OpenDJ uses certificate mappers during binds to establish a mapping
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark between a client certificate and the entry that corresponds to that
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark certificate. The certificate mappers provided out of the box include the
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark following.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <varlistentry>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Looks for the MD5 (default) or SHA1 certificate fingerprint in an
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark attribute of the entry (default:
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </varlistentry>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <varlistentry>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <term>Subject Attribute To User Attribute Mapper</term>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Looks for a match between an attribute of the certificate subject
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark and an attribute of the entry (default: match <literal>cn</literal> in
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark the certificate to <literal>cn</literal> on the entry, or match
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </varlistentry>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <varlistentry>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <term>Subject DN to User Attribute Certificate Mapper</term>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Looks for the certificate subject DN in an attribute of the entry
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark (default: <literal>ds-certificate-subject-dn</literal>).</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </varlistentry>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <varlistentry>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Looks for an entry whose DN matches the certificate subject DN.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </varlistentry>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </variablelist>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>If the default configurations for the certificate mappers are
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark acceptable, you do not need to change them. They are enabled by
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark default.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>The following steps demonstrate how to change the Fingerprint Mapper
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark default algorithm of MD5 to SHA1.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>List the certificate mappers to retrieve the correct name.</para>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>dsconfig \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark list-certificate-mappers \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --port 4444 \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindDN "cn=Directory Manager" \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindPassword password</userinput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark<computeroutput>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkCertificate Mapper : Type : enabled
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark------------------------------------:-------------------------------------:--------
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkFingerprint Mapper : fingerprint : true
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkSubject Attribute to User Attribute : subject-attribute-to-user-attribute : true
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkSubject DN to User Attribute : subject-dn-to-user-attribute : true
08248b5c5b494aff8d1922e8e0b5777796d7450dmarkSubject Equals DN : subject-equals-dn : true
08248b5c5b494aff8d1922e8e0b5777796d7450dmark</computeroutput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>dsconfig \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark get-certificate-mapper-prop \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --port 4444 \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindDN "cn=Directory Manager" \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindPassword password \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --mapper-name "Fingerprint Mapper"</userinput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark<computeroutput>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkProperty : Value(s)
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark----------------------:---------------------------
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkenabled : true
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkfingerprint-algorithm : md5
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkfingerprint-attribute : ds-certificate-fingerprint
08248b5c5b494aff8d1922e8e0b5777796d7450dmarkuser-base-dn : -</computeroutput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>dsconfig \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark set-certificate-mapper-prop \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --port 4444 \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindDN "cn=Directory Manager" \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindPassword password \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --mapper-name "Fingerprint Mapper" \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --set fingerprint-algorithm:sha1 \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --no-prompt</userinput>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Set the External SASL Mechanism Handler to use the appropriate
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark certificate mapper (default: Subject Equals DN).</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Clients applications use the SASL External mechanism during the bind
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark to have OpenDJ set the authorization identifier based on the entry that
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark matches the client certificate.</para>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>dsconfig \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark set-sasl-mechanism-handler-prop \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --port 4444 \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindDN "cn=Directory Manager" \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindPassword password \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --handler-name External \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --set certificate-mapper:"Fingerprint Mapper" \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --no-prompt</userinput>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </procedure>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <example xml:id="auth-with-client-cert"><?dbfo keep-together="auto"?>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Instead of providing a bind DN and password as for simple
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark authentication, use the SASL EXTERNAL authentication mechanism, and provide
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark the certificate. As a test with example data you can try an anonymous search,
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark and then try with certificate-based authentication.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Before you try this example, make sure OpenDJ is set up to accept
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark StartTLS from clients, and that you have set up the client certificate
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark as described above. Next, create a password .pin file for your client key
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark store.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Also, if OpenDJ directory server uses a certificate for StartTLS that
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark was not signed by a well-known CA, import the appropriate certificate into
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark the client key store, which can then double as a trust store. For example,
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark if OpenDJ uses a self-signed certificate, import the server certificate into
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark the key store.</para>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>keytool \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark -alias server-cert \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark -storepass `cat /path/to/opendj/config/keystore.pin`</userinput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>keytool \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark -trustcacerts \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark -alias server-cert \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark -keystore keystore \
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>If OpenDJ directory server uses a CA-signed certificate, but the CA is
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark not well known, import the CA certificate into your keystore.</para>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>keytool \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark -trustcacerts \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark -alias ca-cert \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark -keystore keystore \
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Now that you can try the example, notice that OpenDJ does not return
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark the <literal>userPassword</literal> value for an anonymous search.</para>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>ldapsearch \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --port 1389 \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --baseDN dc=example,dc=com \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --useStartTLS \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --trustStorePath keystore \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --trustStorePasswordFile keystore.pin \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark "(cn=My App)" userPassword</userinput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark<computeroutput>dn: cn=My App,ou=Apps,dc=example,dc=com</computeroutput>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>OpenDJ does let users read the values of their own
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <literal>userPassword</literal> attributes after they bind
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark successfully.</para>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>ldapsearch \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --port 1389 \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --baseDN dc=example,dc=com \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --useStartTLS \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --useSASLExternal \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --certNickName myapp-cert \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --keyStorePath keystore \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --keyStorePasswordFile keystore.pin \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --trustStorePath keystore \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --trustStorePasswordFile keystore.pin \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark "(cn=My App)" userPassword</userinput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark<computeroutput>dn: cn=My App,ou=Apps,dc=example,dc=com
08248b5c5b494aff8d1922e8e0b5777796d7450dmarkuserPassword: {SSHA}vy/vTthOQoV/wH3MciTOBKKR4OX+0dSN/a09Ew==</computeroutput>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>You can also try the same test with other certificate mappers.</para>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark# Fingerprint mapper
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>dsconfig \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark set-sasl-mechanism-handler-prop \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --port 4444 \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindDN "cn=Directory Manager" \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindPassword password \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --handler-name External \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --set certificate-mapper:"Fingerprint Mapper" \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --no-prompt</userinput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>ldapsearch \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --port 1389 \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --baseDN dc=example,dc=com \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --useStartTLS \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --useSASLExternal \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --certNickName myapp-cert \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --keyStorePath keystore \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --keyStorePasswordFile keystore.pin \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --trustStorePath keystore \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --trustStorePasswordFile keystore.pin \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark "(cn=My App)" userPassword</userinput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark<computeroutput>dn: cn=My App,ou=Apps,dc=example,dc=com
08248b5c5b494aff8d1922e8e0b5777796d7450dmarkuserPassword: {SSHA}vy/vTthOQoV/wH3MciTOBKKR4OX+0dSN/a09Ew==</computeroutput>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark# Subject Attribute to User Attribute mapper
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>dsconfig \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark set-sasl-mechanism-handler-prop \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --port 4444 \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindDN "cn=Directory Manager" \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindPassword password \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --handler-name External \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --set certificate-mapper:"Subject Attribute to User Attribute" \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --no-prompt</userinput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>ldapsearch \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --port 1389 \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --baseDN dc=example,dc=com \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --useStartTLS \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --useSASLExternal \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --certNickName myapp-cert \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --keyStorePath keystore \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --keyStorePasswordFile keystore.pin \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --trustStorePath keystore \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --trustStorePasswordFile keystore.pin \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark "(cn=My App)" userPassword</userinput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark<computeroutput>dn: cn=My App,ou=Apps,dc=example,dc=com
08248b5c5b494aff8d1922e8e0b5777796d7450dmarkuserPassword: {SSHA}vy/vTthOQoV/wH3MciTOBKKR4OX+0dSN/a09Ew==</computeroutput>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark# Subject DN to User Attribute mapper
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>dsconfig \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark set-sasl-mechanism-handler-prop \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --port 4444 \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindDN "cn=Directory Manager" \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindPassword password \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --handler-name External \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --set certificate-mapper:"Subject DN to User Attribute" \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --no-prompt</userinput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>ldapsearch \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --port 1389 \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --baseDN dc=example,dc=com \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --useStartTLS \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --useSASLExternal \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --certNickName myapp-cert \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --keyStorePath keystore \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --keyStorePasswordFile keystore.pin \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --trustStorePath keystore \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --trustStorePasswordFile keystore.pin \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark "(cn=My App)" userPassword</userinput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark<computeroutput>dn: cn=My App,ou=Apps,dc=example,dc=com
08248b5c5b494aff8d1922e8e0b5777796d7450dmarkuserPassword: {SSHA}vy/vTthOQoV/wH3MciTOBKKR4OX+0dSN/a09Ew==</computeroutput>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </example>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </section>