Skip to main content
Skip table of contents

LDAP Authentication

You are looking at an older version of the documentation. The latest version is found here.

With the LDAP authentication mechanism, users (and passwords) and roles (or groups) are loaded from an Active Directory or LDAP domain.

Encrypting Credentials in the Configuration

To encode credentials defined in dvserver-standalone.xml, do the following:

  1. Encrypt the password using the UTILS.encrypt function:
SQL
SELECT UTILS.encrypt('password');;
  1. Set encoded values for java.naming.security.credentials and bindCredential:
SQL
<module-option name="java.naming.security.credentials" value="ZjyMp28QJE0D47Rld0LOFw=="/>
<module-option name="bindCredential" value="ZjyMp28QJE0D47Rld0LOFw=="/>
  1. Set dv.encrypted.credentials to TRUE:
SQL
<module-option name="dv.encrypted.credentials" value="true"/>

Configuration

To use authentication based on LDAP, you need to configure the <authentication> section in the current dv-security security-domain defined in dvserver-standalone.xml.

Here is an example configuration:

BASH
<security-domain name="dv-security" cache-type="default">
	<authentication>
		<login-module code="com.datavirtuality.dv.core.teiid.users.ldap.ext.DVLdapExtLoginModule" module="com.datavirtuality.dv" flag="required">
			<module-option name="java.naming.factory.initial" value="com.sun.jndi.ldap.LdapCtxFactory"/>
			<module-option name="java.naming.provider.url" value="ldap://192.168.0.68/"/>
			<module-option name="java.naming.security.authentication" value="simple"/>
			<module-option name="java.naming.security.principal" value="CN=Administrator,CN=Users,DC=mydomain,DC=local"/>
			<module-option name="java.naming.security.credentials" value="Password123"/>
			<module-option name="bindDN" value="CN=Administrator,CN=Users,DC=mydomain,DC=local"/>
			<module-option name="bindCredential" value="Password123"/>
			<module-option name="baseCtxDN" value="DC=mydomain,DC=local"/>
			<module-option name="baseFilter" value="(CN={0})"/>
			<module-option name="rolesCtxDN" value="OU=dvroles,DC=mydomain,DC=local"/>
			<module-option name="roleFilter" value="(member={1})"/>
			<module-option name="roleAttributeIsDN" value="false"/>
			<module-option name="roleAttributeID" value="cn"/>
			<module-option name="roleRecursion" value="5"/>
            <module-option name="searchFilterUsers" value="(memberof=cn=DataVirtuality,OU=Users,DC=mydomain,DC=local)"/>
            <module-option name="searchFilterGroups" value="CN=DataVirtuality"/>
			<module-option name="allowEmptyPasswords" value="false"/>
			<module-option name="defaultAdminGroup" value="dv-admins"/>
		</login-module>	
	</authentication>
</security-domain>


This code replaces the following one in dvserver-standalone.xml:

BASH
<security-domain name="dv-security" cache-type="default">
	<authentication>
		<login-module code="com.datavirtuality.dv.core.teiid.users.DVLoginModule" flag="required" module="com.datavirtuality.dv"/>
	</authentication>
</security-domain>

The parameters should be configured as follows:

To view the full table, click the expand button in its top right corner


ParameterDescription
java.naming.provider.url

Hostname or IP address of directory server. Can use ldaps://  instead of ldap:// for secure connections

