Use LDAP to create and lookup users
- 1 Summary
- 2 LDAP Server configuration
- 3 JEMH configuration
- 4 LDAP validation errors
- 5 Example of basic user lookup
- 6 Example of Alternative ID lookup
- 7 Example of unknown Alternative ID lookup
- 8 Distribution list expansion
- 9 Query support
- 10 Related articles
Summary
LDAP is a protocol that many directories support, such as Apache Directory Server, OpenLDAP, or Microsoft Active Directory. JEMH can make use of LDAP to locate matches on email addresses, in order to 'pick' a centrally defined userid (other than the email address), thereby auto-provision users in a consistent manner.
Any LDAP server should work. Testing during development of the feature was performed on:
Apache Directory Server
Microsoft Active Directory
LDAP Server configuration
The following screenshots show example connection set up for connecting directories using the Apache Directory Studio plugin for Eclipse and Active Directory.
Apache Directory |
|---|
  |
Active Directory |
|---|
Each directory has a different flavour of attribute naming for its record entries. Whatever it is for your LDAP server, you need to reflect it in the JEMH LDAP configuration.
JEMH configuration
LDAP settings
As LDAP instances are likely to be static, they are not defined at a Profile level, there is a new LDAP Configuration Tab. Once an LDAP configuration has been entered it self-validates on viewing. The new UI provides options to create a blank LDAP configuration or start from a known working example for tested directories, these should allow a good starting point for your configuration if using those directories.
If you use a different directory, I will happily accept XML exports of your configuration for future inclusion in JEMH!
New LDAP Screen, concise summary | Expanded LDAP entry |
|---|---|
|
|
Editing LDAP configuration
User credential Encryption Since 4.1.23
User credentials (i.e. username and password) are now encrypted at REST for storage in the Database. Upgrading from a version before 4.1.23 to version 4.1.23 and above will result in all LDAP configurations being automatically updated to use encrypted user credentials. XML Exports of LDAP configurations will no longer export user credentials as plain text and any imports of an XML LDAP configuration will now require the re-validation of User credentials when the XML config is imported.
Using Multiple Configurations
Just select them:
Sort Order (when using Multiple LDAP configs in a Profile)
The Sort Order (set within the LDAP config itself) affects the lookup sequence when used in a Profile, highest values sort highest, eg in a profile, here ‘10’ will be tested first, when a users is found no further attempts to locate are made:
LDAP fields
Field | Example value |
|---|---|
Object Filter | (initials=J) |
Object Class | user |
LDAP filter makeup
FYI, the final LDAP filter involved is built up from information provided as follows (actual values provided are in bold), %uid% would be the userId to lookup.
Search Base | LDAP Filter |
|---|---|
additionalUserDN,baseDN | (&(objectClass=objectClass)(objectFilter)(userNameAttribute=%uid%)) |
Additional User DN
The Additional User DN is an additional naming component that can be added. This allows a Base DN to be defined as 'root', with Users existing in a specific sub-location, that may differ from Groups (not yet implemented). The examples above show this configured for both Active Directory and ApacheDS. Valid BaseDN values could of course be prefixed with the content of this field.
Additional Params
Configuration defined through the UI may not be applicable or 'perfect' for every LDAP environment, for this, the Additional Params allows key=value properties to be defined. You would use this if for example, you were running on a JRE that isn't Oracle as JEMH LDAP support makes use of Oracle specific com.sun..... properties for things such as timeouts).
User creation settings
Set the User > Create users checkbox needs to be set
Set the User > Create User ID from field needs to be set to Alternate
Set the User > Alternate UserID lookup Mech to be LDAP
Set the User > Selected LDAP Config to be the LDAP configuration required
After which your configuration should look something like:
Editing | After Saving |
|---|---|
Note that there is an option to stop validation-before-saving, enabling quick entry of all the fields then per-field fixes. The intention is to stop arbitrary changes from breaking the configuration.
LDAP validation errors
When saving, the LDAP configuration is validated and the Test Lookup Username is looked for. Failures look like:
Validation errors can be cryptic, careful reading of the above would indicate that the 'ou=systemx' which is not correct.
Example of basic user lookup
Using Active Directory, the following email sender andy@javahollic.local relates to the primary mail address of user andy in Exchange.
MIME-Version: 1.0
Received: by 10.223.112.12 with HTTP; Sat, 18 Jun 2011 22:42:26 -0700 (PDT)
Date: Sun, 19 Jun 2011 17:42:26 +1200
Message-ID: <BANLkTinB1mfSh+GwOXGNWoL4SyDvOpdBoQ@mail.gmail.com>
Subject: This is a starting email template, update as required
From: "Andy Brook" <andy@javahollic.local>
To: test@localhost
Content-Type: text/plain; charset=UTF-8
This is from a remote user with a registered LDAP email address
The result of running this testcase is:
JEMH will not find a pre-existing user with that email address
JEMH will lookup ActiveDirectory for Primary 'mail' attribute matches, as well as 'proxyAddressess', any match will return a user entity containing the Primary 'mail' addresss and related userId for creation in JIRA.
Example of Alternative ID lookup
Using Active Directory, the following email sender andy@javahollic.de relates to an alternate proxyAddress of the user andy in Exchange.
MIME-Version: 1.0
Received: by 10.223.112.12 with HTTP; Sat, 18 Jun 2011 22:42:26 -0700 (PDT)
Date: Sun, 19 Jun 2011 17:42:26 +1200
Message-ID: <BANLkTinB1mfSh+GwOXGNWoL4SyDvOpdBoQ@mail.gmail.com>
Subject: This is a starting email template, update as required
From: "Andy Brook" <andy@javahollic.de>
To: test@localhost
Content-Type: text/plain; charset=UTF-8
This is from a remote user with a registered LDAP email address
The result of running this testcase is:
JEMH will not find a pre-existing user with that email address
JEMH will lookup ActiveDirectory for Primary 'mail' attribute matches, as well as 'proxyAddressess'. A direct Match is found. The
sAMAccountName(the userid) is found to pre-exist in JIRA, and so that account is used as a basis for the 'reporter'. No additional user creation has occurred.
Example of unknown Alternative ID lookup
Using Active Directory, the following email sender andy@javahollic.unknown is created:
MIME-Version: 1.0
Received: by 10.223.112.12 with HTTP; Sat, 18 Jun 2011 22:42:26 -0700 (PDT)
Date: Sun, 19 Jun 2011 17:42:26 +1200
Message-ID: <BANLkTinB1mfSh+GwOXGNWoL4SyDvOpdBoQ@mail.gmail.com>
Subject: This is a starting email template, update as required
From: "Andy Brook" <andy@javahollic.unknown>
To: test@localhost
Content-Type: text/plain; charset=UTF-8
This is from a remote user with a registered LDAP email address
The result of running this testcase is:
JEMH will not find a pre-existing user with that email address
JEMH will lookup ActiveDirectory for Primary 'mail' attribute matches, as well as 'proxyAddressess'. In this example, no match is found.
If user creation is enabled, and the sender email address is not blacklisted in the JEMH profile, the sender will have a new user account created. If no user is created, the email sender will effectively be treated as a non-jira user as no JIRA user account is associated.
Distribution list expansion
From version 1.8.20, JEMH can be used to expand distribution list addresses via LDAP. For more information, please see working with distribution groups.
Query support
In 1.8.20+ its also possible to query with LDAP filters, configured repositories. The new interface dynamically queries the LDAP server as you type (valid) filters, and updates the results accordingly.
The interface will use the Base DN with additional User DN if configured
By default, all available attributes will be returned, once the set of required attributes is identified, it can be entered to restrict the volume of data returned
To use the interface, select an existing LDAP configuration:
Once a selection is made, a filter can be entered, but querying will not commence whilst it is not valid, eg having mismatched brackets (currently the only validation check!), a warning message will be shown in such a case:
Once a valid filter has been entered, the server is queried with results listed in condensed form, showing cn, sAMAccountName and mail attributes if present:
Expanding this will reveal the complete set of attributes. No specific attention has been given to binary encoded fields or timestamps stored in milliseconds, hence some fields may look odd: