Using the LDAP Connection Check Tool

LDAP Connection Check Tool Parameters

You can use the ./run.sh -h command to list the LDAP Connection Check tool parameters:

cd /usr/hdp/current/ranger-usersync/ldaptool
./run.sh -h
usage: run.sh
 -noauth         ignore authentication properties
 -d <arg>   {all|users|groups}
 -h                       show help.
 -i <arg>            Input file name
 -o <arg>            Output directory
 -r <arg>             {all|users|groups}

All these parameters are optional.

If “-i” (for input file) is not specified, the tool will fall back to the CLI option for collecting values for mandatory properties.
if “-o” (for output directory) is not specified, the tool will write all of the output files to the /usr/hdp/current/ranger-usersync/ldaptool/output directory.
if “-noauth” (for ignoring authentication) is not specified, the tool will discovery and verify authentication-related properties.
if “-d” (for discovering usersync properties) is not specified, the tool will default to discovering all of the usersync-related properties.
if “-r” (for retrieving users and/or groups) is not specified, the tool will fallback to the “-d” option.

Input Properties

In order to discover the usersync and authentication related properties, the LDAP Connection Check tool collects some mandatory information as part of the input properties. These mandatory properties include:

ranger.usersync.ldap.url (<ldap or ldaps>://<server ip/fqdn>:<port>)
ranger.usersync.ldap.binddn (ldap user like AD user or ldap admin user)
ranger.usersync.ldap.bindpassword (user password or ldap admin password)
ranger.usersync.ldap.user.searchbase (Mandatory only for non AD environment)
ranger.usersync.ldap.user.searchfilter (Mandatory only for non AD environment)
ranger.admin.auth.sampleuser (Mandatory only for discovering authentication properties)
ranger.admin.auth.samplepassword (Mandatory only for discovering authentication properties)

Modify the input.properties file provided as part of the tool installation and provide that file (with the complete path as the command line argument while running the tool.
Use the CLI to input the values for these mandatory properties.

The CLI option is provided to the user when the input file is not provided as the command line option (-i <arg>) while running the tool. Once the values are collected from the CLI, these values are stored in the input.properties file (in the conf dir of the installation folder) for later use.

The following is the CLI provided by the tool when input file is not specified. The tool provides two options for collecting values for these mandatory properties:

Ldap url [ldap://ldap.example.com:389]: 
Bind DN [cn=admin,ou=users,dc=example,dc=com]: 
Bind Password:
User Search Base [ou=users,dc=example,dc=com]:
User Search Filter [cn=user1]:
Sample Authentication User [user1]:
Sample Authentication Password:

	Note
	In order to use secure LDAP, the Java default truststore must be updated with the server’s self signed certificate or the CA certificate for validating the server connection. The truststore should be updated before running the tool.

Discovery of UserSync Properties

Usersync-related properties are divided into two categories: User search related properties and group search related properties. This tool provides a -d option to discover user related and group related properties separately or all at once. The discover properties option is used as follows:

./run.sh -d <arg>

where <arg> can be

all: discover all of the properties at once or
users: discover only user search related properties or
groups: discover only group search related properties

These properties are discovered based on the values provided in the input file for all of the mandatory properties.

The following are the user search related properties that are discovered using this tool:

Basic properties:
- ranger.usersync.ldap.user.objectclass
- ranger.usersync.ldap.user.groupnameattribute
- ranger.usersync.ldap.user.nameattribute
Advanced properties:
- ranger.usersync.ldap.user.searchbase
- ranger.usersync.ldap.user.searchfilter

Group search related properties that are discovered by this tool are as follows:

Basic properties:
- ranger.usersync.group.searchenabled
- ranger.usersync.group.objectclass
- ranger.usersync.group.memberattributename
- ranger.usersync.group.nameattribute
Advanced properties:
- ranger.usersync.group.searchbase
- ranger.usersync.group.searchfilter

Once all of the properties are discovered, the tool also retrieves the total count and details of first 20 users and/or groups and displays them in the output.

The value for the user search base is derived as the OU with max. no of users (from the first 20 users that are retrieved).
The value for the user search filter is derived as <user name attribute>=*
The value for the group search base is derived as the OU with max. no of groups (from the first 20 retrieved groups).
The value for the group search filter is derived as <group name attribute>=*

Discovery of Authentication Properties

The LDAP Connection Check tool provides a -noauth option to skip discovery of authentication properties. When this option is used, the tool will not suggest the values for authentication related properties.

./run.sh -noauth

If the LDAP server is of type active directory, the following properties are suggested:

ranger.authentication.method
ranger.ldap.ad.domain

If the LDAP server is not an active directory, the following properties are suggested:

ranger.authentication.method
ranger.ldap.user.dnpattern
ranger.ldap.group.roleattribute
ranger.ldap.group.searchbase
ranger.ldap.group.searchfilter

These authentication properties can be discovered either by providing the values in the input file for only mandatory properties, or for all of the user and/or group related properties. After discovering the authentication properties, the tool also validates those properties by authenticating the given user, and reports authentication success or failure in the output.

Retrieval of Users and Groups

Usersync-related properties are divided into two categories: User search related properties and group search related properties. This tool provides a -d option to discover user related and group related properties separately or all at once. The discover properties option is used as follows:

./run.sh -r <arg>

where <arg> can be

users : retrieve the total count and details of the first 20 users and associated groups, given the user search related properties in the input file.
groups : retrieve the total count and details of the first 20 groups and associated users, given the group search related properties in the input file.
all : retrieve both users and groups, given all of the corresponding properties in the input file.

Output Directory Content

This tool generates three files in the output directory specified with the -o option, or by default to the /usr/hdp/current/ranger-usersync/ldaptool/output directory.

ambari.properties
install.properties
ldapConfigCheck.log

All of the discovered properties (related to usersync and/or authentication) are written to both the ambari.properties and install.properties files with the corresponding property names.

All of the other information, such as any retrieved users/groups, total count, authentication result, etc. are written to the ldapConfigCheck.log file. This log file also contains any errors or warnings generated while running the tool.

Other UserSync Related Properties

Some of the other usersync-related properties that are used by the tool and left with default values are:

ranger.usersync.ldap.authentication.mechanism - Default authentication mechanism used is “simple”.
ranger.usersync.pagedresultsenabled - Default is set to “true”.
ranger.usersync.pagedresultssize - Default value for this property is “500”. This value can be tweaked depending on the bandwidth and resource availability in the deployment.
ranger.usersync.ldap.username.caseconversion - Default value is set to “lower”
ranger.usersync.ldap.groupname.caseconversion - Default value is set to “lower”
ranger.usersync.ldap.user.searchscope - Default is set to “sub”. This value can be set to either “base” or “one” depending on how the user search is to be performed.
ranger.usersync.group.searchscope - Default is set to “sub”. This value can be set to either “base” or “one” depending on how the group search is to be performed.

The following are the remaining usersync-related properties. These properties are not currently used by the tool and the values are left empty in the input file.

ranger.usersync.credstore.filename - this property is unused as the tool supports only cleartext password.
ranger.usersync.ldap.bindalias - this property is also not used by the tool.
ranger.usersync.ldap.searchBase - This property is used as the user search base or group search base when they are not configured. Hence this value is left blank and not used by the tool.
ranger.usersync.group.usermapsyncenabled - Mainly used for computing group memberships while retrieving users. Currently this value is set to “true”, but is not used by the tool.

Assumptions

Some properties are assumed to have one or more values as follows:

User name attribute : "sAMAccountName" , "uid" , "cn"
User Object class value : "person" , "posixAccount"
User group member attribute : "memberOf" , "ismemberOf"
Group Object class : "group" , "groupOfNames" , "posixGroup"
Group name attribute : "distinguishedName" , "cn"
Group member attribute : "member" , "memberUid"

Sample input.properties File

# Mandatory ldap configuration properties.
ranger.usersync.ldap.url=
ranger.usersync.ldap.binddn=
ranger.usersync.ldap.ldapbindpassword=

# Mandatory only for openLdap
ranger.usersync.ldap.user.searchbase=
ranger.usersync.ldap.user.searchfilter=

# For verifying authentication please provide sample username and password
ranger.admin.auth.sampleuser=
ranger.admin.auth.samplepassword=

# Optional properties will be determined based on the above search
# User attributes
ranger.usersync.ldap.user.nameattribute=
ranger.usersync.ldap.user.objectclass=
ranger.usersync.ldap.user.groupnameattribute=

# Group attributes
ranger.usersync.group.searchenabled=false
ranger.usersync.group.memberattributename=
ranger.usersync.group.nameattribute=
ranger.usersync.group.objectclass=
ranger.usersync.group.searchbase=
ranger.usersync.group.searchfilter=

# Other UserSync related attributes
ranger.usersync.ldap.authentication.mechanism=simple
ranger.usersync.pagedresultsenabled=true
ranger.usersync.pagedresultssize=500
ranger.usersync.ldap.username.caseconversion=lower
ranger.usersync.ldap.groupname.caseconversion=lower
ranger.usersync.ldap.user.searchscope=sub
ranger.usersync.group.searchscope=sub

ranger.usersync.credstore.filename=
ranger.usersync.ldap.bindalias=
ranger.usersync.ldap.searchBase=
ranger.usersync.group.usermapsyncenabled=false

# Authentication properties
ranger.authentication.method=
ranger.ldap.ad.domain=
ranger.ldap.user.dnpattern=
ranger.ldap.group.roleattribute=
ranger.ldap.group.searchbase=
ranger.ldap.group.searchfilter=