chap-attribute-uniqueness.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-2012 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>Some attribute values ought to remain unique. If you are using
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <literal>uid</literal> values as RDNs to distinguish between millions of
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark user entries stored under <literal>ou=People</literal>, then you do not
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark want your directory to contain two or more identical
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <literal>uid</literal> values. If your credit card or mobile number is
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark stored as an attribute value on your directory entry, you certainly do not
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark want to share that credit card or mobile number with another customer.
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark The same is true for your email address.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <indexterm><primary>Unique attribute values</primary></indexterm>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>The difficulty for you as directory administrator lies in
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark implementing attribute value uniqueness without sacrificing the high
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark availability that comes from using OpenDJ's loosely consistent,
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark multi-master data replication. Indeed OpenDJ's replication model lets
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark you maintain write access during network outages for directory
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark applications. Yet, write access during a network outage can result in the
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark same, theoretically unique attribute value getting assigned to two different
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark entries at once. You do not notice the problem until the network outage
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark goes away and replication resumes.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>This chapter shows you how to set up attribute value uniqueness
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark in your directory environment.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>OpenDJ provides a unique attribute plugin that you configure by using
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark the <command>dsconfig</command> command. By default, the plugin is prepared
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark to ensure attribute values are unique for <literal>uid</literal>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark attributes.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Set the base DN where <literal>uid</literal> should have unique
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark values, and enable the plugin.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <screen>$ dsconfig
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark set-plugin-prop
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --port 4444
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindDN "cn=Directory Manager"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindPassword password
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --plugin-name "UID Unique Attribute"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --set base-dn:ou=people,dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --set enabled:true
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --trustAll
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --no-prompt</screen>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Alternatively, you can specify multiple base DNs for unique values
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark across multiple suffixes.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <screen>$ dsconfig
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark set-plugin-prop
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --port 4444
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindDn "cn=Directory Manager"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindPassword password
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --plugin-name "UID Unique Attribute"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --set enabled:true
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --add base-dn:ou=people,dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --add base-dn:ou=people,dc=example,dc=org
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --trustAll
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --no-prompt</screen>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Check that the plugin is working correctly.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkdn: uid=ajensen,ou=People,dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkchangetype: modify
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkuid: bjensen
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark$ ldapmodify
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --defaultAdd
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --port 1389
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindDN "cn=Directory Manager"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindPassword password
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkProcessing MODIFY request for uid=ajensen,ou=People,dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkMODIFY operation failed
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkResult Code: 19 (Constraint Violation)
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkAdditional Information: A unique attribute conflict was detected for \
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark attribute uid: value bjensen already exists in entry
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark uid=bjensen,ou=People,dc=example,dc=com</screen>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>If you have set up multiple suffixes, you might try something like
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark this.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkdn: uid=bjensen,ou=People,dc=example,dc=org
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkobjectClass: top
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkobjectClass: person
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkobjectClass: organizationalPerson
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkobjectClass: inetOrgPerson
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkuid: bjensen
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark$ ldapmodify
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --port 1389
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindDN "cn=Directory Manager"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindPassword password
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --defaultAdd
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkProcessing ADD request for uid=bjensen,ou=People,dc=example,dc=org
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkADD operation failed
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkResult Code: 19 (Constraint Violation)
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkAdditional Information: A unique attribute conflict was detected for attribute
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark uid: value bjensen already exists in entry
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark uid=bjensen,ou=People,dc=example,dc=com</screen>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </procedure>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <title>To Enable Unique Values For Other Attributes</title>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>You can also configure the unique attribute plugin for use with
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark other attributes, such as <literal>mail</literal>, <literal>mobile</literal>,
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark or attributes you define, for example <literal>cardNumber</literal>.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Before you set up the plugin, index the attribute for equality.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Set up the plugin configuration for your attribute.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <screen>$ dsconfig
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark create-plugin
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --port 4444
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindDN "cn=Directory Manager"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindPassword password
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --plugin-name "Unique mobile numbers"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --type unique-attribute
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --set enabled:true
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --set base-dn:ou=people,dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --set type:mobile
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --trustAll
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --no-prompt</screen>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Check that the plugin is working correctly.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkdn: uid=ajensen,ou=People,dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkchangetype: modify
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkadd: mobile
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkmobile: +1 828 555 1212
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkdn: uid=bjensen,ou=People,dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkchangetype: modify
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkadd: mobile
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkmobile: +1 828 555 1212
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark$ ldapmodify
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --defaultAdd
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --port 1389
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindDN "cn=Directory Manager"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindPassword password
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkProcessing MODIFY request for uid=ajensen,ou=People,dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkMODIFY operation successful for DN uid=ajensen,ou=People,dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkProcessing MODIFY request for uid=bjensen,ou=People,dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkMODIFY operation failed
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkResult Code: 19 (Constraint Violation)
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkAdditional Information: A unique attribute conflict was detected for
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark attribute mobile: value +1 828 555 1212 already exists in entry
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark uid=ajensen,ou=People,dc=example,dc=com</screen>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </procedure>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <title>To Ensure Unique Attribute Values With Replication</title>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <indexterm>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </indexterm>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>The unique attribute plugin ensures unique attribute values on the
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark directory server where the attribute value is updated. If client applications
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark separately write the same attribute value at the same time on different
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark directory replicas, it is possible that both servers consider the duplicate
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark value unique, especially if the network is down between the replicas.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Enable the plugin identically on all replicas.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>To avoid duplicate values where possible, try one of the following
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark solutions.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <stepalternatives>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Use a load balancer or proxy technology to direct all updates
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark to the unique attribute to the same directory server.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>The drawback here is the need for an additional component to
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark direct the updates to the same server, and to manage failover should that
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark server go down.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Configure safe read mode assured replication between replicas
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark storing the unique attribute.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>The drawbacks here are the cost of safe read assured replication,
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark and the likelihood that assured replication can enter degraded mode during
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark a network outage, thus continuing to allow updates during the
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark outage.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </stepalternatives>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </procedure>