Introduction

With the Gravity LDAP integration it is possible to authenticate a Gravity user against an LDAP server for example Active Directory or OpenLDAP. LDAP integration factors have been kept flexible so that any LDAP implementation can be supported with regards to user authentication and importing user attributes (first, last name, email address etc.)

A user can be bound to LDAP authentication in 3 ways.

By defining a new user and setting the choice of authenticator to LDAP.
Importing users by way of CSV file with the Import Users… wizard, where the choice of authenticator is LDAP.
By updating an exsiting user to use the LDAP authenticator (edit user from User Admin perspective).

Once a user is assigned to the LDAP authenticator, user authentication will no longer be handled by the Gravity internal authenticator but by the LDAP authenticator which delegates the actual authentication to the configured LDAP server.

For Gravity to authenticate or retrieve user data it is necessary to know how to find the user in the LDAP tree. For accessing user information it must be known in advance how the LDAP tree is to be searched. This is where the query filter plays an important role as the query filter effectively specifies the conditions that must be met for a user to be included in the result(s) of the query. The Gravity LDAP configuration provides a set of ready-made templates of which each template is tailored for a specific LDAP implementation. The provider templates will take out most of the guesswork involved in defining the correct query filter for your LDAP implementation.

Licensing

The LDAP integration is a licensed module. The Gravity base license will contain information pertaining to the availability of the LDAP integration module. The LDAP integration license is the number of Gravity users allowed to use the LDAP integration for log-in purposes. The number should be equal to the number of Gravity users that will login to Gravity by way of LDAP authentication. If the number of LDAP enabled users exceeds the LDAP integration license count then an email message will be sent indicating that the base license does not suffice with regards to the LDAP integration license setting.

Setting up the LDAP configuration

The Gravity configuration form consists of 2 parts the first part, LDAP connection settings, pertains to how to physically connect to the LDAP server. The second part, LDAP Search and Mapping Attributes, pertains to what is needed to find the user and get user attribute values into Gravity.

The form has an option to test the configuration by pressing the button in the top right corner of the form. Note well that testing the connection will only make sense if all required configuration fields have been set with a satisfactory value.

Protocol

Set the connection type required for LDAP server communication. This can be either ‘ldap’ or ‘ldaps’, default is ‘ldap’. If ‘ldaps’ is chosen then make sure the setup of SSL certificates has already taken place for this client and the Gravity server. If 'ldaps' is chosen then make sure the setup of SSL certificates has already taken place for the client on which the LDAP connection is being tested and the Gravity server, see ‘Setting up a secure LDAP connection’.

Server Host

LDAP server address, either an IP address or a host name. The IP address may be either an IPv4 or IPv6 type address. Note that if the Gravity client or server is configured with the java property -Djava.net.preferIPv4Stack=true then it will not be possible to use an IPv6 address to communicate with the LDAP server, the following error will occur: "... Protocol family unavailable".

Server Port

LDAP Server port, default port is 339. If running against an Active Directory you can optionally use port 3268, which directs LDAP queries to the global catalog. A user look-up in the global directory will be in general faster than a query using a non-optimized search filter or search DN. Also if Gravity users are spread over multiple domains then you will need to make use of the global catalog to locate a user.

Start TLS

This option is only available if the ‘ldap’ protocol has been selected. This option allows the start of a secure connection over an initially unsecure LDAP port, for example port 389. The possibility to run a secure connection over the default non secure port is often a configuration available on Active Directory servers. If this option is selected then make sure the setup of SSL certificates has already taken place for the client on which the LDAP connection is being tested and the Gravity server, see ‘Setting up a secure LDAP connection’.

Domain

The domain or base distinguished name defines the root for the look up of a user in the LDAP directory tree. The domain must be supplied in a dotted format for example 'company.com'. If you know the LDAP name, for example as 'dc=company,dc=com' then transform this to 'company.com'. The domain name will also be used to substitute the query filter key values %domain% and %domaintodc%, where %domain% is the original dotted value of the domain name and %domantodc% the distinguished domain name (for example dc=company, dc=com).

Bind User DN

