From 3973c56df8318ad9bdc577c06d4c00d7ac81f15e Mon Sep 17 00:00:00 2001
From: jensp <jensp@8810af33-2d31-482b-a856-94f89814c4df>
Date: Wed, 16 Oct 2019 18:38:00 +0000
Subject: [PATCH] JavaDoc for JndiLoginModule

git-svn-id: https://svn.libreccm.org/ccm/trunk@6269 8810af33-2d31-482b-a856-94f89814c4df
---
 .../kernel/security/JndiLoginModule.java      | 39 ++++++++++++++++++-
 1 file changed, 37 insertions(+), 2 deletions(-)

diff --git a/ccm-core/src/com/arsdigita/kernel/security/JndiLoginModule.java b/ccm-core/src/com/arsdigita/kernel/security/JndiLoginModule.java
index 9587726bd..8cf9b92be 100644
--- a/ccm-core/src/com/arsdigita/kernel/security/JndiLoginModule.java
+++ b/ccm-core/src/com/arsdigita/kernel/security/JndiLoginModule.java
@@ -9,7 +9,6 @@ import org.apache.log4j.Logger;
 
 import java.net.URI;
 import java.net.URISyntaxException;
-import java.text.MessageFormat;
 import java.util.Hashtable;
 import java.util.Map;
 
@@ -36,6 +35,42 @@ import com.arsdigita.kernel.UserAuthentication;
 import java.math.BigDecimal;
 
 /**
+ * A simple login module for LDAP.
+ *
+ * Currently not tested with LDAPS schema.
+ *
+ * The module uses the SSO login name for finding the user in the LDAP 
+ * repository. If no user with the an SSO name matching the provided user name
+ * is found the methods of the login module will return false which means that
+ * the module should be ignored.
+ * 
+ * To use the module has to be added to the list of {@code LoginModule}s in the
+ * {@link SecurityConfig}. An example configuration (line breaks for easier
+ * reading, remove them for the properties file):
+ *
+ * <pre>
+ * waf.login_config=Request:com.arsdigita.kernel.security.AdminLoginModule:sufficient,
+ * Request:com.arsdigita.kernel.security.RecoveryLoginModule:sufficient,
+ * Request:com.arsdigita.kernel.security.CookieLoginModule:requisite,
+ * Register:com.arsdigita.kernel.security.JndiLoginModule:sufficient,
+ * Register:com.arsdigita.kernel.security.LocalLoginModule:requisite,
+ * Register:com.arsdigita.kernel.security.UserIDLoginModule:requisite,
+ * Register:com.arsdigita.kernel.security.CookieLoginModule:optional
+ * </pre>
+ *
+ * Additionally three more settings have to be configured in the the security
+ * configuration:
+ *
+ * <pre>
+ * waf.ldap.connectionUrl=ldap://jp-fedora-server
+ * waf.ldap.userBase=ou=users,dc=example,dc=org
+ * waf.ldap.userSearch=(mail=%s)
+ * </pre>
+ *
+ * The {@code connectionUrl} is the URL of the LDAP server to use.
+ * {@code userBase} is the tree part in which the users are stored. 
+ * {@code userSearch} defines an LDAP filter for searching the user. 
+ * {@link String#format} is used to fill in the username.
  *
  * @author <a href="mailto:jens.pelzetter@googlemail.com">Jens Pelzetter</a>
  */
@@ -116,7 +151,7 @@ public class JndiLoginModule extends PasswordLoginModule implements LoginModule
         final String connectionUrl = securityConfig.getLdapConnectionUrl();
         final String userBase = securityConfig.getLdapUserBase();
         final String userSearch = securityConfig.getLdapUserSearch();
-        
+
         final Hashtable<String, Object> env = new Hashtable<>();
         env.put(Context.INITIAL_CONTEXT_FACTORY,
                 "com.sun.jndi.ldap.LdapCtxFactory");