XNAT LDAP Authentication Plugin

The XNAT LDAP Authentication Plugin allows you to use an external LDAP registry for user authentication into your 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 (we've 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.

Configuring LDAP Authentication Providers

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


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.

You can use the files ldap1-provider-sample.properties and ldap2-provider-sample.properties as starting points for your own provider configurations. Just copy the files, omitting the "-sample" in the name. The values specified in those file 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 you'll need to map the server name ldap.xnat.org to the IP address for that VM (by default, to the hosts file on any machines that need to connect to the server (alternatively you can replace ldap.xnat.org 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. Note that properties that are marked with an asterisk (like this*) are default provider options and not specific to the LDAP plugin.

Important note when upgrading from earlier versions of XNAT: Previous versions of XNAT uses 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.

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.
addressSpecifies 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).
userdnContains the user DN for the authenticating account.
passwordContains the password for the authenticating account.
search.baseIndicates the top level to search in the LDAP structure for user account entries.

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:


With OpenLDAP it might be more like this:

validate.usernameFor 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.passwordFor 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