Knox Gateway Administration Guide
Also available as:
PDF
loading table of contents...

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]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:

  1. Open the cluster topology descriptor file, $cluster-name.xml, in a text editor.

  2. 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> <name>main.ldapRealm.userDnTemplate</name> <value> $USER_DN </value> </param> <name>main.ldapRealm.contextFactory.url</name> <value> $protocol :// $ldaphost : $port </value> </param> <name>main.ldapRealm.contextFactory.authenticationMechanism</name> <value>simple</value> </param> <name>urls./**</name> <value> $auth_type </value> </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.

  3. Save the file.

    The gateway creates a new WAR file with modified timestamp in $gateway/data/deployments.