Skip to main content
Hitachi Vantara Lumada and Pentaho Documentation

LDAP Configuration

Parent article

LDAP authentication modes

In this section, the LDAP authentication modes are explained in detail. If you want to set up the LDAP authentication, realize which authentication mode of LDAP you need.

  • bind-only

    The bind-only mode uses the user supplied credentials to substitute the authIdentityPattern property with the {USERNAME} token and then binds to the LDAP server. If the bind is successful, authentication succeeds.

  • bind-search

    The bind-search mode works in two steps:

    • The user supplied credentials are used to substitute the authIdentityPattern property with the {USERNAME} token and then binds to the LDAP server.
    • If the bind is successful, a search is performed using the filter specified by searchFilterPattern property. If the search returns exactly one result, the authentication succeeds.
  • search-bind

    The search-bind mode works in four steps:

    1. The module binds to the server using system user credentials (searchUser and searchPassword)
    2. A search is performed using the filter specified by the searchFilterPattern property.
    3. It is validated that the search returns exactly one result, otherwise authentication fails.
    4. A second bind is performed using the password provided during login and - either the substituted authIdentityPattern or another specified attribute (attributeToExtract) to be extracted from the search result - as the principal. If the bind is successful, authentication succeeds.

LDAP properties

The following properties are available for use with LDAP authentication. All properties should be prefixed with ldc.web.pam.property and should be added/edited in login.properties.

  • providerUrl

    The URL of your LDAP/Active Directory server. If you have an Active Directory Global Catalog, this should point to the port number of the catalog. If SSL is required, use the appropriate port.

  • authIdentityPattern

    The pattern for the principal of the end user that binds to the LDAP server. This must contain the {USERNAME} token that gets substituted with the actual username that is passed in. Applicable in the bind-only and bind-search authentication modes and applicable in search-bind unless the doExtractAttribute is set to true, in which case the attributeToExtract is used as the principal instead.

  • searchBase

    This is the base of the directory where the search is performed. Applicable for bind-search and search-bind authModes only.

  • searchFilterPattern

    The search to perform. This restricts the users logging in to certain groups. This must contain the {USERNAME} token and must return exactly one entry. Applicable for bind-search and search-bind authModes only.

  • searchUser and searchPassword

    The credentials of the designated system user to bind and perform the initial search. Applicable for search-bind authMode only.

  • doExtractAttribute and attributeToExtract

    Applicable for search-bind authMode only. If the doExtractAttribute is set to true, the module uses the attributeToExtract property (for example, distinguishedName) to look up that attribute of the user returned in the search result and uses that value as the principal to send to the LDAP server for the second bind operation.

  • referral

    The referral option for LDAP connection. The value should be either "follow" or "ignore". This property is optional. When not specified, the value is determined by the provider.

  • timeout

    The value in milliseconds for server connection and request timeouts. Optional. Default value is "10000" (10 seconds).

  • debug true | false. Optional

    When set to true, prints out additional information to the console. Should generally be set to false.

NoteIf you have multi-factor authentication enabled, it should generally be completely transparent to the LDAP authentication mechanism. However you can increase the timeout value to allow the user additional time to authenticate using the next factor. For example, if timeout is set to say 60 seconds, the system will wait for (a maximum of) one minute until the user submits a code or a one-time password (OTP), before it times out.

LDAP authentication mode examples

bind-only

To use a Distinguished Name. This is a required property for all LDAP configurations.

waterlinedata.web.pam.fqcn=com.waterlinedata.web.jaas.LdapLoginModulewaterlinedata.web.pam.property.providerUrl=ldaps://
ldap.jumpcloud.com:636
waterlinedata.web.pam.property.authMode=bind-only
waterlinedata.web.pam.property.authIdentityPattern=uid={USERNAME},ou=Users,o=5834bd20ba309ed9201c418a,dc=jumpcloud,dc=com
waterlinedata.web.pam.property.referral=follow waterlinedata.web.pam.property.debug=true

Notice the {USERNAME}@domain.com format. That works generally for Active Directory - with a single domain only. This is a required property for all LDAP configurations.

