1. Advanced LDAP Configuration

Use the advanced LDAP configuration to take advantage of LDAP searches. For example, in environments where users are not in the same branch of the LDAP DIT, user login token is an attribute that is not in the UserDN or to lookup a user's group membership.

To enable an advanced LDAP configuration:

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.hadoop.gateway.shirorealm.KnoxLdapRealm</value>
	</param>

	<param>
		<name>main.ldapContextFactory</name>
		<value>org.apache.hadoop.gateway.shirorealm.KnoxLdapContextFactory</value>
	</param>

	<param>
		<name>main.ldapRealm.contextFactory</name>
		<value>$ldapContextFactory</value>
	</param>

	<param>
		<name>main.ldapRealm.contextFactory.url</name>
		<value>$protocol://$ldap-host:$port</value>
	</param>

	<param>
		<name>main.ldapRealm.contextFactory.authenticationMechanism</name>
		<value>$mechanism</value>
	</param>

	<param>
		<name>main.ldapRealm.userDnTemplate</name>
		<value>$userDN</value>
	</param>

	<param>
		<name>main.ldapRealm.userSearchAttributeName</name>
		<value>$userid-attribute</value>
	</param>

	<param>
		<name>main.ldapRealm.authorizationEnabled</name>
		<value>$true_or_false</value>
	</param>

	<param>
		<name>main.ldapRealm.contextFactory.systemUsername</name>
		<value>$ldapuserDN</value>
	</param>

	<param>
		<name>main.ldapRealm.contextFactory.systemPassword</name>
		<value>${ALIAS=ldcSystemPassword}</value>
	</param>

	<param>
		<name>main.ldapRealm.contextFactory.systemAuthenticationMechanism</name>
		<value>simple</value>
	</param>

	<param>
		<name>main.ldapRealm.userObjectClass</name>
		<value>$user-class</value>
	</param>

	<param>
		<name>main.ldapRealm.searchBase</name>
		<value>$searchbaseDN</value>
	</param>

	<param>
		<name>main.ldapRealm.userSearchBase</name>
		<value>$userSearchBaseDN</value>
	</param>

	<param>
		<name>main.ldapRealm.groupSearchBase</name>
		<value>$groupSearchBaseDN</value>
	</param>
 
	<param>
		<name>main.ldapRealm.groupObjectClass</name>
		<value>$group-class</value>
	</param>
  
	<param>
		<name>main.ldapRealm.memberAttribute</name>
		<value>$member-attribute</value>
	</param>

  <param>
    <name>main.ldapRealm.memberAttributeValueTemplate</name>
    <value>$memberDN</value>
  </param>
  
	<param>
		<name>main.ldapRealm.groupIdAttribute</name>
		<value>$group-attribute</value>
	</param>

	<param>
		<name>urls./**</name>
		<value>$auth_type </value>
	</param>

	<param>
		<name>sessionTimeout</name>
		<value>$minutes</value>
	</param>

</provider>

	Warning
	The value for `main.ldapRealm.contextFactory` parameter is `$ldapContextFactory` and the value for `main.ldapRealm.contextFactory.systemPassword` to use an alias is `${ALIAS=accountalias}`. (The dollar symbol '$' in these fields does not represent a user replaceable variable.)

Where the following variables are specific to your environment:

Table 6.1. Advanced LDAP Parameter Values

Parameter Name	Value	Description
`main.ldapContextFactory`	`org.apache.hadoop.gateway.shirorealm.KnoxLdapRealm`	Extends the Apache Shiro provider to allow for LDAP searches and to provide group membership to the authorization provider. (Use the value shown.)
`main.ldapRealm.contextFactory`	`$ldapContextFactory`^[a]	Must be set to `$ldapContextFactory`. (Use the value shown.)
`main.ldapRealm.contextFactory.url`	`$protocol`://`$ldaphost`:`$port`	Specify the URL of the LDAP service, Knox Gateway supports LDAP or LDAPS protocols. For example: `ldap://hdp.example.com:389`.
`main.ldapRealm.contextFactory.authenticationMechanism`	`$mechanism`	Specify the authenticated mechanism used by the LDAP service. For example, `simple`.
`main.ldapRealm.userDnTemplate`	`$USER_DN` ^[b]	Optional. Knox uses this value to construct the UserDN for the authentication bind. Specify the UserDN where the first attribute is equal to `{0}` indicating the attribute which matches the user log in token. For example, the UserDnTemplate for Apache DS bundled with Knox is `uid={0},ou=people,dc=hadoop,dc=apache,dc=org`.
`main.ldapRealm.userSearchAttributeName`	`$userid-attribute`^[c]	Optional, the default value is null. Specify the attribute that corresponds to the user login token. This attribute is used with the search results to compute the UserDN for the authentication bind. For example: `email`.
`main.ldapRealm.authorizationEnabled`	`true` or `false`	Set to `true` to enable group lookup for use with the authorization provider.
`main.ldapRealm.contextFactory.systemUsername`	`$ldap-serviceaccountDN`	Set to the LDAP Service Account that the Knox Gateway uses for LDAP searches, if required specify the full account UserDN. For example: `uid=guest,ou=people,dc=hadoop,dc=apache,dc=org`. This account requires read permission to the search base DN.
`main.ldapRealm.contextFactory.systemPassword`	`${ALIAS=accountalias}` or `plaintextpassword`	Specify the value as "`${ALIAS=accountalias}`" where `accountalias` is the alias name and save the LDAP Service account password to the credential store, see Saving the LDAP Password in the Credential Store. Alternatively, you can put the password in plain text for testing.
`main.ldapRealm.userObjectClass`	`$user-class`	The LDAP class name of the user object. For example: `person`.
`main.ldapRealm.searchBase`	`$searchbaseDN`	The starting DN in the LDAP DIT for the search. Only subtrees of the specified subtree are searched. For example: `dc=hadoop,dc=apache,dc=org`.
`main.ldapRealm.userSearchBase`	`$userSearchBaseDN`	Search base for user bind DN. Defaults to the value of `main.ldapRealm.searchBase` if no value is defined. If `main.ldapRealm.userSearchAttributeName` is defined, also define a value for either `main.ldapRealm.searchBase` or `main.ldapRealm.userSearchBase`.
`main.ldapRealm.groupSearchBase`	`$groupSearchBaseDN`	Search base used to search for groups. Defaults to the value of `main.ldapRealm.searchBase`. Only set if `main.ldapRealm.authorizationEnabled` is `true`.
`main.ldapRealm.groupObjectClass`	`$group-class`	Optional, the default value is `groupOfNames`. Set value to the Objectclass that identifies group entries in LDAP. Knox uses this value to build search filter to search for group entries.
`main.ldapRealm.memberAttribute`	`$member-attribute`	Optional, the default value is `member`. Set the value to the attribute that defines group membership. When the value is rememberer, found groups are treated as dynamic groups.
`main.ldapRealm.memberAttributeValueTemplate`	`$member-value`^[d]	Optional, the default value is `uid={0}`. This is the attribute that identifies the user in the group.
`main.ldapRealm.groupIdAttribute`	`$group-attribute`	Optional, the default value is `cn`. Specify the attribute that uniquely identifies the group.
`urls./`	`authcBasic`	Set to `authcBasic` which provides basic authentication.
`sessionTimeout`	`$minutes`	Defines the session idle time in minutes. The default timeout is 30 minutes.
^[a]Is not a user defined variable, use the literal value including '$'. ^[b]This value is ignored when the value for `main.ldapRealm.userSearchAttributeName` is also defined. ^[c]When this value is specified the `useDnTemplate` is ignored. ^[d]This field is ignored if `main.ldapRealm.userSearchAttributeName` is defined.

Save the file.
The gateway creates a new WAR file with modified timestamp in /var/lib/knox/data/deployments .

Legal notices