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.
| Property | Description |
|---|---|
| name* | Defines a human-readable name for the provider. This should be unique on the system, and shows up on the login page if multiple providers are enabled. |
| provider.id* | Defines the ID for this provider. This must be unique on the system. This value is to enable the provider in XNAT. |
| auth.method* | Indicates the method to be used for authentication. This basically maps directly to the provider implementation. For the LDAP authentication provider, this is always ldap. |
| auto.enabled* | Indicates whether user accounts that authenticate using the provider definition should automatically be enabled on the system. If true, users can use the system right away. If false, an administrator needs to review and enable the account manually before the user can access the system. |
| auto.verified* | Indicates whether user accounts that authenticate using the provider definition should automatically be verified on the system. If false, users must receive an email from the system and click the provided link before they can access the system. |
| address | Specifies the address of the LDAP server for the provider definition. This should include the protocol (ldap or ldaps), the server address, and the port (only required if non-standard). |
| userdn | Contains the user DN for the authenticating account. |
| password | Contains the password for the authenticating account. |
| search.base | Indicates the top level to search in the LDAP structure for user account entries. |
| search.filter | The LDAP field that contains the user's login name. This may be different depending on your LDAP implementation. An Active Directory implementation will need something like the following:
BASH
With OpenLDAP it might be more like this:
BASH
|
| validate.username | For testing purposes only. This is a regular user name on the LDAP server. This is used by the ValidateLdap.groovy script to verify that the combination of address, user DN, password, and search base and filter are configured properly. |
| validate.password | For testing purposes only. This is the password corresponding to the user name above. |
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.1.0.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.0.0-SNAPSHOT.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