LDAP Util library

Name	LDAP Util
Latest Version	1.0.16
Confluence Versions	any (osuser/atlassian-user configurations)
Jira Versions	any (osuser configurations)
Support
Author(s)	Andy Brook
Homepage	here
Price	Free
Issues	tucked into the Confluence-LDAP section of the NTLM Jira project.
License	BSD
Source	SVN, Fisheye
Download	view all jars, latest stable version 1.0.16 jar, unstable 1.0.17-SNAPSHOT

A missing Snapshot is not a bug, it just hasn't been built yet.

Description/Features

A library that provides a simplified interface to LDAP user lookup's that make use of pre-existing LDAP configuration in atlassian-user.xml and (deprecated) osuser.xml.

Install

In order to do this you need to have LDAP authentication setup and working. See LDAP User Management for more details.

Get the dependent JAR's

This plugin has one dependency on commons-digester, providing XML parser support used to process the Confluence atlassian-user.xml file. For JIRA, no such library is required. There are two use cases:

System referenced code (eg the NTLM authenticator for confluence)

In which case, the dependent JAR need to go into WEB-INF/lib, but confluence already comes with a digester jar so there is nothing to do in this scenario.

Confluence plugin (eg the Custom Space User Management plugin)

In which case, the dependent JAR need to be marked as 'compile' dependency of the plugins POM.

Using ldaputil in confluence plugins

If you want to make use of the LDAP util library, you need to have a 'compile' dependency for commons-digester (an earlier version is already bundled with confluence) as its needed for atlassian-user parsing, the additions to your pom should be:

<!-- ldap util compile dependency so it gets bundled with the plugin -->
        <dependency>
            <groupId>com.dolby.confluence.net</groupId>
            <artifactId>ldaputil</artifactId>
            <version>1.0.10</version>
        </dependency>

<!-- atlassian-user.xml parser -->
        <dependency>
            <groupId>commons-digester</groupId>
            <artifactId>commons-digester</artifactId>
            <version>1.8</version>
            <scope>compile</scope>
        </dependency>

Compatibility Matrix

This library should work with ALL versions of Confluence / Jira. Will document any exceptions as/when found.

Release Notes