waterlinedata.web.pam.fqcn=com.waterlinedata.web.jaas.LdapLoginModule
waterlinedata.web.pam.property.providerUrl=ldaps://abc.com:636
waterlinedata.web.pam.property.authMode=bind-only
waterlinedata.web.pam.property.authIdentityPattern={USERNAME} @domain.waterlinedata.com
waterlinedata.web.pam.property.referral=follow waterlinedata.web.pam.property.debug=true
bind-search

This is a required property for all LDAP configurations.

waterlinedata.web.pam.fqcn=com.waterlinedata.web.jaas.LdapLoginModule
waterlinedata.web.pam.property.providerUrl=ldaps://abc.com:636
waterlinedata.web.pam.property.authMode=bind-search waterlinedata.web.pam.property.authIdentityPattern={USERNAME} @domain.waterlinedata.com
waterlinedata.web.pam.property.searchBase=OU=DataAnalytics,dc=waterlinedata,dc=com
waterlinedata.web.pam.property.searchFilterPattern=(&(sAMAccountName={USERNAME})(memberOf=CN=DataScientists,OU=DataAnalytics,dc=waterlinedata,dc=com))  
waterlinedata.web.pam.property.referral=follow waterlinedata.web.pam.property.debug=true
search-bind

To use {USERNAME}@domain.com format. This is a required property for all LDAP configurations.

waterlinedata.web.pam.fqcn=com.waterlinedata.web.jaas.LdapLoginModule
waterlinedata.web.pam.property.providerUrl=ldaps://abc.com:636
waterlinedata.web.pam.property.authMode=search-bind waterlinedata.web.pam.property.authIdentityPattern={USERNAME} @domain.waterlinedata.com
waterlinedata.web.pam.property.searchBase=OU=DataAnalytics,dc=waterlinedata,dc=com
waterlinedata.web.pam.property.searchFilterPattern=(&(sAMAccountName={USERNAME})(memberOf=CN=DataScientists,OU=DataAnalytics,dc=waterlinedata,dc=com))
waterlinedata.web.pam.property.searchUser=administrator@waterlinedata.com
waterlinedata.web.pam.property.searchPassword=s3cr3t
waterlinedata.web.pam.property.referral=follow waterlinedata.web.pam.property.debug=true

To use DN format and DN extraction for end-user. This is a required property for all LDAP configurations.

waterlinedata.web.pam.fqcn=com.waterlinedata.web.jaas.LdapLoginModule
waterlinedata.web.pam.property.providerUrl=ldaps://abc.com:636
waterlinedata.web.pam.property.authMode=search-bind waterlinedata.web.pam.property.searchBase=OU=DataAnalytics,dc=waterlinedata,dc=com
waterlinedata.web.pam.property.searchFilterPattern=(&(sAMAccountName={USERNAME})(memberOf=CN=DataScientists,OU=DataAnalytics,dc=waterlinedata,dc=com))
waterlinedata.web.pam.property.searchUser=CN=administrator,OU=Users,DC=waterlinedata,DC=com
waterlinedata.web.pam.property.searchPassword=s3cr3t
waterlinedata.web.pam.property.doExtractAttribute=true waterlinedata.web.pam.property.attributeToExtract=distinguishedName
waterlinedata.web.pam.property.referral=follow waterlinedata.web.pam.property.debug=true

Mapping LDAP users to Data Catalog roles

Lumada Data Catalog provides the capability to be able to retrieve group information from a user's LDAP and to dynamically assign them roles based on group name to role name mapping.

There are mostly two kinds of LDAP systems:

  • Microsoft Active Directory - AD (Provided by Microsoft. Most commonly used service)
  • OpenLDAP (JumpCloud)

Data Catalog supports both directory services with LDAP and provides configuration properties to support both systems.

