chap-ldap-operations.xml revision 51607ea01068c9047391e4c8b46bc9dbd0edb7fd
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
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark ! Copyright 2011-2013 ForgeRock AS
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark xmlns='http://docbook.org/ns/docbook' version='5.0' xml:lang='en'
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd'
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>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>The <command>ldapsearch</command> command thus takes at minimum a
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark search base DN option and an LDAP filter. The search base DN identifies
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark where in the directory to search for entries that match the filter.
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark For example, if you are looking for printers, you might specify the base
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark DN as <literal>ou=Printers,dc=example,dc=com</literal>. Perhaps you are
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark visiting the <literal>GNB00</literal> office and are looking for a
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark printer.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <screen>$ ldapsearch --baseDN ou=Printers,dc=example,dc=com "(printerLocation=GNB00)"</screen>
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>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <screen>$ ldapsearch --port 1389 --baseDN dc=example,dc=com "(uid=*jensen*)" uid
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkdn: 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
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkResult Code: 0 (Success)</screen>
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>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <screen>$ ldapsearch
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --port 1389
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --baseDN ou=people,dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "(&(uid=*jensen*)(l=Santa Clara))"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkdn: 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
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>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <screen>$ ldapsearch --port 1389 --baseDN dc=example,dc=com uid=bjensen +
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkdn: 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
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkentryUUID: fc252fd9-b982-3ed6-b42a-c76d2546312c</screen>
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>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <screen>$ ldapsearch --port 1389 --baseDN dc=example,dc=com uid=bjensen @person
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkdn: 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
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarksn: Jensen</screen>
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>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <screen>$ ldapsearch --port 1389 --baseDN dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "(description=\28*\5c*\2a\29)" description
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkdn: uid=bjensen,ou=People,dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkdescription: (A \great\ description*)</screen>
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
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark 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>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <screen>$ ldapmodify
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --port 1389
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --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
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark X-ORIGIN 'OpenDJ example documentation' )
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkProcessing MODIFY request for cn=schema
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkMODIFY operation successful for DN cn=schema
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>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <screen>$ dsconfig
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark set-password-policy-prop
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --port 4444
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindDN "cn=Directory Manager"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindPassword password
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --policy-name "Default Password Policy"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --set last-login-time-attribute:lastLoginTime
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --set last-login-time-format:"yyyyMMddHH'Z'"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --trustAll
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --no-prompt</screen>
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>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <screen>$ ldapsearch
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --port 1389
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --baseDN dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "(lastLoginTime:1.3.6.1.4.1.26027.1.4.6:=13w)" mail
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkdn: uid=bjensen,ou=People,dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkmail: bjensen@example.com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkdn: uid=kvaughan,ou=People,dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkmail: kvaughan@example.com</screen>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </example>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <example xml:id="localized-search"><?dbfo keep-together="auto"?>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>OpenDJ directory server supports many language subtypes. See the
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark chapter on <link xlink:href="admin-guide#appendix-l10n"
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>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <screen>$ ldapsearch
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --port 1389
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --baseDN dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "(givenName:fr:=Fréderique)" cn\;lang-fr
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkdn: uid=fdupont,ou=People,dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkcn;lang-fr:: RnJlZMOpcmlxdWUgRHVwb250
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark$ base64 decode -d RnJlZMOpcmlxdWUgRHVwb250
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkFredérique Dupont</screen>
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>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>In this example, Kirsten Vaughan checks whether the hashed password
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark value matches the stored value on <literal>authPassword</literal>.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --port 1389
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindDN "uid=kvaughan,ou=people,dc=example,dc=com"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindPassword bribery
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark 'authPassword:MD5$dFHgpDxXUT8=$qlC4xMXvmVlusJLz9/WJ5Q=='
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark uid=kvaughan,ou=people,dc=example,dc=com</userinput>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkComparing type authPassword with value
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark uid=kvaughan,ou=people,dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkCompare operation returned true for entry
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark uid=kvaughan,ou=people,dc=example,dc=com</screen>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </example>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </section>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <indexterm><primary>Updating data</primary></indexterm>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <indexterm><primary>LDIF</primary><secondary>Examples</secondary></indexterm>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Authorized users can change directory data using the LDAP add, modify,
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark modify DN, and delete operations.</para>
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>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkdn: 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
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarksn: Velmont
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark$ ldapmodify
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --defaultAdd
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --port 1389
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindDN "uid=kvaughan,ou=people,dc=example,dc=com"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindPassword bribery
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkProcessing 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
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark cn=Horace Velmont,ou=Special Users,dc=example,dc=com</screen>
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>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkdn: uid=scarter,ou=people,dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkchangetype: modify
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkadd: description
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkdescription: Accounting Manager
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkadd: jpegphoto
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark$ ldapmodify
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --port 1389
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindDN "uid=kvaughan,ou=people,dc=example,dc=com"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindPassword bribery
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkProcessing MODIFY request for uid=scarter,ou=people,dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkMODIFY operation successful for DN uid=scarter,ou=people,dc=example,dc=com</screen>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </example>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>The following example replaces the description on Sam Carter's
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark entry.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkdn: uid=scarter,ou=people,dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkchangetype: modify
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkreplace: description
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkdescription: Accounting Director
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark$ ldapmodify
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --port 1389
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindDN "uid=kvaughan,ou=people,dc=example,dc=com"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindPassword bribery
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkProcessing MODIFY request for uid=scarter,ou=people,dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkMODIFY operation successful for DN uid=scarter,ou=people,dc=example,dc=com</screen>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </example>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>The following example deletes the JPEG photo on Sam Carter's
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark entry.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkdn: uid=scarter,ou=people,dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkchangetype: modify
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkdelete: jpegphoto
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark$ ldapmodify
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --port 1389
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindDN "uid=kvaughan,ou=people,dc=example,dc=com"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindPassword bribery
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkProcessing MODIFY request for uid=scarter,ou=people,dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkMODIFY operation successful for DN uid=scarter,ou=people,dc=example,dc=com</screen>
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
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark xlink:href="admin-guide#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>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkdn: uid=bjensen,ou=People,dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkchangetype: modify
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkl: Grenoble
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkadd: description
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkdescription: Employee of the Month
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark$ ldapmodify
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindDN "cn=Directory Manager"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindPassword password
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --port 1389
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --assertionFilter "(ETag=000000007a1999df)"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkProcessing 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
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark and the associated filter did not match the contents of the that entry</screen>
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>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <screen>$ dsconfig
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark create-plugin
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --port 4444
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindDN "cn=Directory Manager"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindPassword password
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --type attribute-cleanup
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --plugin-name "Rename email to mail"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --set enabled:true
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --set rename-inbound-attributes:email:mail
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --trustAll
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --no-prompt</screen>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkdn: 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
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkuserPassword: changeme
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark$ ldapmodify
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --port 1389
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindDN "cn=Directory Manager"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindPassword password
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --defaultAdd
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkProcessing ADD request for uid=newuser,ou=People,dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkADD operation successful for DN uid=newuser,ou=People,dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark$ ldapsearch --port 1389 --baseDN dc=example,dc=com uid=newuser mail
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkdn: uid=newuser,ou=People,dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkmail: newuser@example.com</screen>
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>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <screen>$ dsconfig
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark create-plugin
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --port 4444
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindDN "cn=Directory Manager"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindPassword password
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --type attribute-cleanup
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --plugin-name "Remove attrs"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --set enabled:true
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --set remove-inbound-attributes:creatorsName
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --set remove-inbound-attributes:createTimestamp
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --set remove-inbound-attributes:modifiersName
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --set remove-inbound-attributes:modifyTimestamp
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --trustAll
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --no-prompt</screen>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkdn: 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
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkmodifyTimestamp: 20110930164937Z
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark$ ldapmodify
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --port 1389
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindDN "cn=Directory Manager"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindPassword password
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --defaultAdd
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkProcessing ADD request for uid=badattr,ou=People,dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkADD operation successful for DN uid=badattr,ou=People,dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark$ ldapsearch --port 1389 --baseDN dc=example,dc=com uid=badattr +
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkdn: 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
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkcreateTimestamp: 20110930165959Z</screen>
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>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkdn: 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
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkmail: sjensen@example.com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark$ ldapmodify
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --port 1389
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindDN "uid=kvaughan,ou=people,dc=example,dc=com"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindPassword bribery
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkProcessing 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
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkMODIFY operation successful for DN uid=sjensen,ou=people,dc=example,dc=com</screen>
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>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkdn: ou=Customers,dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkchangetype: modrdn
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarknewrdn: ou=People
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkdeleteoldrdn: 1
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarknewsuperior: dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark$ ldapmodify
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --port 1389
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindDN "cn=Directory Manager"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindPassword password
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkProcessing MODIFY DN request for ou=Customers,dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkMODIFY DN operation successful for DN ou=Customers,dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark# For each employee, construct a spec to move under ou=People.
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkwhile (<>)
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/;
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark$ ldapsearch --port 1389 --baseDN ou=Employees,dc=example,dc=com uid=* - |
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkdn: uid=abarnes,ou=Employees,dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkchangetype: moddn
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarknewrdn: uid=abarnes
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkdeleteoldrdn: 0
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarknewsuperior: ou=People,dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark$ ldapmodify
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --port 1389
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindDN "cn=Directory Manager"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindPassword password
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkProcessing 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
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkMODIFY DN operation successful for DN uid=wlutz,ou=Employees,dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark$ ldapdelete
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --port 1389
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindDN "cn=Directory Manager"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindPassword password
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark ou=Employees,dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkProcessing DELETE request for ou=Employees,dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkDELETE operation successful for DN ou=Employees,dc=example,dc=com</screen>
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>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <screen>$ ldapdelete
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --port 1389
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindDN "cn=Directory Manager"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindPassword password
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --deleteSubtree "ou=Special Users,dc=example,dc=com"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkProcessing DELETE request for ou=Special Users,dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkDELETE operation successful for DN ou=Special Users,dc=example,dc=com</screen>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </example>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </section>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </section>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <indexterm><primary>Passwords</primary><secondary>Changing</secondary></indexterm>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>With the <command>ldappasswordmodify</command> command, authorized
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark users can change and reset user passwords.</para>
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>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <screen>$ ldappasswordmodify
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --useStartTLS
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --port 1389
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindDN "uid=kvaughan,ou=people,dc=example,dc=com"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindPassword bribery
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --authzID "dn:uid=scarter,ou=people,dc=example,dc=com"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --newPassword ChangeMe
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkThe LDAP password modify operation was successful</screen>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Whenever one user changes another user's password, OpenDJ considers
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark it a password reset. That often means the user has to change her password
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark again after the reset.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>If you want your application to change a user's password, rather
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark than reset a user's password, have your application request the password
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark change as the user whose password is changing. To change the password as
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark the user, either bind as the user or use proxied authorization. For
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark instructions on the latter, see the section on <link
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark xlink:role="http://docbook.org/xlink/role/olink"><citetitle>Configuring
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>You could also accomplish password reset with the following command,
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark but <command>set-password-is-reset</command> is a hidden option, supported
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark only for testing.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <screen>$ manage-account
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark set-password-is-reset
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindDN "cn=Directory Manager"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindPassword password
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --targetDN uid=scarter,ou=people,dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --operationValue true
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkPassword Is Reset: true</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>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <screen>$ ldappasswordmodify
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --port 1389
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --authzID "dn:uid=bjensen,ou=people,dc=example,dc=com"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --currentPassword hifalutin
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --newPassword secret12
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkThe LDAP password modify operation was successful</screen>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>The same operation works for <literal>cn=Directory
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <screen>$ ldappasswordmodify
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --port 1389
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --authzID "dn:cn=Directory Manager"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --currentPassword password
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --newPassword secret12
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkThe LDAP password modify operation was successful</screen>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </example>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>OpenDJ expects passwords to be UTF-8 encoded (base64 encoded when
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark included in LDIF).</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <screen>$ echo $LANG
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark$ ldappasswordmodify
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --port 1389
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindDN uid=bjensen,ou=People,dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindPassword hifalutin
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --currentPassword hifalutin
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --newPassword pàsswȏrd
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkThe LDAP password modify operation was successful
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark$ ldapsearch
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --port 1389
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindDN uid=bjensen,ou=People,dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindPassword pàsswȏrd
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --baseDN dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "(uid=bjensen)" cn
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkdn: uid=bjensen,ou=People,dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkuserPassword: {SSHA}k0eEeCxj9YRXUp8yJn0Z/mwqe+wrcFb1N1gg2g==
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkcn: Barbara Jensen
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkcn: Babs Jensen
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>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <screen>$ ldapsearch
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --port 1389
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --useStartTLS
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --baseDN dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --saslOption mech=PLAIN
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --saslOption authid=u:bjensen
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindPassword hifalutin
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "(cn=Babs Jensen)" cn userPassword
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkdn: uid=bjensen,ou=People,dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkcn: Barbara Jensen
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkcn: Babs Jensen
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkuserPassword: {SSHA}7S4Si+vPE513cYQ7otiqb8hjiCzU7XNTv0RPBA==</screen>
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>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <screen>$ dsconfig
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark create-identity-mapper
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --port 4444
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindDN "cn=Directory Manager"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindPassword password
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --mapper-name "Email Mapper"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --type exact-match
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --set match-attribute:mail
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --set enabled:true
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --no-prompt
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark set-sasl-mechanism-handler-prop
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --port 4444
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindDN "cn=Directory Manager"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindPassword password
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --handler-name PLAIN
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --set identity-mapper:"Email Mapper"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --no-prompt
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark$ ldapsearch
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --port 1389
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --useStartTLS
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --baseDN dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --saslOption mech=PLAIN
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --saslOption authid=u:bjensen@example.com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindPassword hifalutin
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "(cn=Babs Jensen)" cn userPassword
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkdn: uid=bjensen,ou=People,dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkcn: Barbara Jensen
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkcn: Babs Jensen
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkuserPassword: {SSHA}7S4Si+vPE513cYQ7otiqb8hjiCzU7XNTv0RPBA==</screen>
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>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <screen>$ dsconfig
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark set-sasl-mechanism-handler-prop
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --port 4444
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindDN "cn=Directory Manager"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindPassword password
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --handler-name PLAIN
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --set identity-mapper:"Regular Expression"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --no-prompt
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark$ ldapsearch
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --port 1389
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --useStartTLS
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --baseDN dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --saslOption mech=PLAIN
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --saslOption authid=u:bjensen@example.com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindPassword hifalutin
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "(cn=Babs Jensen)" cn userPassword
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkdn: uid=bjensen,ou=People,dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkcn: Barbara Jensen
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkcn: Babs Jensen
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkuserPassword: {SSHA}7S4Si+vPE513cYQ7otiqb8hjiCzU7XNTv0RPBA==</screen>
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>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <screen>$ ldapmodify
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --port 1389
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --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
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark )(userdn = "ldap:///cn=*,ou=Apps,dc=example,dc=com");)
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkProcessing MODIFY request for dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkMODIFY operation successful for DN dc=example,dc=com</screen>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Grant the privilege to use proxied authorization to My App.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <screen>$ ldapmodify
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --port 1389
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindDN "cn=Directory Manager"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindPassword password
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkdn: cn=My App,ou=Apps,dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkchangetype: modify
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkadd: ds-privilege-name
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkds-privilege-name: proxied-auth
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkProcessing MODIFY request for cn=My App,ou=Apps,dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkMODIFY operation successful for DN cn=My App,ou=Apps,dc=example,dc=com</screen>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Test that My App can use proxied authorization.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <screen>$ ldapmodify
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --port 1389
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindDN "cn=My App,ou=Apps,dc=example,dc=com"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --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
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkdescription: Changed through proxied auth
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkProcessing MODIFY request for uid=bjensen,ou=People,dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkMODIFY operation successful for DN uid=bjensen,ou=People,dc=example,dc=com</screen>
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>
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>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <screen>$ keytool
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark -alias myapp-cert
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark -keyalg rsa
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark -dname "cn=My App,ou=Apps,dc=example,dc=com"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark -keystore keystore
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark -storepass changeit
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark -keypass changeit</screen>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>If you cannot get the certificate signed by a Certificate Authority,
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark self-sign the certificate.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <screen>$ keytool
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark -alias myapp-cert
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark -validity 7300
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark -keystore keystore
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark -storepass changeit
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark -keypass changeit</screen>
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>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <screen>$ keytool
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark -alias myapp-cert
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark -keystore keystore
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark -storepass changeit
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkAlias 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:
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark MD5: 48:AC:F9:13:11:E0:AB:C4:65:A2:83:9E:DB:FE:0C:37
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark SHA1: F9:61:54:37:AA:C1:BC:92:45:07:64:4B:23:6C:BC:C9:CD:1D:44:0F
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark SHA256: 2D:B1:58:CD:33:40:E9:...:FD:61:EA:C9:FF:6A:19:93:FE:E4:84:E3
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark Signature algorithm name: SHA256withRSA
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark 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.
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Export the certificate to a file in binary format.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <screen>$ keytool
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark -alias myapp-cert
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark -keystore keystore
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark -storepass changeit
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark -keypass changeit
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkCertificate stored in file </path/to/myapp-cert.crt></screen>
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>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkdn: 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
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkuserCertificate;binary:<file:///path/to/myapp-cert.crt
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark$ ldapmodify
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --port 1389
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindDN "cn=Directory Manager"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindPassword password
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkProcessing MODIFY request for cn=My App,ou=Apps,dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkMODIFY operation successful for DN cn=My App,ou=Apps,dc=example,dc=com</screen>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <screen>$ ldapsearch
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --port 1389
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --baseDN dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "(cn=My App)"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkdn: 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
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarksn: App</screen>
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>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <screen>$ keytool
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark -alias myapp-cert
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:
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark MD5: 48:AC:F9:13:11:E0:AB:C4:65:A2:83:9E:DB:FE:0C:37
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark SHA1: F9:61:54:37:AA:C1:BC:92:45:07:64:4B:23:6C:BC:C9:CD:1D:44:0F
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark SHA256: 2D:B1:58:CD:33:40:E9:...:FD:61:EA:C9:FF:6A:19:93:FE:E4:84:E3
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark Signature algorithm name: SHA256withRSA
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark 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.
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkTrust this certificate? [no]: yes
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkCertificate was added to keystore</screen>
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>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <screen>$ keytool
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark -storepass changeit</screen></footnote>, import the CA certificate either
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark into the Java runtime environment trust store, or into the OpenDJ trust
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark store as shown in the following example.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <screen>$ keytool
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark -alias ca-cert
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkOwner: 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:
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark MD5: 8A:83:61:9B:E7:18:A2:21:CE:92:94:96:59:68:60:FA
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark SHA1: 01:99:18:38:3A:57:D7:92:7B:D6:03:8C:7B:E4:1D:37:45:0E:29:DA
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark SHA256: 5D:20:F1:86:CC:CD:64:50:1E:54:...:DF:15:43:07:69:44:00:FB:36:CF
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark Signature algorithm name: SHA1withRSA
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark 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.
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkTrust this certificate? [no]: yes
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkCertificate was added to keystore</screen>
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>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <screen>$ stop-ds --restart
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkStopping Server...
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark... The Directory Server has started successfully</screen>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </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>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark list-certificate-mappers
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --port 4444
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindDN "cn=Directory Manager"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindPassword password
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
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkSubject Equals DN : subject-equals-dn : true</screen>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <screen>$ dsconfig
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark get-certificate-mapper-prop
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --port 4444
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindDN "cn=Directory Manager"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindPassword password
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --mapper-name "Fingerprint Mapper"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkProperty : Value(s)
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark----------------------:---------------------------
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkenabled : true
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkfingerprint-algorithm : md5
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkfingerprint-attribute : ds-certificate-fingerprint
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkuser-base-dn : -</screen>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <screen>$ dsconfig
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark set-certificate-mapper-prop
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --port 4444
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindDN "cn=Directory Manager"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindPassword password
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --mapper-name "Fingerprint Mapper"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --set fingerprint-algorithm:sha1
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --no-prompt</screen>
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>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <screen>$ dsconfig
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark set-sasl-mechanism-handler-prop
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --port 4444
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindDN "cn=Directory Manager"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindPassword password
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --handler-name External
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --set certificate-mapper:"Fingerprint Mapper"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --no-prompt</screen>
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>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <screen>$ keytool
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark -alias server-cert
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark -trustcacerts
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark -alias server-cert
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark -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>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <screen>$ keytool
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark -trustcacerts
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark -alias ca-cert
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark -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>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <screen>$ ldapsearch
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --port 1389
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --baseDN dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --useStartTLS
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --trustStorePath keystore
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --trustStorePasswordFile keystore.pin
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "(cn=My App)" userPassword
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkdn: cn=My App,ou=Apps,dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>OpenDJ does let users read the values of their own
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <literal>userPassword</literal> attributes after they bind
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark successfully.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <screen>$ ldapsearch
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --port 1389
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --baseDN dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --useStartTLS
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --useSASLExternal
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --certNickName myapp-cert
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --keyStorePath keystore
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --keyStorePasswordFile keystore.pin
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --trustStorePath keystore
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --trustStorePasswordFile keystore.pin
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "(cn=My App)" userPassword
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkdn: cn=My App,ou=Apps,dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkuserPassword: {SSHA}vy/vTthOQoV/wH3MciTOBKKR4OX+0dSN/a09Ew==</screen>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>You can also try the same test with other certificate mappers.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <screen># Fingerprint mapper
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark set-sasl-mechanism-handler-prop
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --port 4444
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindDN "cn=Directory Manager"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindPassword password
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --handler-name External
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --set certificate-mapper:"Fingerprint Mapper"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --no-prompt
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark$ ldapsearch
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --port 1389
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --baseDN dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --useStartTLS
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --useSASLExternal
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --certNickName myapp-cert
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --keyStorePath keystore
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --keyStorePasswordFile keystore.pin
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --trustStorePath keystore
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --trustStorePasswordFile keystore.pin
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "(cn=My App)" userPassword
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkdn: cn=My App,ou=Apps,dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkuserPassword: {SSHA}vy/vTthOQoV/wH3MciTOBKKR4OX+0dSN/a09Ew==
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark# Subject Attribute to User Attribute mapper
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark set-sasl-mechanism-handler-prop
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --port 4444
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindDN "cn=Directory Manager"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindPassword password
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --handler-name External
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --set certificate-mapper:"Subject Attribute to User Attribute"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --no-prompt
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark$ ldapsearch
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --port 1389
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --baseDN dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --useStartTLS
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --useSASLExternal
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --certNickName myapp-cert
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --keyStorePath keystore
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --keyStorePasswordFile keystore.pin
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --trustStorePath keystore
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --trustStorePasswordFile keystore.pin
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "(cn=My App)" userPassword
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkdn: cn=My App,ou=Apps,dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkuserPassword: {SSHA}vy/vTthOQoV/wH3MciTOBKKR4OX+0dSN/a09Ew==
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark# Subject DN to User Attribute mapper
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark set-sasl-mechanism-handler-prop
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --port 4444
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindDN "cn=Directory Manager"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindPassword password
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --handler-name External
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --set certificate-mapper:"Subject DN to User Attribute"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --no-prompt
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark$ ldapsearch
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --port 1389
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --baseDN dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --useStartTLS
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --useSASLExternal
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --certNickName myapp-cert
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --keyStorePath keystore
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --keyStorePasswordFile keystore.pin
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --trustStorePath keystore
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --trustStorePasswordFile keystore.pin
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "(cn=My App)" userPassword
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkdn: cn=My App,ou=Apps,dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkuserPassword: {SSHA}vy/vTthOQoV/wH3MciTOBKKR4OX+0dSN/a09Ew==</screen>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </example>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </section>