Version	Notes
1.0.16	Replace incorrect wildcard usage producing bad account lookups for emails. Enables domains that a users email address are equivalent to (user@myco.co.uk/user@myco.com) to match correctly
1.0.15	provide -generate command line function to load an atlassian-user.xml file, probe Active Directory to get a list of DC's and generate an ntlm-atlassian-user.xml file (obv, for use specifically with NTLM). This isn't particularly elegant but by keeping a common configuration file, multiple DOMAINS should, in theory at least, be able to be supported. add method to check whether a given user exists and is enabled (ie not been disabled by admins)
1.0.14	Enabled anonymous login for LDAP Enable configurable alternative for osuser/atlassian-user config files, useful for NTLM, perhaps other uses
1.0.13	Fixes NPE for Active Directory DC lookup when there are none found (usually an indicator that the basecontext in atlassian user is too low (ou=x,ou=y,dc=this,dc=that moved higher to: dc=this,dc=that) moved ldaputil.properties to example-ldaputil.properties to enable inclusion in plugins with their own ldap configuration file/ configuration methods.
1.0.12	removed dependency on ClassLoaderUtils, should now work with confluence 2.10+ API expanded to allow general LDAP queries to be made (ie complete LDAP filters can be provided) with specified attributes and maximum return rows. The results are returned for flexible processing. If using active directory, the ability to list out the Domain Controllers.
1.0.11	adds ability to use mulitple ldap server definitions, in both atlassian-user (Confluence only) and osuser (Jira and Confluence) configuration files. This means that if multiple LDAP servers are defined, plugins and macros that use this library will continue to work if the Primary (first) in the list, goes down, just like Confluence/Jira. verified under Jira believed to work ok under Confluence - feedback encouraged!
1.0.10	this version is BSD adds getUserDetailsByEmailAddress(String) extends LDAPUser model to include emailAliases allows emailAliases in LDAP to have nominated prefixes (as found in Active Directory proxyAddresses attribute)

LDAP Util configuration

Although you don't have to specify any LDAP configuration, some choices are available, if you want to change anything you need to unpack the ldaputil jar and edit ldaputils.properties, or provide it programatically at the point of use.

Common configuration

These could be changed if needed

Key	Default	Valid Values	Description
ldaputil.providerType	atlassian-user	osuser,atlassian-user	use Atlassian user config
ldaputil.ldap.narrowingFilterExpression	(objectclass=user)	any	this can be used to restrict the LDAP lookup
ldaputil.ldap.fullNameFormat	0	0,1	0= Lastname, Firstname , 1 = Firstname Lastname (no comma)
ldaputil.ldap.forceUserIDCase	2	0,1,2	0=force lower, 1=force upper, 2=use reflect stored value
ldaputil.ldap.subtreeScope	2	0,1,2	0=object scope, 1=one-level scope, 2=subtree scope
ldaputil.ldap.emailAliasesLdapAttribute	proxyAddresses	any ldap attribute	'proxyAddresses' is the Active Directory attribute that houses email aliases
ldaputil.ldap.emailAliasesLdapAttributeSearchPrefix	n/a	comma separated values	This prefix will be used to optionally 'pull out email address' from LDAP, I see in Active Directory many entries such as 'smtp:user@company.co.uk'. The values are case sensitive as the comparison is done in Java not LDAP filters, for example 'smtp:,SMTP:'
ldaputil.ldap.emailAliasesLdapAttributeParser	n/a	implementer of my ILDAPEmailAliasProcessor, eg LDAPUtilsActiveDirectoryEmailAliasExtractor	If specified, this class handles the extraction of email aliases from an LDAP lookup NamingEnumeration
ldaputil.ldap.dclistFilterExpression	(userAccountControl:1.2.840.113556.1.4.803:=532480)	any filter	lists all servers that allowed to participate in authentication of users
ldaputil.ldap.initialContextValidationLookupUser	AnyOldInvalidUsername	if specified, a valid user name that exists	used to validate each ldap connection (has to be common)
ldaputil.providerFilenameOverride	n/a	a valid filename/path e.g. ldaputil-atlassian-user.xml	If provided, enables potentially multiple separate LDAP repositories to be setup specifically for ldaputil related use.

Denotes optional field.

Configuration based on 'atlassian-user'

If you are using 'atlassian-user' no changes are required.

Configuration based on 'osuser'

The ldap attribute keys need configuring in the property file (unpack the jar, edit, repack), the existing values are suited to Active Directory - configure as appropriate, and/or comment here for my info. all keys are required.

Key	Default	Valid Values	Description
ldaputil.osuser.providerClass	com.opensymphony.user.provider.ldap.LDAPCredentialsProvider	any	the provider class containing the ldap configuration in osuser.xml
ldaputil.ldap.emailLdapAttribute	mail	any	Mail, this is AD specific, configure as appropriate
ldaputil.ldap.userIdLdapAttribute	sAMAccountName	any	User account ID, this is AD specific, configure as appropriate
ldaputil.ldap.firstNameAttribute	givenName	any	First Name, this is AD specific, configure as appropriate
ldaputil.ldap.lastNameAttribute	sn	any	Surname, this is AD specific, configure as appropriate

Logging

To enable logging for this library, you will need to add the following to log4j.properties in WEB-INF/classes:

#
# LDAP UTILS
#
log4j.logger.com.dolby.confluence.net.ldap=DEBUG, confluencelog
log4j.additivity.com.dolby.confluence.net.ldap=false

log4j.logger.com.dolby.confluence.net.ldap.atlassianuser=DEBUG, confluencelog
log4j.additivity.com.dolby.confluence.net.ldap.atlassianuser=false

log4j.logger.com.dolby.confluence.net.ldap.osuser=DEBUG
log4j.additivity.com.dolby.confluence.net.osuser=false

Manually checking LDAP connectivity

Available only in the current 1.0.12-SNAPSHOT is the ability to check the configuration at the command line. The process to do this is as follows (setup for the WAR distro as that's what I use):

Extract the WAR if applicable, in which case change CONFHOME to ../lib
Copy the ldaputils-xyz.jar to WEB-INF/lib
Navigate to WEB-INF/classes

Copy the text below into a file, eg list.sh in WEB-INF/classes:

Linux

#!/bin/bash
CONFHOME=../../../confluence/WEB-INF/lib

for aFile in `ls -1 ../lib/*.jar`
do
 CP=$CP:$aFile
done

for aFile in `ls -1 ../../../confluence/WEB-INF/lib/*.jar`
do
 CP=$CP:$aFile
done

java -cp .:$CP com.dolby.confluence.net.ldap.LDAPLookupUtil $1

Windows (will need tweaking)

@echo off
java -cp ..\lib\ldaputil-1.0.12-SNAPSHOT.jar;..\lib\commons-logging-1.0.4.jar;..\lib\confluence-2.8.2.jar;..\lib/atlassian-core-3.9.jar;..\lib\commons-digester-1.5.jar;..\lib\commons-collections-3.2.jar;..\lib\commons-beanutils-1.6.1.jar;. com.dolby.confluence.net.ldap.LDAPLookupUtil %1

Command line options to these scripts are:
- userid to lookup
- -listdc to list the DC's (only applicable to Active Directory servers)
The script may need minor version changes.

See Identifying Active Directory connection details may be useful background reading for users new to LDAP.

Using the library in Confluence

I used this library to create Beanshell macros that allows queries to be made over the underlying LDAP repositories (not multple repositories, just the first to work).

Example configurations

Atlassian-user.xml

This config file only appears to be used in Confluence. The search filter removes disabled users, it can be removed.

<atlassian-user>
    <repositories>
    
    <ldap key="ldapRepository" name="LDAP Repository@test.server.net" cache="true">
			<host>test.server.net</host>
			<port>3268</port>
			<securityPrincipal>CN=auser,OU=something,DC=yourco,DC=net</securityPrincipal>
			<securityCredential>pasword</securityCredential>
			<securityProtocol>plain</securityProtocol>
			<securityAuthentication>simple</securityAuthentication>
			<baseContext>dc=yourco,dc=net</baseContext>
			<baseUserNamespace>dc=yourco,dc=net</baseUserNamespace>
			<baseGroupNamespace>DC=yourco,DC=net</baseGroupNamespace>
			<usernameAttribute>sAMAccountName</usernameAttribute>
			<userSearchFilter>(&amp;(sAMAccountType=805306368)(!(userAccountControl:1.2.840.113556.1.4.803:=2)))</userSearchFilter>
			<firstnameAttribute>givenname</firstnameAttribute>
			<surnameAttribute>sn</surnameAttribute>
			<emailAttribute>mail</emailAttribute>
			<groupnameAttribute>sAMAccountName</groupnameAttribute>
			<groupSearchFilter>(&amp;(objectClass=group)(mail=*))</groupSearchFilter>
			<membershipAttribute>member</membershipAttribute>
		</ldap>

		<hibernate name="Hibernate Repository" key="hibernateRepository"  description="Hibernate Repository" />
    
    </repositories>
</atlassian-user>

osuser.xml

This config file can be used with Confluence (but is deprecated) or with Jira (the only format it supports):

<opensymphony-user>

	<authenticator class="com.opensymphony.user.authenticator.SmartAuthenticator" />

	<provider class="com.opensymphony.user.provider.ldap.LDAPCredentialsProvider">
	    	<property name="java.naming.factory.initial">com.sun.jndi.ldap.LdapCtxFactory</property>
    		<property name="java.naming.provider.url">ldap://test.server.net:3268</property>
    		<property name="searchBase">DC=yourco,DC=net</property>
    		<property name="uidSearchName">sAMAccountName</property>
    		<property name="java.naming.security.principal">CN=username,OU=something,OU=somethingelse,DC=yourco,DC=net</property>
    		<property name="java.naming.security.credentials">password</property>
		<property name="java.naming.referral">follow</property>
    		<property name="exclusive-access">true</property>
	</provider>

        <authenticator class="com.opensymphony.user.authenticator.SmartAuthenticator" />
	<provider class="com.atlassian.core.ofbiz.osuser.CoreOFBizCredentialsProvider">
		<property name="exclusive-access">true</property>
	</provider>
	<provider class="com.opensymphony.user.provider.ofbiz.OFBizProfileProvider">
		<property name="exclusive-access">true</property>
	</provider>
	<provider class="com.opensymphony.user.provider.ofbiz.OFBizAccessProvider">
		<property name="exclusive-access">true</property>
	</provider>
</opensymphony-user>

Just remove the ldaputil.properties file from the JAR, add to WEB-INF/classes, put the JAR minus config file in WEB-INF/lib, rebuild/deploy and it should just work. In time I hope to set this up a proper plugin via plugin repository.

LDAP Util library

Description/Features

Install

Get the dependent JAR's

System referenced code (eg the NTLM authenticator for confluence)

Confluence plugin (eg the Custom Space User Management plugin)

Compatibility Matrix

Release Notes

LDAP Util configuration

Common configuration

Configuration based on 'atlassian-user'

Configuration based on 'osuser'

Logging

Manually checking LDAP connectivity

Using the library in Confluence

Example configurations

Atlassian-user.xml

osuser.xml

Screenshot of Beanshell AD/conf user lookup tool

Labels

Children (4)

Comments (55)

Andy Brook says:

David Peterson [CustomWare] says:

Andy Brook says:

David Peterson [CustomWare] says:

Andy Brook says:

David Peterson [CustomWare] says:

Andy Brook says:

Neil Crow says:

Andy Brook says:

Andrew Hoover Mannings says:

Andy Brook says:

Michael Jositz says:

Andy Brook says:

Andy Brook says:

Michael Jositz says:

Andy Brook says:

Michael Jositz says:

Andy Brook says:

Michael Jositz says:

Andy Brook says:

Michael Jositz says:

Andy Brook says:

Michael Jositz says:

Andy Brook says:

Michael Jositz says:

Andy Brook says:

Michael Jositz says:

Adam Campbell says:

Andy Brook says:

Adam Campbell says:

Andy Brook says:

Adam Campbell says:

Andy Brook says:

Adam Campbell says:

Andy Brook says:

Adam Campbell says:

Andy Brook says:

Adam Campbell says:

Andy Brook says:

Adam Campbell says:

Andy Brook says:

Andy Brook says:

Milkman says:

Andy Brook says:

Adam Campbell says:

Andy Brook says:

Adam Campbell says:

Adam Campbell says:

Vidar Kongsli says:

Andy Brook says:

Vidar Kongsli says:

Andy Brook says:

Vidar Kongsli says:

Andy Brook says:

Tobias Anstett says: