From 386a4c554d8485d8b5e077e0c6745db4857b00ad Mon Sep 17 00:00:00 2001 From: Mark Craig <mark.craig@forgerock.com> Date: Thu, 19 Apr 2012 16:02:17 +0000 Subject: [PATCH] Partial first draft --- opendj3/src/main/docbkx/dev-guide/chap-best-practices.xml | 85 ++++++++++++++++++++++++++++++++++++------ 1 files changed, 72 insertions(+), 13 deletions(-) diff --git a/opendj3/src/main/docbkx/dev-guide/chap-best-practices.xml b/opendj3/src/main/docbkx/dev-guide/chap-best-practices.xml index 33f1e58..441784c 100644 --- a/opendj3/src/main/docbkx/dev-guide/chap-best-practices.xml +++ b/opendj3/src/main/docbkx/dev-guide/chap-best-practices.xml @@ -36,31 +36,90 @@ <section xml:id="authenticate-correctly"> <title>Authenticate Correctly</title> - <para>TODO</para> + + <para>Unless your application performs only read operations, you should + authenticate to the directory server. Some directory administrators require + authentication even to read directory data.</para> + + <para>Once you authenticate (bind), directory servers like OpenDJ make + authorization decisions based on your identity. With servers like OpenDJ + that support proxied authorization, once authenticated your application can + also request an operation on behalf of another identity, for example the + identity of the end user.</para> + + <para>Your application therefore should have an account used to authenticate + such as <literal>cn=My Killer App,ou=Apps,dc=example,dc=com</literal>. The + directory administrator can then authorize appropriate access for your + application, and also monitor your application's requests to help you + troubleshoot problems if they arise.</para> + + <para>Your application can use simple, password-based authentication. When + you opt for password-based authentication, also use Start TLS for example to + avoid sending the password as clear text over the network. If you prefer to + manage certificates rather than passwords, directory servers like OpenDJ can + do client authentication as well.</para> </section> - <section xml:id="limit-connection-overhead"> - <title>Limit Connection Overhead</title> - <para>TODO</para> + <section xml:id="reuse-connections"> + <title>Reuse Connections</title> + + <para>LDAP is a stateful protocol. You authenticate (bind), you do stuff, + you unbind. The server maintains a context that lets it make authorization + decisions concerning your requests. You should therefore reuse + connections when possible.</para> + + <para>You can make multiple requests without having to set up a new + connection and authenticate for every request. You can issue a request and + get results asynchronously, while you issue another request. You can even + share connections in a pool, avoiding the overhead of setting up and tearing + down connections if you use them often.</para> </section> - <section xml:id="handle-inactivity-timeouts"> - <title>Handle Potential Inactivity Timeouts</title> - <para>TODO</para> + <section xml:id="health-check-connections"> + <title>Health Check Connections</title> + + <para>In a network built for HTTP applications, your long-lived LDAP + connections can get cut by network equipment configured to treat idle and + even just old connections as stale resources to reclaim.</para> + + <para>When you maintain a particularly long-lived connection such as a + connection for a persistent search, periodically perform a health check to + make sure nothing on the network quietly decided to drop your connection + without notification. A health check might involve reading an attribute + on a well-known entry in the directory.</para> </section> - <section xml:id="retrieve-entries-intelligently"> - <title>Retrieve Entries Intelligently</title> - <para>TODO</para> + <section xml:id="request-what-you-need-all-at-once"> + <title>Request Exactly What You Need All At Once</title> + + <para>By the time your application makes it to production, you should know + what attributes you want, so request them explicitly and request all + the attributes you need in the same search. For example, if all you need + is <literal>mail</literal> and <literal>cn</literal>, then specify both + attributes in your <literal>SearchRequest</literal>.</para> </section> - <section xml:id="write-simple-conforming-filters"> - <title>Write Simple, Conforming LDAP Filters</title> - <para>TODO</para> + <section xml:id="use-specific-filters"> + <title>Use Specific LDAP Filters</title> + + <para>The difference between a general filter + <literal>(mail=*@example.com)</literal> and a good, specific filter like + <literal>(mail=user@example.com)</literal> can be huge numbers of entries + and enormous amounts of processing time, both for the directory server + that has to return search results, and also for your application that has + to sort through the results. Many use cases can be handled with short, + specific filters. As a rule, prefer equality filters over substring + filters.</para> + + <para>Furthermore, always use <literal>&</literal> with + <literal>!</literal> to restrict the potential result set before returning + all entries that do not match part of the filter. For example, <literal + >(&(location=Oslo)(!(mail=birthday.girl@example.com)))</literal>.</para> </section> <section xml:id="make-modifications-specific"> <title>Make Modifications Specific</title> + <para>TODO</para> </section> -- Gitblit v1.10.0