However the inherent differences, with respect to user attributes and groups in these systems, calls for unique approaches to support each service.

  • Microsoft LDAP/AD:

    Microsoft AD based LDAP system has the following structure for user attributes and group information. A user can belong to multiple groups and one of these groups will be marked as primary group for a user in the AD tool. Microsoft AD's design mandates a two step process for retrieving these groups information for a user.

    • Retrieve normal user groups from attribute ‘memberOf’

      ‘memberOf’ will return a list of group DN’s (DN: Domain Name which can be used to search for this group/entity within AD).

      The name of a group in AD can be accessed via ‘sAMAccountName’ property

    • Retrieve primary user group from attribute ‘primaryGroupId’

      This returns a unique number from which the linked group and its name should be retrieved.

      The name of the group can be accessed via ‘sAMAccountName’ property

    • Combining both normal groups and the primary group would lead to all of the groups that the user is linked to.
  • OpenLDAP:

    With OpenLDAP on the other hand, the access attributes are simpler and straightforward.

    • User would have an attribute called ‘memberOf’ which returns a list of group DN’s.
    • Resolving these group DN’s to their actual group entities and then accessing the group name from an attribute like ‘ou’ gives us the group name.

Retrieving group information from LDAP

There are two configuration files in WLD Install Dir/app-server/conf directory, which determine how Lumada Data Catalog retrieves group information from an LDAP system.

  • group-to-role-map.json
  • login.properties

Group to role names mapping file

This configuration file currently provides a way to configure and manage group-role mapping in the application.

Group to role mapping file

Sample configuration for Microsoft AD:

{
  "firstName": "givenName",
  "lastName": "sn",
  "email": "mail",
  "userGroupAttributes": [
    {"attributeName": "memberOf", "subAttributeName": "sAMAccountName"},
    {"attributeName": "primaryGroupId", "subAttributeName": "sAMAccountName"}
  ],
  "groupToRoleMap": {
    "QATESTGROUP": ["Administrator", "Guest", "Role1"],
    "AUTOMATIONQA": ["Guest"],
    "DUMMY_GROUPNAME": ["non-existing-role", "Role2"]
  }
}

Where:

  • firstName - is the field in LDAP that denotes the user's first name
  • lastName - is the field in LDAP that denotes the user's last name
  • email - is the attribute that denotes the user's email address in LDAP
  • userGroupAttributes - contains the list of attributes in LDAP that contain the user's group information

    The second entry of attributeName is an optional property and is used with Windows AD/LDAP service

  • groupToRoleMap - contains the list of LDAP group names and the corresponding Lumada Data Catalog roles

Sample configuration for JumpCloud:

{
  "firstName": "givenName",
  "lastName": "sn",
  "email": "mail",
  "userGroupAttributes": [
    {"attributeName": "memberOf", "subAttributeName": "ou"}
  ],
  "groupToRoleMap": {
    "All Users - LDAP": ["Guest"],
    "DUMMY_GROUPNAME": ["non-existing-role", "Steward"]
  }
}

Where:

  • firstName - The attribute using which name for user can be retrieved. givenName is default key in OpenLDAP systems
  • lastName - Accessed via ‘sn’
  • email - Accessed via ‘mail’
  • userGroupAttributes - List of properties that should be accessed for getting groups information for the user.
  • attributeName - Name of the attribute which returns the group information. For OpenLDAP it is ‘memberOf’
  • subAttributeName: Once groups are retrieved and are fetched from LDAP, which attribute needs to be used to retrieve the group name. For OpenLDAP it is ‘ou’. This attribute is optional and can be avoided as well. If this attribute is not provided, then the group names retrieved from attributeName need to be used in the groupToRoleMap.
  • groupToRoleMap - Map of group name (from LDAP) to the role names (in Data Catalog). So a user with a specific group will be assigned the configured roles.
    NoteThe roles are dynamically assigned. Which means, they are not saved to solr. They will be fetched and given to a user upon login dynamically every time.
  • All Users - LDAP - This is the name of one group in JumpCloud which is attached to the users.
    NoteNon existing roles, non existing group names can also be provided. The application will take care of not failing or not assigning invalid roles to the user.
This mapping file group-to-role-map.json can be found under WLD Install Dir/app-server/conf directory

Login.properties

  • For OpenLDAP/JumpCloud we would have an entry like:

    waterlinedata.web.pam.property.ldapGroupClass=(&(objectClass=groupOfNames))

  • For Microsoft AD we would have the following instead:

    waterlinedata.web.pam.property.ldapGroupClass=(&(objectClass=group))

Lumada Data Catalog provides the sample mapping JSON files for JumpCloud and Microsoft AD. The login-ldap.properties should also contain the JumpCloud config by default and will also have sample entry for Microsoft AD.