Add Spring LDAP Samples

servlet/xml/java/user-admin/README.adoc

@@ -0,0 +1,57 @@
+== User Admin Sample
+
+Sample application demonstrating how to do some real work with Spring LDAP. This is a fully functional LDAP user
+administration application. It uses many of the useful concepts in Spring LDAP and would serve as a
+good example for best practices and various useful tricks.
+
+=== Users and Groups in LDAP
+
+Users in LDAP are usually represented as `organizationalPerson` or `inetOrgPerson` entries in the LDAP tree.
+The attributes in these entries represent the basic information on the users, e.g. (subset of available attributes):
+
+* `cn`: Common Name, or full name of the user
+* `sn`: Surname
+* `mail`: Email address
+* `telephoneNumber`: Phone number
+* ...several more attributes are available
+
+Groups in LDAP are typically organized in `groupOfName` or `groupOfUniqueName` entries. These entries have a name,
+an optional description, and an attribute containing the distinguished names (i.e. the unique identifiers) of all
+members of the group. This attribute is named `member` and `uniqueMember` respectively.
+
+Thus, user administration in LDAP typically involves creating and manipulating `orgalizationalPerson` or `inetOrgPerson`
+entries and adding or removing references to these entries in `groupOfName` or `groupOfUniqueName` entries.
+
+This application demonstrates to do this easily and efficiently using Spring LDAP.
+
+=== Application Structure
+
+The core Spring application context of the sample is defined in resources/applicationContext.xml.
+By default this ApplicationContext will start an in-process Apache Directory Server instance, automatically populated
+with some test data. The data will be reset every time the application is restarted.
+
+=== Running the Example
+
+To run the example, do `gradle jettyRun`, or `mvn jetty:run`, and then navigate to `http://localhost:8080/spring-ldap-user-admin-sample`
+
+It is also possible to run this sample application against a remote LDAP server as opposed to starting an in-process
+LDAP server. To do this, use the following system properties:
+
+* `spring.profiles.active` - set this to `no-apacheds` to prevent the in-process ApacheDs to be launched
+* `sample.ldap.url` - the URL of the target LDAP server
+* `sample.ldap.userDn` - principal to use for authentication against the LDAP server
+* `sample.ldap.password` - authentication password
+* `sample.ldap.base` - the directory root to use - note that by default all data under this node will be deleted and replaced with test data
+* `sample.ldap.clean` - set this property to false to *not* clear the root node
+* `sample.ldap.directory.type` - NORMAL or AD. Specify AD if running against Active Directory in order to enable some particular AD tweaks
+
+Example:
+
+[source,bash,role="primary"]
+----
+gradle jettyRun -Dspring.profiles.active=no-apacheds -Dsample.ldap.url=ldaps://127.0.0.1:636 \
+ -Dsample.ldap.userDn=CN=ldaptest,CN=Users,DC=261consulting,DC=local -Dsample.ldap.password=secret \
+ -Dsample.ldap.base=ou=test,dc=261consulting,dc=local -Dsample.ldap.directory.type=AD
+----
+
+This sample uses Bootstrap to present a decent web design - copyright 2013 Twitter, Inc; distributed under the Apache 2 License.