Ldap Connection Check tool is a command line tool that helps Ranger admin to configure Ldap properties for UserSync module. This tool collects minimal input from admin about the ldap/AD server and discovers various properties for users and groups in order to successfully pull only targeted Users and Groups from the Ldap/AD server. It provides various options like discovering/verifying user sync related properties as well as authentication properties, generating install properties for manual installation, etc. Once all the required properties are discovered and tested, these properties can be applied in Ranger config either through Ambari or manual install.
Ldap Connection check tool is a command line tool and can be run on any machine where Java is installed and Ldap/AD server access is available. This tool can be used to discover not only user sync related properties but also authentication properties if needed. It also generates ambari configuration properties as well as install properties for manual installation. User is also provided an option to discover both the user and group properties together or separately. As part of the tool, a template properties file is provided for the user to update the values specific to the setup.
Following are the various options provided by the tool:
Discover usersync related properties
Discover authentication related properties
Retrieve total count as well as details of first 20 users or groups or both by providing corresponding usersync properties.
Read the input properties either from an input file or from the command line.
Ldap connection check tool is built as part of regular ranger build and is packed with ranger UserSync module. Following are the installation steps for this tool:
Content of ldaptool directory:
In order to learn details on how to use the tool, the tool also provides an “help” option (-h) as follows:
usage: run.sh
-a 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 above parameters are optional.
If “-i” (for input file) is not specified, the tool will fall back to CLI option for collecting values for mandatory properties
if “-o” (for output directory) is not specified, the tool will write all the output files to the <install dir>/ranger-0.5.0-usersync/ldaptool/output directory
if “-a” (for ignoring authentication) is not specified, the tool will discovery & verify authentication related properties.
if “-d” (for discovering usersync properties) is not specified, the tool will default to discovering all the usersync related properties
if “-r” (for retrieving users and/or groups) is not specified, the tool will fallback to “-d” option.
In order to discover the usersync and authentication related properties, tool collects some mandatory information as part of the input properties. These Mandatory properties include:
Mandatory properties include:
1. ranger.usersync.ldap.url (<ldap or ldaps>://<server ip/fqdn>:<port>
2. ranger.usersync.ldap.binddn (ldap user like AD user or ldap admin user)
3. ranger.usersync.ldap.bindpassword (user password or ldap admin password)
4. ranger.usersync.ldap.user.searchbase (Mandatory only for non AD environment)
5. ranger.usersync.ldap.user.searchfilter (Mandatory only for non AD environment)
6. ranger.admin.auth.sampleuser (Mandatory only for discovering authentication properties)
7. ranger.admin.auth.samplepassword (Mandatory only for discovering authentication properties)
This tool provides two options for collecting values for these mandatory properties:
Modify the input.properties file provided as part of the tool installation and provide that file (with complete path as the command line argument while running the tool.
Use CLI to input the values for these mandatory properties.
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.
Following is the CLI provided by the tool when input file is not specified:
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.
Usersync related properties are divided into two categories - User search related properties and group search related properties. This tool provides an option (“-d”) to discover user related and group related properties separately or at once. Following is the discover properties option:
-d,--discoverProperties <arg> {all|user|group}
where <arg> can be
all: discover all the properties at once or
user: discover only user search related properties or
group: discover only group search related properties
These properties are discovered based on the values provided in the input file for all the mandatory properties.
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 the properties are discovered, the tool also retrieves the total count and details of first 20 users and/or groups and displayed in the output.
Value for user search base is derived as the OU with max. no of users (from the first 20 users that are retrieved).
Value for user search filter is derived as <user name attribute>=*
Value for group search base is derived as the OU with max. no of groups (from the first 20 retrieved groups).
Value for group search filter is derived as <group name attribute>=*
This tool provides an option (-a) to skip discovery of authentication properties. When admin runs the tool with this option, the tool will not suggest the values for authentication related properties. The authentication option is as follows:
-a Ignore authentication properties
If the ldap server is of type active directory, following properties are suggested:
ranger.authentication.method
ranger.ldap.ad.domain
Whereas, if the ldap server is not an active directory, 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 just mandatory properties or for all the user and/or group related properties. After discovering the authentication properties, the tool also validates those properties by authenticating the given user and provides authentication success or failure result in the output.
In order to test the user and/or group related properties, this tool provides an option (-r) to retrieve top 20 users/groups by providing the values for corresponding properties in the input file. Following is the retrieve option:
-r,--retrieve <arg> {all|users|groups}
where arg can be:
users: retrieve total count and details of first 20 users and associated groups, given the user search related properties in the input file
groups: retrieve total count and details of first 20 groups and associated users, given the group search related properties in the input file
all: retrieve both users and groups, given all the corresponding properties in the input file.
This tool generates three files in the specified output directory or by default to <install dir>/ranger-0.5.0-usersync/ldaptool/output -
ambari.properties
install.properties
ldapConfigCheck.log
All the discovered properties (related to usersync and/or authentication) are written to both ambari.properties and install.properties files with the corresponding property names.
All the other information like any retrieved users/groups, total count, authentication result, etc… are written to ldapConfigCheck.log file. This log file also contains any errors or warning generated while running the tool.
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 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 to be performed.
Following are the remaining usersync related properties. These 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 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 not used by the tool.
Some of the properties are assumed to have one or more values as follows:
1. User name attribute - "sAMAccountName", "uid", "cn"
2. User Object class value - "person", "posixAccount"
3. User group member attribute - "memberOf", "ismemberOf"
4. Group Object class - "group", "groupOfNames", "posixGroup"
5. Group name attribute - "distinguishedName", "cn"
6. Group member attribute - "member", "memberUid"
# 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=