Is the (administrative) user that will be used to look-up and authenticate an LDAP user. The supplied user must be defined as a distinguished name, for example 'cn=read-only-admin,cn=users,dc=company,dc=com or in the case of Active Directory a user principal name (UPN) for example administrator@company.com administrator@company.com or DOMAIN\Administrator. Gravity will only read from an LDAP server, the specified bind user should at least have read access on the LDAP server.

Bind Password

The bind user’s password.

For example a configuration targeted towards an Active Directory will look something like the configuration below.

Example connection configuration:

Defining the LDAP user mappings

Provider Template

The Provider template supplies reasonable values for the user-dn, query filter and attributes mapping for a number of well-known LDAP implementations. These values can be customized to comply with the target LDAP schema and directory tree structure.

Note that there are 2 templates for Windows, one to bind/query a user based on the SAM account name and one to bind/query a user based on the user principal name (UPN). With the bind on SAM account name the user is expected to login with his or her pre Windows 2000 login account name.

User DN

User Distinguished Name sets the location (LDAP tree path) from which to search for a user, this is a comma delimited list of 1 or more containers (CN=) and or organizational units (OU=), for example 'CN=Users, OU=Main Office'. Although setting a User DN is optional, in some cases a user DN can significantly speed up LDAP query times. Note that when testing the connection and you receive the message 'unable to retreive user ..., failed to locate user' then most likely the User DN is incorrect. Either remove the User DN or determine the correct container the users are located in and apply this to User DN.

Prefetch User DN

Prefetch the user's fully qualified LDAP name and use this as overriding input for the User DN. If not required do not set this option as it will incur a slight performance impact on user login. If this option is selected then any value set in the User DN field will be ignored. Use this option only if the 'User DN' cannot be succesfully determined. With this option enabled the user will first be retrieved (relying on the default LDAP server's search path to find the user) then the user will be authenticated using the discovered fully qualified user name.

User Query Filter

The purpose of the query filter is to restrict the LDAP lookup to a single user, i.e. the user that will log into Gravity. The query filter will be different per LDAP template but can be adapted to meet the requirements of the target LDAP implementation. The query filter defines a comma separated list of object classes and types used to bind to a user (the search user). The substitution key %user% is a placeholder for the user to be authenticated (i.e. the user logging into Gravity), %domain% for the, already configured, dotted domain name and %domaintodc% for a dc=... type domain name (for example ‘dc=corp,dc=com’). To add a custom filter to the query, append the query filter with a string starting with and ampersand and the query enclosed in brackets, &(...). Below is an example for Active Directory where the rule applies that the user must also be a member of the ‘developers’ group:

objectCategory=person, objectClass=user, sAMAccountName=%user% &(memberOf=cn=developers,%domaintodc%)

Note that if a filter is not defined properly then the outcome of a user search can be the javax.naming.PartialResultException exception. It could be that a loosely defined filter is forcing the query to follow referrals (which by default is enabled), which in the end does not resolve the query but makes the connection time-out and return the PartialExceptionResult exception.

LDAP attribute mappings

LDAP attribute mapping is used to map LDAP user fields to Gravity user fields. These mappings will be used when a new User is added as a Gravity user, for example when the user is created with the LDAP authenticator or an LDAP import is run. Default values are provided based on the chosen LDAP provider template but these values can be overridden if there is a mismatch.

User ID

Maps the LDAP user name (log-in name) to the Gravity user name.

First Name

Maps the LDAP first name (given name) to the Gravity first name.

Last Name

Maps the LDAP last name (surname) to the Gravity last name.

Email Address

Maps the LDAP email address to the Gravity email address.

Country

Maps the LDAP country to the Gravity country.

Example LDAP user settings:

LDAP group assign

With the LDAP group assign it is possible to automatically assign a Gravity user to a Gravity group based on th existence of a user's membership to an LDAP group. In the field 'LDAP group' the LDAP group is set to which a user must be member of for the assignment to take place based on the selected 'Gravity group'. Group assign will occur when a Gravity-LDAP user is synchronized against the configured LDAP directory. To have a group assigned during login then the option 'Sync on Authenticate' must be enabled.

Example LDAP group assign:

LDAP synchronize settings