java.naming.security.principalUser account that has permissions to read users and groups from the directory
java.naming.security.credentialsCredentials of the user account above
bindDNSame as java.naming.security.principal. For technical reasons, the same credentials need to be supplied twice
bindCredentialSame as java.naming.security.credentials
baseCtxDNThe container where to start searching for roles
baseFilterWhen a user logs in, this filter locates the user inside the directory based on the provided username passed as {0}. Different types of filters are possible, such as using the CN ((cn={0})), userPrincipleName ((userPrincipalName={0}@mydomain.local)) or the sAMAccountName ((sAMAccountName={0}))
searchFilterGroupsOptional filter to restrict the groups that the login module will retrieve. By default, all groups under rolesCtxDN are loaded as (&(&(objectClass=group))). Specify a more restrictive filter if you want only a subset of groups to be loaded
searchFilterUsersOptional filter to restrict the users that the login module will retrieve. By default, all users under baseCtxDN  are loaded as (&(&(objectClass=user))). Specify a more restrictive filter if you want only a subset of users to be loaded
rolesCtxDNThe container where to start searching for roles
roleFilterFilter to obtain groups a user belongs to. The users' userDN can be accessed as {1}
roleAttributeIsDNSet to FALSE if the user's role attribute doesn't contain the fully distinguished name of the role object
roleAttributeID If roleAttributeIsDN  is FALSE, specifies the name of the role attribute which corresponds to the name of the role
roleRecursionThe depth to search for a role in the given role context. Disabled if set to 0
allowEmptyPasswordsSet to FALSE if logins without a password should be rejected
defaultAdminGroupName of the Active Directory role to be granted administrative rights on the Data Virtuality Server

Сonnecting to the Active Directory server over the TLS protocol requires the following parameter:

BASH
<module-option name="java.naming.security.protocol" value="ssl"/>

Please note that the number of domain users visible in the Data Virtuality Studio is limited by the ADWS MaxGroupOrMemberEntries setting and the Active Directory LDAP default MaxPageSize setting. Please refer to the ADWS and LDAP documentation for more information.

defaultAdminGroup property is available since v2.4.2

Users and Roles (or Groups)

Users and Roles lists are loaded from Active Directory. Lists are loaded during the first call to the relevant tables after the server start or restart (SYSADMIN.Users and SYSADMIN.Roles) and cached on the server. New users are able to log in to Data Virtuality without refreshing the cache. However, to query new users and roles, the cache must be refreshed using the SYSADMIN.refreshLdapUserCache procedure.

CODE
CALL "SYSADMIN.refreshLdapUserCache"();;

When the Data Virtuality Server is configured to read users, passwords, and roles from an LDAP domain, some features related to these objects can no longer be used in the Data Virtuality Server. In particular, handling users and roles from the Data Virtuality Server is impossible: they should be managed directly in LDAP.

For this reason, the following stored procedures are not available anymore:

  • SYSADMIN.addRole()
  • SYSADMIN.renameRole()
  • SYSADMIN.deleteRole()
  • SYSADMIN.importUser()
  • SYSADMIN.addUser()
  • SYSADMIN.renameUser()
  • SYSADMIN.deleteUser()
  • SYSADMIN.changeUserPwd()
  • SYSADMIN.getEncryptedUserPwd()
  • SYSADMIN.addUserRole()
  • SYSADMIN.deleteUserRole()

If they are called, this error message is shown:

UnsupportedLdapUsersHandlerOperationException. This operation is not supported when LDAP is used for the authentication.

refreshLdapUserCache procedure is available since v2.4.14

Permissions

Permissions are handled and stored locally in dvconfig, and they can be set using the SYSADMIN.setPermissions() system procedure as with the default dvconfig-based authentication mechanism.

Special Permission to Create Temporary Tables

With the default Data Virtuality Server mechanism, the special permission to create temporary tables is normally assigned to a role, and it is set when a new role is created via SYSADMIN.addRole().

Since the Data Virtuality Server with LDAP authentication mechanism cannot handle roles, a procedure to grant or revoke that permission is also provided.

CODE
SYSADMIN.setAllowCreateTempTables(IN role_name string NOT NULL, IN allow boolean NOT NULL)

This procedure can be used with both authentication mechanisms and will grant/deny the appropriate permission to the role.

The main difference (but this is only a technical detail) is that if a dvconfig-based authentication is used, the special permission is set to the role and stored in the dv_roles table, as usual; if LDAP is configured for authenticating users, the special permission is stored in a new and appropriate table called dv_ldap_role_props.

