Setting Up LDAP Authentication

LDAP authentication is configured by adding a "ShiroProvider" authentication provider to the cluster's topology file. When enabled, the Knox Gateway uses Apache Shiro (org.apache.shiro.realm.ldap.JndiLdapRealm) to authenticate users against the configured LDAP store.

	Note
	Knox Gateway provides HTTP BASIC authentication against an LDAP user directory. It currently supports only a single Organizational Unit (OU) and does not support nested OUs.

To enable LDAP authentication:

Open the cluster topology descriptor file, $cluster-name.xml, in a text editor.
Add the ShiroProvider authentication provider to /topology/gateway as follows:
```
<provider>
    <role>authentication</role>
    <name>ShiroProvider</name>
    <enabled>true</enabled>
    <param>
        <name>main.ldapRealm</name>
        <value>org.apache.shiro.realm.ldap.JndiLdapRealm</value>
    <param>
    <param>
        <name>main.ldapRealm.userDnTemplate</name>
        <value>$USER_DN</value>
    </param>
    <param>
        <name>main.ldapRealm.contextFactory.url</name>
        <value>$protocol://$ldaphost:$port</value>
    </param>
    <param>
        <name>main.ldapRealm.contextFactory.authenticationMechanism</name>
        <value>simple</value>
    </param>
    <param>
        <name>urls./**</name>
        <value>$auth_type</value>
    </param>
    <param>
        <name>sessionTimeout</name>
        <value>$minutes</value>
    </param>
</provider>
```
where:
- $USER_DN
  is a comma-separated list of attribute and value pairs that define the User Distinguished Name (DN). The first pair must be set to " $attribute_name ={0}" indicating that the $attribute_name is equal to the user token parsed from the request. For example, the first attribute in an OpenLdap definition is UID={0}. The main.ldapRealm.userDnTemplate parameter is only required when authenticating against an LDAP store that requires a full User DN.
- $protocol :// $ldaphost : $port
  is the URL of the LDAP service, Knox Gateway supports LDAP or LDAPS protocols.
- $auth_type
  is either authcBasic, which provides basic authentication for both secured and non-secured requests, or ssl authcBasic, which rejects non-secured requests and provides basic authentication of secured requests.
- $minutes
  is the session idle time in minutes, the default timeout is 30 minutes.
Save the file.
The gateway creates a new WAR file with modified timestamp in $gateway/data/deployments.

	Note
	If the Active Directory and Kerberos names differ in case (e.g. the Active Directory name is in upper case and the Kerberos name is lower case), the Knox Gateway enables you to resolve this conflict using the `auth_to_local` flag.

You can also configure LDAP authentication over SSL by following the steps below.

Change the LDAP protocol from ladp :// to ldaps://.
If LDAP is using a self-signed certificate, then import the LDAP's certificate into the CACerts file of the Java Virtual Machine (JVM) being used to run the Apache Knox Gateway. To import the LDAP certificate, enter the following commands:
```
%JAVA_HOME%\bin\keytool
-import -trustcerts -alias ldap_ssl -file C:\temp\FileFromLDAP.cert -keystore %JAVA_HOME%/jre/lib/security/cacerts -storepass "changeit"
```

​Setting Up LDAP Authentication

Setting Up LDAP Authentication