As of version 3 of Gravity the LDAP integration also includes functionality to synchronize a Gravity user with its LDAP counterpart. The synchronization process will detect disabled, deleted and renamed users as will as detect changes in user fields, such as the email address. There are 2 settings that are key to a fully functional synchronization; 'UUID Entry' and 'UUID Query Filter'. Default values for these fields are provided based on the chosen LDAP provider template but these values can be overridden if required. The 2 settings help Gravity retrieve and use an LDAP user's UUID (globally unique LDAP identifier) which can be used to detect a user name change (i.e. a user id rename). As part of the synchronize process, Gravity will add the LDAP UUID to the Gravity user if the Gravity UUID has not yet been set (by default creating a user for LDAP from the User Admin UI will also set the LDAP UUID). Without the availability of an UUID a rename cannot be determined. This is not a bad thing but it is more work for the Gravity administrator as he will have to manually update the changed user name. Synchronization can be run automatically by the Gravity server (see LDAP Sync. Interval) or manually initiated from the Gravity UI client. On the UI client an LDAP synchronization can be initiated by selecting Gravity -> 'Synchronize Users with LDAP' from the top menu bar. This option can only be run if you are logged in as the user 'admin'.

UUID Entry

Refers to the LDAP attribute that defines the UUID for an LDAP entry. The value for this field is LDAP implementation specific. This is an important attribute for synchronization and allows Gravity to retrieve the UUID of the Gravity-LDAP user. The UUID is used to detect a user rename. A default value is presented by the selected LDAP template, if required the default can be overridden.

UUID Query Filter

Defines the concise LDAP query filter to be used to retrieve a user by its UUID. The default value for this field is '(&(%entryuuid%=%uuid%))', where substitution key %uuid% is a placeholder for the user's prefetched UUID (automatically provided by Gravity) and %entryuuid% is a placeholder for the previously defined 'UUID Entry'. This query filter will be used when synchronizing Gravity users with LDAP users. Below is a list of well known LDAP UUID attribute field names:

OpenLDAP and ldapv3 (RFC 4530)	entryGUID
Active Directory		objectGUID
Novell  			GUID
Oracle Internet Directory 	orclGUID
Oracle Virtual Directory  	orclGUID
WebLogic  			orclGUID
SunOne/iPlanet			nsUniqueId

Sync on Authenticate

Synchronize the Gravity user with information retrieved during the user login (authentication). This ensures that Gravity uses up to date LDAP user info (e-mail address, first name etc ..) but may incur a slight performance impact on the user login due to an extra roundtrip to retrieve user information from LDAP.

LDAP Sync. Interval

Synchronization can be set to run automatically on the Gravity server. By default the synchronization process is not scheduled to run. To enable the automatic LDAP synchronization you must update the 'LDAP Sync. Interval' field with a value between 10 minutes and 1440 minutes (24 hours). A sensible value will lie somewhere between 45 and 60 minutes. If you have a very large user base (thousands of Gravity users) then you might need to schedule to only once or twice a day by (720-1440 minutes) as the synchronization process can be long running. Note that on server startup a synchronization will run within a few minutes as no previous synchronization process has been logged since server startup.To disable automatic synchronization set the interval value to 0. A synchronization process can also be initiated from the Gravity Admin Client by selecting the top level Gravity menu option: 'Synchronize Users with LDAP'. Selecting this option will start a background job of which the result can be viewed in the Gravity log (which is automatically openened for viewing).

Example LDAP sync settings:

Testing the LDAP configuration

Once the LDAP configuration has been set with values correct for the target LDAP implemenation, the configuration can be tested by pressing the LDAP test button . But before pressing the button the Test user and password will be needed to bet set with the credentials of an existing LDAP user.

On a successful run of the configuration the following response will be returned:

A failed test will look something like the following:

unable to retrieve user

When testing the connection and you receive for example the message 'unable to retrieve user 'janice', failed to locate user' and you a very sure the user exists then you might need to change the User DN (distinguished name). First retry the lookup by removing the User DN, if this does not work or the User DN is already empty then you will have to consult your LDAP admininstrator to find out which container the users are located in and apply this container as the User DN value.

