Various options supported in Ranger Usersync with AD/LDAP as the sync source

[#1]

This article mainly focuses mainly on what all supported options available in User sync and how they can be used to target specific use cases. For some common use cases examples and how ranger can be configured in those cases, please refer to Configuring Ranger UserSync with AD/LDAP

1. User based search without enable group sync:
   1. This configuration can be used in cases where customers want to sync users based on a OU or a user search filter and get all the groups the users belong to.
   2. This case is supported only when the user object has the group membership attributes like “memberof” or “ismemberof”.
   3. This option is available only in Full sync case (i.e., when Incremental sync is disabled in Ranger User sync configuration)
2. User based search with enable group sync:
   1. This configuration can be used in cases where -
      1. customers want to sync users based on a OU or a user search filter and want to limit the groups that these user belong to based on the OU or a group search filter.
      2. Group membership attributes like “memberof” is not available for the user objects.
   2. This is the default option when “Incremental Sync” is enabled in Ranger Usersync configuration
   3. This option is available for both “Incremental Sync” or “Full Sync”

Group based search without enable user sync (RANGER-869):

1. This option is available for both “Incremental Sync” or “Full Sync”
2. This option cannot be used in cases where customers want to sync the users with “sAMAccountName” instead if “CN”
3. This is the default option when “Group Search First Enable” is set to “true”
4. This configuration can be used in cases where -
   1. customers want to sync groups based on a OU or a group search filter and get all the users that belong to those groups.
   2. customers want to sync the groups that don’t have any users

Group based search with enable user sync (RANGER-869):

1. This configuration can be used in cases where

1. customers want to sync groups based on a OU or a group search filter and limit the users that belong to those groups based on a OU or a user search filter.
2. customers want to sync groups based on a OU or a group search filter and use the “sAMAccountName” for the user instead of “CN”
3. customers want to sync the groups that don’t have any users

This option is available for both “Incremental Sync” or “Full Sync”

Multiple OUs for User search base and/or Group search base (RANGER-803):

1. This configuration can be used in cases where customers want to sync users and/or groups from multiple OUs
2. Multiple OUs can be specified in the User search base and/or Group search base using “;” separated like ou=OU1,dc=hortonworks,dc=com;ou=OU2,dc=hortonworks,dc=com;ou=OU3,dc=hortonworks,dc=com
3. Multiple OUs are supported for both User based search and Group based search

Incremental Sync or Full sync (RANGER-1211):

1. Incremental Sync -

1. Ranger Usersync can be configured to perform full sync only during startup and incremental sync for the subsequent sync cycles.
2. This is the default option for fresh installs of HDP version 2.6 onwards
3. With this option, “Enable Group Sync” is mandatory
4. This option is highly recommended in order to improve usersync performance and decrease the startup time of Ranger.

Full sync -

1. Ranger Usersync can be configured to perform full sync from AD/LDAP for every sync cycle.
2. This is the default option for clusters upgraded to 2.6 or higher

Username and/or Groupname case conversion: Ranger usersync support three options for case conversion of username and/or groupname - “lower”, “upper”, and “none”

1. “None” is the default option for case conversion
2. This option must be configured to be same as the hdfs users/groups as ranger authorization is case sensitive for username and/or groupname.
3. Ranger usersync properties for case conversion are:
   1. ranger.usersync.ldap.username.caseconversion
   2. ranger.usersync.ldap.groupname.caseconversion

Username and/or Groupname transformation (RANGER-684):

1. Ranger Usersync can be configured to perform username and/or groupname transformations in order to make them POSIX compliant.
2. The value for these properties should be in the following format (similar to Sed format):“s/regex/replacement/g”s – stands for substitution and is mandatory/ - delimiter and is mandatoryRegex – regular expression to matchReplacement – value to replace and is optional. If not specified, the found pattern is removed from the resulting string.g – for replacing all the occurrences. It is optional and if not specified, default to “g” as well.
3. In order to enable this feature, following properties should be added as custom usersync site properties in Ambari:
   1. ranger.usersync.mapping.username.handler - value as “org.apache.ranger.usergroupsync.RegEx”
   2. ranger.usersync.mapping.groupname.handler - value as “org.apache.ranger.usergroupsync.RegEx”
   3. ranger.usersync.mapping.username.regex - value must be in the format defined in section #b above
   4. ranger.usersync.mapping.groupname.regex - value must be in the format defined in #b above

To configure multiple transformations/mappings:

1. new regex properties can be added as: ranger.usersync.mapping.<attribute name>.<tranformation>.1, ranger.usersync.mapping.<attribute name>.<tranformation>.2, etc…
2. All these transformations will be applied in the order they were configured.

LDAP or LDAPS or STARTTLS (RANGER-722):

1. Ranger Usersync support both secure and non-secure communication to AD/LDAP server for performing the sync operation.
2. Ranger usersync can be configure with LDAPS or STARTTLS for secure communication
3. For LDAP/LDAPS, ldap url must be configured accordingly with the corresponding port. For example -
   1. For non-secure/LDAP communication, sample ldap url value is “ldap://10.10.10.10:389”
   2. For secure with LDAPS communication, sample ldap url value is “ldaps://ad.hortonworks.COM:636”

In order to configure Ranger Usersync to use STARTTLS instead of LDAPS -

1. Add “ranger.usersync.ldap.starttls” with value “true” in custom usersync site properties in Ambari
2. Set LdapURL property to be in the format “ldap://10.10.10.10:389”

[#2]

This is a useful article, but I would be better by explaining what the different main configurations do instead of listing interpretation of the best use case (as perceived by the creator) for each combination. By knowing what each of these few options do or how do they affect the behavior regarding the matching of users and groups from LDAP, I'm pretty sure most of us IT professionals will be able to find out in which case each combination is more appropriate for our use case.

Indeed that is a recurrent problem with Ranger documentation in HDP and with many other aspects of security components, you usually will find out "subjective" interpretation of what combination of settings are best for this or that scenario, but the objective description of how each options behaves is much harder to find, and sometimes the only way to find out this is going to the source code.