XNAT LDAP Authentication Plugin

Introduction

The XNAT Lightweight Directory Access Protocol (LDAP) Authentication Plugin allows the user to use an external LDAP registry for their authentication into an XNAT instance. For users, XNAT will create local user accounts which mirror LDAP accounts and are used for project access. This plugin replaces and improves upon early functionality that was built into core XNAT, prior to XNAT 1.7.5.

XNAT uses the Spring Security library's LDAP integration and should support most LDAP implementations (actively tested against Active Directory and OpenLDAP providers). To authenticate against an LDAP server, or multiple servers, you must create a separate properties file for each LDAP server.

Installing the LDAP Authentication Plugin

Download the latest version of the XNAT LDAP Authentication Plugin at https://bitbucket.org/xnatx/ldap-auth-plugin/downloads/, and follow the instructions here: Deploying Plugins in XNAT. 

The LDAP Authentication Plugin is compatible with XNAT versions 1.7.5 and later

Before you can use this plugin to enable authentication against your LDAP server, you must create an authentication provider properties file in your XNAT server. 

Configuring LDAP Authentication Providers

XNAT searches for authentication server configurations by looking for files whose names match the pattern:

*-provider.properties

It looks in the following locations:

• On the classpath in the folder META-INF/xnat/auth

• In {XNAT_HOME}/config/auth

This plugin uses any entries located in any of those properties files where the property auth.method is set to "ldap" (which points to XdatUserAuthService.LDAP) to define a new LDAP repository configuration.

One can use the files ldap1-provider-sample.properties and ldap2-provider-sample.properties as starting points for their own provider configurations. Copy the files, omitting the "-sample" in the name. The values specified in those files have been tested and verified against two separate LDAP configurations:

• The configuration in ldap1-provider-sample.properties works with the default configuration of the XNAT LDAP Server Vagrant project. The only caveat is that one will need to map the server name ldap.xnat.org to the Internet Protocol (IP) address for that VM (by default, 10.1.1.22) to the hosts file on any machines that need to connect to the server (alternatively ldap.xnat.org can be replaced with the IP address).

• The configuration in ldap2-provider-sample.properties works with the LDAP test server provided by Forum Systems and described in more detail here.

The various configuration options for the XNAT LDAP authentication provider plugin are described below. Of special note, the properties that are marked with an asterisk (*) are default provider options and not specific to the LDAP plugin.

Important note when upgrading from earlier versions of XNAT: Prior to version 1.7.5, XNAT used the properties id and type to specify the provider ID and type of authentication. These properties are no longer supported: id is replaced by provider.id and type by auth.method.

search.filter=(sAMAccountName={0})

search.filter=(uid={0})

Enabling LDAP Providers

The list of enabled authentication providers is managed in the Security section of the Site Administration page. The specific setting is labeled Enabled Authentication Providers. All authentication providers that should be active and enabled should be specified by the provider.id value, with each provider separated by a comma. These changes go into effect as soon as you click the Save button, i.e. no Tomcat restart is required.

See Configuring Authentication Providers for more details.

This is also scriptable through the REST API. The currently enabled providers can be retrieved through the REST path /xapi/siteConfig/enabledProviders. The enabled providers can be set by POSTing a JSON list of the provider IDs. See Enabling Authentication Providers via the SiteConfig API. 

Testing LDAP Providers

You can test provider properties against an LDAP server using the ValidateLdap.groovy script (running this script requires having Groovy installed and the plugin jar available). To run the test script, use following syntax:

groovy 'jar:file:path/to/ldap-auth-plugin-1.2.1.jar!/ValidateLdap.groovy' [properties-file]

On Linux or OS X, the "'" characters are required to prevent the "!" character from being detected by the shell interpreter. You can prefix the "!" with a backslash ("\") instead.

If you don't specify a properties file, the validate script will use the same default values as specified in ldap1-provider-sample.properties, along with the default user asmith and password password. You can specify a properties file that only overrides a few properties in the sample configuration as well, otherwise inheriting the values for the default properties. The username and password properties aren't normally configured in the provider properties definition but can be specified for the LDAP validator with the properties user and pass (note that password is already used in the provider definition, but indicates the password for the LDAP binding account and stays the same regardless of the specific username and password being validated).

The output from a successful validation looks something like this:

$ groovy 'jar:file:build/libs/ldap-auth-plugin-1.2.1.jar!/ValidateLdap.groovy'
Dec 06, 2017 3:18:45 PM org.springframework.security.ldap.DefaultSpringSecurityContextSource <init>
INFO:  URL 'ldap://ldap.xnat.org', root DN is ''
User asmith authentication state: true

XNAT Version Compatibility Matrix

The following describes what versions of the LDAP Auth Plugin are compatible with which versions of XNAT.