Versions 2.1.12 - 4.8

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');;

2. 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=="/>

3. 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"/>
			<module-option name="displayUserName" value="cn"/>
		</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

Parameter	Description
`java.naming.provider.url`	Hostname or IP address of directory server. Can use `ldaps://` instead of `ldap://` for secure connections
`java.naming.security.principal`	User account that has permissions to read users and groups from the directory
`java.naming.security.credentials`	Credentials of the user account above
`bindDN`	Same as `java.naming.security.principal`. For technical reasons, the same credentials need to be supplied twice
`bindCredential`	Same as `java.naming.security.credentials`
`baseCtxDN`	The container where to start searching for roles
`baseFilter`	When 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})`), userPrincipalName (`(userPrincipalName={0}@mydomain.local)`), or sAMAccountName (`(sAMAccountName={0})`)
`searchFilterGroups`	Optional 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
`searchFilterUsers`	Optional 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
`rolesCtxDN`	The container where to start searching for roles
`roleFilter`	Filter to obtain groups a user belongs to. The users' `userDN` can be accessed as `{1}`
`roleAttributeIsDN`	Set 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
`roleRecursion`	The depth to search for a role in the given role context. Disabled if set to `0`
`allowEmptyPasswords`	Set to `FALSE` if logins without a password should be rejected
`defaultAdminGroup`	Name of the Active Directory role to be granted administrative rights on the CData Virtuality Server
`displayUserName`	Defines LDAP attribute that is used as CData Virtuality "`userName"`. Defaults to "`displayName"` LDAP attribute value. Must be the same attribute as in "`baseFilter"`. "`has"` and "`stripDomain"` functions could be used in the value of this parameter. "`displayUserName"` could be skipped if all users have "`displayName"` LDAP attribute set and "`baseFilter"` has `cn={0}` or `sAMAccountName={0}` value and "`displayName"` for all users equals to "`cn"` or "`sAMAccountName".` Examples: Use <module-option name="displayUserName" value="has('userPrincipalName') ? stripDomain(userPrincipalName) : cn"/> when "baseFilter" is set to `<module-option name="baseFilter" value="(userPrincipalName={0}@mydomain.local)"/>`. "`userName"` is equal to "`userPrincipalName" w`ithout the domain part if the user has "`userPrincipalName"` attribute set and "`cn"` if not. Use `<module-option name="displayUserName" value="cn"/>` if "baseFilter" is `<module-option name="baseFilter" value="CN={0}"/>`. "`userName"` is "`cn" in this case.`

Authorization and Authentication Realms Stacking

Login modules can be combined to authenticate and authorize users, and to load users and roles. For example, you can use LDAP authentication while managing roles and permissions internally. Follow these steps:

Start the server as usual and log in with admin/admin.

Create internal user accounts matching the usernames of LDAP users. Assign them roles and permissions, but use placeholder passwords.

SQL

-- Create a user with admin role 
call SYSADMIN.addUser("name" => 'ad_user1', "pwd" => '123', "role_name" => 'admin-role') ;; 
-- Create a user wiht connect role 
call SYSADMIN.addUser("name" => 'ad_user2', "pwd" => '123', "role_name" => 'connect-dv-role') ;;

Stop the server and update the configuration as follows:

CODE

<security-domain name="dv-security" cache-type="default">
	<authentication>
		<login-module code="com.datavirtuality.dv.core.teiid.users.DVLoginModule" flag="optional" module="com.datavirtuality.dv"/>
		<login-module code="com.datavirtuality.dv.core.teiid.users.ldap.ext.DVLdapExtLoginModule" flag="required" module="com.datavirtuality.dv">
			<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="displayUserName" value="cn"/>
			<module-option name="allowEmptyPasswords" value="false"/>
			<module-option name="password-stacking" value="useFirstPass"/> 
		</login-module>
		<login-module code="com.datavirtuality.dv.core.teiid.users.DVLoginModule" flag="required" module="com.datavirtuality.dv">
			<module-option name="password-stacking" value="useFirstPass"/> 
		</login-module>
	</authentication>
</security-domain>

Restart the server.
Log in using the usernames created in step 2 to access the system.

displayUserName parameter default value behaviour has been changed in v4.2:

Previously:

If displayUserName was not specified in the dvserver-standalone.xml file, the system defaulted to using the user's displayName LDAP attribute value as displayUserName. If displayName was not available, the distinguishedName LDAP attribute value was used instead, as every LDAP user has a distinguishedName;
Similarly, if displayUserName was specified but some LDAP users lacked the used LDAP attribute, the system defaulted to the distinguishedName LDAP attribute value.

Since v4.2:

This update removes the automatic use of distinguishedName LDAP attribute in cases where the user does not have a displayName, or the attribute specified in displayUserName is missing. Now, an error will occur when reading CData Virtuality users if displayUserName is not specified in the config, or if it is set to an attribute that some users do not have (e.g. cn). Therefore, it is crucial to specify displayUserName accurately.

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

BASH

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