UY-1156 OTP-LDAP documentation

Author: golbi

documentation/pom.xml

@@ -65,6 +65,11 @@
 			<artifactId>unity-server-pam</artifactId>
 			<version>${project.version}</version>
 		</dependency>
+		<dependency>
+			<groupId>io.imunity</groupId>
+			<artifactId>unity-server-otp-ldap</artifactId>
+			<version>${project.version}</version>
+		</dependency>
 		<dependency>
 			<groupId>io.imunity</groupId>
 			<artifactId>unity-server-web-common</artifactId>
@@ -215,6 +220,7 @@
 								<argument>pl.edu.icm.unity.webui.authn.extensions.PasswordRetrievalProperties|ref-PasswordRetrievalProperties.txt|</argument>
 								<argument>pl.edu.icm.unity.webui.authn.extensions.SMSRetrievalProperties|ref-SMSRetrievalProperties.txt|</argument>
 								<argument>pl.edu.icm.unity.webui.authn.extensions.TLSRetrievalProperties|ref-TLSRetrievalProperties.txt|</argument>
+								<argument>io.imunity.otp.ldap.OTPWithLDAPProperties|ref-OTPLDAPProperties.txt|</argument>
 							</arguments>
 						</configuration>
 						<goals>

documentation/src/main/doc/authenticator-otp-ldap.txt

@@ -0,0 +1,49 @@
+[[otp-ldap-authenticator]]
+=== OTP verification with LDAP backend 
+
+Credential verificator name:: +otp-ldap+
+Compatible credentials:: _not used_
+
+The OTP authenticator with LDAP backend allows for configuring OTP verification with secret (and optionally other OTP parameters) stored in LDAP as user's attribute. 
+
+Authenticated user must possess the `username` identity to be authenticated. This identity is mapped to an LDAP entity DN first and then an attribute with OTP secret is retrieved from the entity. 
+
+The configuration of this authenticator consists mostly from LDAP connection options. 
+
+The most important is setting of an LDAP attribute which is storing an OTP URI with user's secret. The URI must be encoded `otpauth://` scheme. See https://github.com/google/google-authenticator/wiki/Key-Uri-Format for details of the URI format. Additional OTP key parameters as time step, hash algorithm and code length are also taken from the URI if are present. If are missing, then the values set in Unity's configuration of the authenticator are used.  
+
+
+[NOTE]
+Technically this authenticator is implemented as _local authenticator_, that is it does not support setting up an input translation profile. This decision was made as in practice OTP is used as a 2nd factor authenticator and if a deployment is using this authenticator, most likely it is accompanied with LDAP password (or certificate) authenticator, which can map and fetch LDAP users with full flexibility of Unity remote authenticator.
+
+
+==== File based configuration 
+
+This section is relevant only if Unity is configured with configuration files, instead of the Admin Console web UI.
+
+Example configuration of LDAP OTP authenticator in unityServer.conf:
+
+----
+unityServer.core.authenticators.otpldap.authenticatorName=OTP LDAP
+unityServer.core.authenticators.otpldap.authenticatorType=otp-ldap
+unityServer.core.authenticators.otpldap.configurationFile=authn/otp-ldap.properties
+----
+
+and the corresponding configuration of the authenticator:
+
+----
+otpldap.servers.1=localhost
+otpldap.ports.1=389
+
+otpldap.userDNTemplate=cn={USERNAME},ou=People,dc=srv,dc=world
+otpldap.systemDN=cn=Manager,dc=srv,dc=world
+otpldap.systemPassword=ldap-test
+
+otpldap.otpSecretURIAttribute=otp-secret
+----
+
+Full reference with all properties:
+
+include::ref-OTPLDAPProperties.txt[]
+
+

documentation/src/main/doc/external-idps.txt

@@ -23,3 +23,5 @@ include::external-saml.txt[]
 include::external-oauth.txt[]
 
 include::external-pam.txt[]
+
+include::authenticator-otp-ldap.txt[]

engine-api/src/main/java/pl/edu/icm/unity/engine/api/authn/CredentialVerificator.java

@@ -27,13 +27,8 @@ public enum VerificatorType
 
 	/**
 	 * Instance name is the configured name of the authenticator to which this credential verificator belongs.
-	 * @param name
 	 */
 	void setInstanceName(String name);
 
-	/**
-	 * 
-	 * @return verificator type
-	 */
 	VerificatorType getType();
 }

integration-tests/src/test/resources/otp-ldap.properties

@@ -0,0 +1,8 @@
+otpldap.servers.1=localhost
+otpldap.ports.1=389
+
+otpldap.userDNTemplate=cn={USERNAME},ou=People,dc=srv,dc=world
+otpldap.systemDN=cn=Manager,dc=srv,dc=world
+otpldap.systemPassword=ldap-test
+
+otpldap.otpSecretURIAttribute=otp-secret

integration-tests/src/test/resources/unityServer.conf

@@ -149,6 +149,10 @@ unityServer.core.credentials.3.credentialConfigurationFile=src/test/resources/fi
 # Authenticators
 #######################################
 
+unityServer.core.authenticators.otpldap.authenticatorName=OTP LDAP
+unityServer.core.authenticators.otpldap.authenticatorType=otp-ldap
+unityServer.core.authenticators.otpldap.configurationFile=src/test/resources/otp-ldap.properties
+
 unityServer.core.authenticators.1.authenticatorName=pwdSys
 unityServer.core.authenticators.1.authenticatorType=password
 unityServer.core.authenticators.1.localCredential=sys:password

otp-ldap/src/main/java/io/imunity/otp/ldap/OTPWithLDAPProperties.java

@@ -11,6 +11,7 @@
 
 import org.apache.logging.log4j.Logger;
 
+import eu.unicore.util.configuration.DocumentationReferenceMeta;
 import eu.unicore.util.configuration.DocumentationReferencePrefix;
 import eu.unicore.util.configuration.PropertyMD;
 import io.imunity.otp.HashFunction;
@@ -40,6 +41,7 @@ class OTPWithLDAPProperties extends LDAPConnectionProperties
 	@DocumentationReferencePrefix
 	public static final String PREFIX = "otpldap.";
 
+	@DocumentationReferenceMeta
 	public final static Map<String, PropertyMD> defaults = new HashMap<String, PropertyMD>();
 
 	static