Using the LDAP Connection Check Tool
The LDAP Connection Check tool is a command line tool that helps Ranger administrators configure LDAP properties for the UserSync module. The tool collects minimal input from the administrator 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 options such as discovering/verifying UserSync-related properties as well as authentication properties, generating install properties for manual installation, etc. Once all of the required properties have been discovered and tested, these properties can be applied to the Ranger configuration during Ambari or non-Ambari cluster installation.
The LDAP Connection tool can be accessed in the
/usr/hdp/current/ranger-usersync/ldaptool
directory.
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 orusers
-- discover only user search related properties orgroups
-- 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=