Also note that when testing the configuration with a bind user and test user that LDAP can return an error message indicating that the test user is incorrect. This may not always be the case as it can very well be that the bind user is incorrect. To confirm which user is causing an error set the bind user as the test user to verify that at least the bind user is correct.

We assume of course that testing the configuration will return a positive response but this is not always the case. There are a lot of reasons why a negative response can be returned, invalid binding credentials, inappropriate User DN or possibly an incorrect query filter. Finding the correct values to be used for an LDAP implementation is often a case of trial and error and where the input of the LDAP administrator can be instrumental in solving any LDAP connect or user binding issues.

Troubleshooting

General

If an error occurs during the testing of the LDAP integration then it might be helpful to bring the Gravity console log to the foreground. Errors logged will be more detailed than the message displayed in the Mail configuration view, see Gravity Log viewer

LDAP error codes

LDAP error code 49 will be returned on an authentication exception, for example:

[LDAP: error code 49 - 80090308: LdapErr: DSID-0C0903A9, comment: AcceptSecurityContext error, data 52e, v1db0]

Then the cause of the error is most likely an invalid bind or test/search user credential. Below are some well known data codes returned by an authentication exception (for example 'data 52e' in the exception above) :

Data Code	Description
525	User not found
52e	Invalid credentials
530	Not permitted to logon at this time
531	Not permitted to logon at this workstation
532	Password expired
533	Account disabled
701	Account expired
773	User must reset password
775	User account locked

LDAP error code 32 will be returned if the target object cannot be found, for example:

[LDAP: error code 32 - 0000208D: NameErr: DSID-03100238, problem 2001 (NO_OBJECT), data 0, best match of: ...]

Error	Data	Description
32	0	User DN not found

Error code 39 is usually resolved by entering a correct User DN (this may take some experimentation). Depending on the LDAP setup, simplyfying or leaving the User DN empty may also resolve the situation.

Known issues

... o.s.l.c.LdapTemplate: PartialResultException encountered and ignored
javax.naming.PartialResultException: null

If you are seeing this error and you're LDAP server is Microsoft Active Directory then try changing the server port from 389 to 3268 (for LDAPS 636 to 3269).

This error is only a warning and will occur when the LDAP server tries to pursue a referral but fails (which can be the case when using AD Global Catalog). This error does not influence the outcome of an LDAP lookup as the exception is ignored, but the underlying process still logs the exception and stack-trace.

gLDAPtry

With the Gravity OSGi console command gLDAPtry you can enter an LDAP configuration by hand to track down an error when testing an LDAP configuration from the Gravity UI or server.

To start the Gravity OSGi console from the UI, run telnet (or putty) with localhost and port 45052. For the Gravity server you have to start a telnet session on the server use localhost and port 45051. Note: when you have finished testing then leave the console using the command 'disconnect', under no circumstances use the command 'exit' as this will stop the Gravity instance.

The syntax for the gldaptry command is as follows:

gldaptry [HELP|AD|NOAD] [ldapUrl] [bindUser] [bindPassword] [searchDN] [searchFilter | ""] [searchUser] [userPassword | ""]

The first parameter is AD if accessing an active directory LDAP server or NOAD if not.

Note that when using the console LDAP tooling, passwords will be explicitly output to the console so that possible typos in a password can be caught. The passwords are not logged to file only output to the OSGi console.

If you do not provide a password for the search-user then only the user look up will take place and not the user authentication.

Example gLDAPtry command with output as displayed in the Gravity console:

osgi> gldaptry ad ldap://win01:389 ldapadmin@corp.remainsoftware.com secretpassword dc=corp,dc=remainsoftware,dc=com "" userx

ldap try; url: ldap://win01:389, bind-user: ldapadmin@corp.remainsoftware.com, search-base: 'dc=corp,dc=remainsoftware,dc=com', search-filter: , search-user: 'userx'

2016-07-07 08:55:31,847 INFO c.r.g.u.l.LDAPTry: acquiring a dir-context for provider-url: 'ldap://win01:389', bind-user:

'ldapadmin@corp.remainsoftware.com'

2016-07-07 08:55:31,863 INFO c.r.g.u.l.LDAPTry: successfully obtained dir-context for provider-url: 'ldap://win01:389', bind-user: