On this page

    Setting Up LDAP enterprise

    To establish LDAP authentication, do the following on all coordinator nodes prior to deploying the Dremio cluster:

    1. Configure Dremio to use LDAP authentication (via the dremio.conf file).
    2. Configure LDAP (via the ad.json file).

    note:

    Granting Admin Privileges: See Granting Admin Privileges at Configuration Time for information about specifying a list of users and/or groups to be given the Admin role (during initial login) for boot-strap purposes.

    Once the cluster is configured and deployed in LDAP mode,

    • Dremio uses the users and groups defined in LDAP. Administrators cannot create additional users within Dremio.
    • The first user to login with valid LDAP credentials is marked as the Administrator. At this point, other groups/users can be assigned as administrators.

    note:

    The LDAP configuration in the dremio.conf and ad.json files must exist and match on all coordinator nodes.

    Configuring Dremio for LDAP

    warning:

    Dremio does not support changing from LDAP to Dremio authentication modes. Due to the differences in protocols utilized, changing authentication modes from LDAP can result in users being unable to log in and other issues relating to privilege assignment. If you are switching from LDAP authentication to Dremio authentication, you must reinstall Dremio.

    To configure Dremio for LDAP, edit the dremio.conf file, and add the following properties:

    services: {
      coordinator.enabled: true,
      coordinator.web.auth.type: "ldap",
      coordinator.web.auth.ldap_config: "ad.json"
    }
    

    note:

    Ad.json Location: The location of the ad,json file is relative to the conf directory. In addition, the path to the file can be an absolute path; the file can live anywhere in the system.

    Configuring LDAP

    To configure LDAP, edit the ad.json file and add your properties.

    This file located under the Dremio configuration directory (same as dremio.conf path) and is specified in the dremio.conf file as a coordinator service.

    Properties

    PropertyRequiredDescription
    bindMethodNoAuthentication method: UNAUTHENTICATED/ANONYMOUS/SIMPLE_BIND.

    If this property is not specified, authentication defaults to SIMPLE_BIND mode.

    Default: SIMPLE_BIND.
    • SIMPLE_BIND -- Connect and authenticate to LDAP server using bindDN and bindPassword.
    • ANONYMOUS -- Connect anonymously to the LDAP server. Note: When authenticating to Dremio, empty passwords for users are not allowed.
    • UNAUTHENTICATED -- Connect to LDAP server using an unauthenticated bind. bindDN is required.
    bindDNNoCredentials for the user who connects from the Dremio LDAP client to the LDAP server.

    If you are using ANONYMOUS mode, this property is not required. In particular, the following property must not be present:

    "CN=admin,DC=drem,DC=io"

    bindPasswordNoPassword credential for the user who connects from the Dremio LDAP client to the LDAP server.

    If you are using UNAUTHENTICATED or ANONYMOUS mode, this property must not be present.

    baseDNYesThe root path for all searches.

    If userAttributes.baseDNs or groupAttributes.baseDNs are specified, they override baseDN for search purposes.

    searchScopeNoScope of user searches:
    • SUB_TREE -- Searches subtrees below the specified baseDNs (default).
    • ONE -- Searches immediate children below the specified baseDNs.
    • BASE -- Match the exact entry.
    userAttributesNoA mapping of LDAP user attributes to Dremio user attributes. This should include firstname, lastname and email
    userDNsNoList of templates for user DNs.
    idNo
    • If used with the userAttributes property, id is the attribute for the login name. Defaults to sAMAccountName
    • If used with the groupAttibutes property, id is the attribute for the group name (default: CN).
    firstnameNoAttribute for the first name.
    lastnameNoAttribute for the last name.
    emailNoAttribute for the email address.
    userFilterYesLDAP filter for validating users.

    Only users who fit the specific criteria are allowed to authenticate.

    groupDNsNoList of templates for group DNs.
    groupAttributesNoA mapping of LDAP group attributes to Dremio group attributes. The baseDNs, searchScope, id properties are used.
    groupFilterYesLDAP filter for groups.
    userGroupRelationshipNoDetermines whether you are implementing lists based on users or groups.
    • USER_ENTRY_LISTS_GROUPS (Default) -- Specifies whether the user entry in LDAP lists the groups that they belong to. The group attribute in LDAP is configured by the groupMembership property.
    • GROUP_ENTRY_LISTS_USERS -- Specifies whether the group entry in LDAP lists the users that belong to it.
    groupMembershipNomemberOf value. This attribute specifies the groups that a user or a group belongs to.
    groupRecursiveNoAttribute of a user or a group that lists transitive group membership.
    groupEntryListsUsersNoSpecifies the ID attributes used for the user entry and the group entry. Used only with userGroupRelationship and specified with the following sub-properties:
    • userEntryUserIdAttribute
    • groupEntryUserIdAttribute
    connectionModeNOSpecifies a connection mode. Default: PLAIN
    • PLAIN -- Dremio uses an unencrypted connection.
    • ANY_SSL -- Dremio's LDAP client trusts any certificate presented by the LDAP server.
    • TRUSTED_SSL -- Dremio's LDAP client will trust certificates signed by a Certificate Authority; no extra configuration is required. If the LDAP server has a self-signed certificate, a trustStore with the public certificate needs to be passed in as a JVM argument.
    autoAdminFirstUserNoAssigns the Admin role to the first valid LDAP user to log in to Dremio. The assignment occurs during initial login. Options: True/False
    Default: True

    Defining Users

    The following examples show how to define users.

    Example: Using userDNs

    In the following example, a list of templates for user DNs are specified. The placeholder {0} is replaced with the username entered by the user and that DN is used during LDAP bind. Dremio attempts binding to the provided userDNs in the order they are specified.

    "userDNs": ["cn={0},dc=staticsecurity,dc=dremio,dc=com"],
    "userAttributes": {
    	"firstname": "givenName",
    	"lastname": "sn",
    	"email": "mail"
    }
    

    Example: Using userAttributes

    In this example, you are mapping LDAP user attributes to Dremio user attributes.

    "userAttributes": {
    	"baseDNs": [
    		"OU=test,OU=ad,DC=drem,DC=io"
    	],
    	"searchScope": "SUB_TREE",
    	"id": "sAMAccountName",
    	"firstname": "givenName",
    	"lastname": "sn",
    	"email": "mail"
    }
    

    note:

    In the attribute-based approach, userDNs field must not be specified.

    In the DN-based approach, the baseDNs, searchScope, id properties cannot be specified under userAttributes.

    Example: Using userFilter

    The following example using the userFilter property to limit access to members of the engineering group.

    "userFilter": "&(objectClass=user)(memberOf=cn=engineering,OU=Groups,OU=ad,DC=drem,DC=io)",
    

    Defining Groups

    The following examples show how to define groups.

    Example: Using groupDNs

    In the following example, a list of templates for group DNs are specified. The placeholder {0} is replaced with the group name entered by the user. Dremio attempts searching given groupDNs in the order they are specified.

    "groupDNs": ["cn={0},OU=engg,OU=test,OU=ad,DC=drem,DC=io"]
    

    note:

    In the DN-based approach, the groupAttributes property must not be specified.

    Example: Using groupAttributes

    In this example, the groupAttributes property is used to specify a list of baseDNs and group name IDs. These properties map LDAP group attributes to Dremio group attributes. The baseDNs, searchScope, id properties are required.

    "groupAttributes": {
        "baseDNs": ["dc=roles,dc=dremio,dc=com"],
        "searchScope": "SUB_TREE",
        "id": "CN"
     }
    

    note:

    In the attribute-based approach, groupDNs field must not be specified.

    Defining User-Group Relationships

    The relationship between users and groups can be defined with one of the following methods:

    • Group membership
    • Group lists

    Group Membership

    This method implements user entries in LDAP that list their group membership. (The user entries in LDAP are configured to list their group membership via the internal field memberOf.) See Sample Group Membership Configuration for a full example with the properties in context.

    To establish this user-group relationship:

    • Specify groupMembership property.
    • Specify (if applicable) the groupRecursive property.

    For example, if Dan is part of the BI group and the BI group is part of the engineering group, groupMembership property will contain only the BI group but the groupRecursive property will contain the engineering group.

    For example:

    "groupMembership": "memberOf",
    "groupRecursive": "transitive-memberOf",
    

    In addition, you can specify the "userGroupRelationship": "USER_ENTRY_LISTS_GROUPS" property-value, however, this property is optional since it is the default.

    Group Lists

    This method implements group entries in LDAP that lists users(by using the IDs of the users) that belong to that group . In the following sample, uid is the ID attribute that is used for the user entry and memberUid is the ID attribute that is used for the group entry.

    "userGroupRelationship": "GROUP_ENTRY_LISTS_USERS",
        "groupEntryListsUsers": {
            "userEntryUserIdAttribute: "uid",
            "groupEntryUserIdAttribute": "memberUid"
    },
    

    For example, Dan’s ID is 1234 and is represented by the attribute uid in Dan’s LDAP records. Dan is part of the BI group and the LDAP entry for group BI lists memberUid = 1234. This indicates that Dan is a valid member of the group.

    Encrypting the LDAP Bind Password

    When configuring Dremio, you might want to provide credentials to access third-party services. A common service that requires credential entry is the LDAP provider, which may request a password in order to bind Dremio to an LDAP external server for the purpose of obtaining user details during login. For customers with security standards and requirements, the use of password encryption offers a secure way to communicate key information with the LDAP service.

    This is accomplished using the CLI command dremio-admin encrypt. Upon entering the command, Dremio then prompts for the entry of a string for use as the secret. The output URI may then be copied and pasted directly to the Dremio configuration file.

    Example

    This example goes through the process of LDAP encryption using the bind password.

    To begin, you should perform the following command:

    bin/dremio-admin encrypt thisIsSecret
    

    Where thisIsSecret is the secret to be used for authentication purposes. Dremio then outputs a series of characters:

    secret:1.FxLevnDdoHx58x7VZmBpNExUiM76_u7XAXo1SJ8mCJxzeC1SirK2Jm5aBRR-h2_r8iypOAcRYSzH4uyP33Vg6Fh94bV6evuQ.wENZ7fgdJBw92wy4DiPhpJRzNP07wBaVpspv8KygjMfYV2en3YPFZw==
    

    You would then copy the entire output via ad.json bindPassword.

    Regarding schemes, you may set this to either env or file. For env scheme, the bindPassword could be env:ldap with the env variable set to export ldap <secret> where <secret> is the output. For the file scheme, the bindPassword could be set to file:///tmp/test.file where the file specified contains the output secret. For both of these methods, this only applies to the local node. If you are using a multi-coordinator configuration, you need to do this for each coordinator node. However, this method contains the raw secret in both the env scheme and file.

    Another scheme you may use is data, where the secret is in base64 format. You would use the same process above for establishing the secret, but with the bindPassword set to data:text/plain;base64,SGVsbG8sIFdvcmxkIQ==.

    Note:

    The data, env, and file schemes all do not have encryption capabilities. Only secret may encrypt.

    Note:

    Dremio still accepts the old style bin password format.

    Securing the Connection

    The LDAP connection can be secured by specifying either ANY_SSL or TRUSTED_SSL. The default, PLAIN, is an unencrypted connection.

    To set up TRUSTED_SSL mode, do the following:

    • Update ad.json with the connectionMode set to TRUSTED_SSL.
    • Update dremio.conf with javax.net.ssl settings for trustStore and trustStorePassword.
    // ad.json entry for TRUSTED_SSL mode
    "connectionMode": "TRUSTED_SSL",
    
    
    // dremio.conf entry for TRUSTED_SSL mode with a self-signed certificate**
    javax.net.ssl {
        trustStore: "<path/to/truststore/jks/file>",
        trustStorePassword: "trustStorePassword"
        }
    

    note:

    Unencrypted Connections: If you want an unencrypted connection, the connectionMode property is set to PLAIN: "connectionMode": "PLAIN",

    Sample Group List Configuration

    In the following example, the group list method is being implemented. You are defining the user-group relationship where the group entry lists the users that belong to that group).

    To establish this user-group relationship:

    • Set userGroupRelationship to GROUP_ENTRY_LISTS_USERS.
    • Specify the groupEntryListsUsers property and it’s sub-properties, userEntryUserIdAttribute and groupEntryUserIdAttribute.

    In the following example, uid is the ID attribute that is used for the user entry and memberUid is the ID attribute that is used for the group entry.

    {
        "connectionMode": "PLAIN",
        "servers": [
            {
                "hostname": "host_ip",
                "port": 389
            }
        ],
        "names": {
            "bindDN": "CN=admin,DC=drem,DC=io",
            "bindMethod": "UNAUTHENTICATED",
            "bindPassword": "admin",
            "baseDN": "dc=drem,dc=io",
            "userFilter": "&(objectClass=posixAccount)",
            "userAttributes": {
                "baseDNs": [
                    "OU=Users,OU=ldaptest,DC=drem,DC=io",
                ],
                "id": "uid",
                "firstname": "givenName",
                "lastname": "sn",
                "email": "mail"
            },
            "userGroupRelationship": "GROUP_ENTRY_LISTS_USERS",
            "groupEntryListsUsers": {
                "userEntryUserIdAttribute": "uid",
                "groupEntryUserIdAttribute": "memberUid"
            },
            "groupDNs": ["cn={0},OU=test,OU=ldaptest,DC=drem,DC=io",
                         "cn={0},OU=dev,OU=ldaptest,DC=drem,DC=io"],
            "groupFilter": "|(objectClass=posixGroup)(objectClass=sub)",
            "autoAdminFirstUser": false
        }
    }
    

    Sample Group Membership Configuration

    The following sample is a Microsoft AD configuration that illustrates the group membership method (the user entry lists the groups that the user is a member of).

    {
    	"connectionMode": "PLAIN",
    	"servers": [
    		{
    			"hostname": "<LDAP_HOST>",
    			"port": 389
    		}
    	],
    	"names": {
    		"bindDN": "CN=Admin,OU=Users,OU=ad,DC=drem,DC=io",
    		"bindPassword": "password",
    		"baseDN": "dc=dremio,dc=io",
    		"userFilter": "&(objectClass=user)(|(memberOf=CN=QA,OU=temps,OU=test,OU=ad,DC=drem,DC=io)(memberOf=CN=qa,OU=engg,OU=test,OU=ad,DC=drem,DC=io))",
    		"userAttributes": {
    			"baseDNs": [
    				"OU=test,OU=ad,DC=drem,DC=io"
    			],
    			"searchScope": "SUB_TREE",
    			"id": "sAMAccountName",
    			"firstname": "givenName",
    			"lastname": "sn",
    			"email": "mail"
    		},
    		"groupMembership": "memberOf",
    		"groupRecursive": "transitive-memberOf",
    		"groupDNs": ["cn={0},OU=engg,OU=test,OU=ad,DC=drem,DC=io"],
    		"groupFilter": "(objectClass=group)",
    		"autoAdminFirstUser": true
    	}
    }
    

    Granting Admin Privileges at Configuration Time

    By default, the first valid LDAP user to log in to Dremio is given the Admin role. This is done via the autoAdminFirstUser: true property in the ad.json file. The assignment of the first valid user to Admin occurs during initial login.

    Alternatively, you can specify a list of users and/or groups to be given the Admin role. This is valid only during initial login; it is used for boot-strapping only.

    warning:

    When you set autoAdminFirstUser to false, then you must specify users/groups in a bootstrap-admin-users.json file. Otherwise, an administrator won’t be a specified.

    To specify users/groups as administrators up-front, during initial login:

    1. In the ad.json file, set autoAdminFirstUser to false.

      autoAdminFirstUser: false
      
    2. Create a file called bootstrap-admin-users.json under the Dremio configuration directory and add users and groups property information.

    For example:

        {
        users: ["joe", "bob"],
        groups: ["marketers", "sales wizards"]
        }
    

    note:

    The users/groups specified in the bootstrap-admin-users.json file are used only during initial login and only when autoAdminFirstUser is set to false.
    To add other Users/Groups to the Admin role after the initial login, use the Dremio UI.

    Deleting Users

    note:

    When deleting users from LDAP, ensure that all Personal Access Tokens (PATs) are also deleted.