Creating an Administrative Role

This section applies if your version of the Data Virtuality Server is 2.4.1 or older.

LDAP authentication does not come with default roles compared to the Data Virtuality login mode. To access the Data Virtuality Server, one group from the directory has to be made the administrative group.

To do this, one needs a group in the directory within the search scope of the configured LDAP authentication module from the Data Virtuality Server.

Once this is done, a connection to the configuration database has to be made, and a manual entry has to be performed within one of the tables.

Use the command below and replace the timestamps with the current date and time and the role name with the group's name in the directory.

Add admin group

SQL
INSERT INTO dvconfig.dv__ldap_permissions VALUES (1, '2018-02-02 09:00:27.37', 'system', '2018-02-02 09:00:27.37', 'system','',false, '',1, 'CRUDEAL','*', '3389dae361af79b04c9c8e7057f60cc6',1,'custom-admin-role');;

Adding a Role with Minimal Permissions

Perform the following steps to create a role with minimum permissions for connecting to the Data Virtuality Server. You might not want to have all users granted admin rights.

1. Create a new group in your directory. Ensure that it is within the search scope of the configuration of the login module.

2. If necessary, create a user that shall not be an administrator.

3. Assign the user to the group. Double-check (see the screenshot):


4. Connect to the Data Virtuality Server as an administrator and go to User Management in the Studio. Check that the Server has recognized the users, roles and assignments.
If not, look at the login module configuration and the directory structure. The screenshot depicts the case where everything was correctly read from the directory.

5. Assign the role all permissions from the screenshot underneath, except the one for SYSADMIN.changeUserPwd:

You can use the script below to speed things up. Just replace custom-connect-role by your role name:

SQL
BEGIN
	DECLARE string roleName='custom-connect-role';
	CALL SYSADMIN.setPermissions("role_name" => roleName, "resourceName" => 'SYSADMIN', "permissions" => 'R') ;  
    CALL SYSADMIN.setPermissions("role_name" => roleName, "resourceName" => 'SYSADMIN.getInstalledLicense', "permissions" => 'RE') ;
	CALL SYSADMIN.setPermissions("role_name" => roleName, "resourceName" => 'SYSADMIN.getServerVersion', "permissions" => 'RE') ;
	CALL SYSADMIN.setPermissions("role_name" => roleName, "resourceName" => 'SYSADMIN.getServerBuildInfo', "permissions" => 'RE') ;
	CALL SYSADMIN.setPermissions("role_name" => roleName, "resourceName" => 'SYSADMIN.getCurrentDWH', "permissions" => 'RE') ;
	CALL SYSADMIN.setPermissions("role_name" => roleName, "resourceName" => 'SYSADMIN.refreshDataSource', "permissions" => 'RE') ;
	CALL SYSADMIN.setPermissions("role_name" => roleName, "resourceName" => 'SYSADMIN.refreshAllDataSources', "permissions" => 'RE') ;
    CALL SYSADMIN.setPermissions("role_name" => roleName, "resourceName" => 'SYSADMIN.getDefaultOptionValue', "permissions" => 'RE') ;
    CALL SYSADMIN.setPermissions("role_name" => roleName, "resourceName" => 'SYSADMIN.getUserProperty', "permissions" => 'RE') ;
    CALL SYSADMIN.setPermissions("role_name" => roleName, "resourceName" => 'SYSADMIN.getDataCatalogAttribute', "permissions" => 'RE') ;
	CALL SYSADMIN.setPermissions("role_name" => roleName, "resourceName" => 'INFORMATION_SCHEMA', "permissions" => 'RE') ;
	CALL SYSADMIN.setPermissions("role_name" => roleName, "resourceName" => 'SYSLOG', "permissions" => 'R') ;
END ;;

All users that belong to this group in your directory will now be able to connect.

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.