The authentication providers you configure for your XNAT determine how your site's users will be able to log in. If you do not specify any authentication providers, XNAT uses the default authentication provider, which uses the local XNAT database. The admin account is the default user account in a newly initialized XNAT database (there's also a user named guest, but that user can't be used to log in).
Many teams using XNAT have existing user repositories such as university-wide user databases that they'd like to leverage for user authentication and account management. XNAT provides the ability to integrate authentication through external repositories through its authentication provider API.
As of the XNAT 1.7.5 release, LDAP authentication is no longer part of the core XNAT application but requires installing the LDAP authentication plugin. See Configuring LDAP Authentication Providers below for more information.
This page explains how to configure one or many LDAP authentication providers for your XNAT, and how to preserve or remove your local database account access while doing so.
If you have configured LDAP for versions of XNAT earlier than 1.7, you'll need to migrate properties from your existing deployment.
If you have configured LDAP for versions of XNAT 1.7 prior to 1.7.5 (including pre-1.7), you'll need to modify some of the property names to work properly with XNAT 1.7.5 and later.
If you are running XNAT 1.7.0, you should upgrade to the newest XNAT release, but if you can't the procedure to configure LDAP authentication providers for XNAT 1.7.0 only differs from subsequent point releases of XNAT 1.7.
Adding an Authentication Provider Configuration
To add an authentication provider, create a properties file and add it to your XNAT installation:
- Go to the config directory in your XNAT home folder. The default location for this is /data/xnat/home/config, but can vary by deployment.
- If it doesn't already exist, create a new folder named auth. For the default settings, this would be located at /data/xnat/home/config/auth.
- Place your properties file(s) in this new directory. Your authentication provider properties files must be named something-provider.properties. The something part can be any legal file name but should indicate the particular authentication provider.
Once you have these properties files in auth, simply restart Tomcat.
XNAT 1.7.0 required putting your provider configuration properties in a plugin jar file. This is not compatible with later versions of XNAT, so if you have your provider properties configured in that way, you should just extract the properties file from the plugin jar, then remove the jar file from the XNAT plugins folder.
Prior to XNAT 1.7, all authentication providers were configured in a single file (services.properties), with each provider distinguished by a prefix on the property names. For example:
In this example, the default database provider has the ID db, so its properties are prefixed with provider.db, while the LDAP provider has the ID mainrepo and its properties prefixed with provider.mainrepo.
For XNAT 1.7, each provider must be defined in its own properties file, but the prefix is no longer required (you also don't need to define the default database provider).
Notice that both the db and mainrepo provider configurations have three properties in common: name, id, and type. Every provider configuration must have these three main properties but the names of two of these properties has changed in XNAT 1.7.5!
- id is now provider.id
- type is now auth.method
To migrate the properties for the mainrepo provider above:
- Move all of the properties for the provider to a file named something like mainrepo-provider.properties
- Remove the provider.mainrepo prefix from all of the properties
- Rename id to provider.id and type to auth.method
- You can also add new properties supported in 1.7.5 or later: visible, auto.enabled, and auto.verified
- Move your properties file to the config/auth folder
The mainrepo provider configuration file would look something like this:
Adding configurations via plugins
XNAT no longer supports configuration of authentication providers by plugin.
Configuring LDAP Authentication Providers
As of the XNAT 1.7.5 release, LDAP authentication is no longer part of the core XNAT application but requires installing the LDAP authentication plugin as described in this section.
Installing the LDAP Authentication Plugin
As of the XNAT 1.7.5 release, LDAP authentication is no longer part of the core XNAT application but requires installing the LDAP authentication plugin. You can download the latest release of this plugin from:
Once you've downloaded the plugin jar, copy or move it into the plugins folder under your XNAT installation's home folder. Restart the Tomcat service.
Note that adding, modifying, or removing LDAP configurations also require a restart.
For versions of XNAT 1.7 before 1.7.5, if you add an LDAP authentication method, XNAT will assume that you only want to allow access to those LDAP accounts. To preserve any local accounts, see "Preserving Local Database Accounts" below.
XNAT is known to work with ActiveDirectory and OpenLDAP providers. Other LDAP implementations have not been tested but should work as well. To authenticate against an LDAP server, or multiple servers, you must create a separate properties file for each LDAP server.
To connect to an LDAP repository, you must provide some information about the LDAP server you want to use. Here is an LDAP properties template which shows what an LDAP properties file should look like (you will need to change these properties to match those of your LDAP and name the file
PROVIDER_ID-provider.properties, where PROVIDER_ID is the id of the provider you are configuring):
|name||what you want your users to see on the login page, if they have a choice of authentication providers|
|id||uniquely identifies the provider in case there are multiple providers of a given type. If you add a second LDAP provider, it should have a different ID ("ldap2" is fine).|
|type||indicates what type of provider it is. The two types that are currently supported are "db" for the local XNAT database and "ldap"|
|address||the URL of your LDAP server. Note the trailing parameters in the example URL. These should be included.|
|userdn||the server login configuration script that grants site-wide access to your LDAP server|
|password||password for that user|
|search.base||configures where the LDAP server should look for user accounts|
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:
|order||an optional parameter to control the order in which the login options appear on the XNAT login page in the case of multiple authentication providers. This should be an integer, where the providers with smaller "order" values are listed earlier in the dropdown.|
Preserving Local Database Accounts
This does not apply to XNAT 1.7.5 and later. Instead you can enable or disable each authentication provider by ID:
- Go to Administer→Site Administration (requires an administrator account)
- Click the Security tab on the left side
- Find the text box labeled Enabled Authentication Providers
- Enter the IDs of the authentication providers that should be enabled, separated by commas
- Click Save
User Logins With LDAP Providers
If you have configured more than one authentication provider, your XNAT login screen will give users the option of selecting how they want to log in. Otherwise, all logins will be checked against the only configured provider (regardless of whether that provider is LDAP or local database).
See XNAT User Management for more information about how to manage your user accounts. When someone with an LDAP account logs into XNAT for the first time, XNAT stores their user information and their user account can then be managed just like other user accounts. The one exception to this is that if you want to change passwords for LDAP users this needs to be done on the LDAP server unless your XNAT instance is customized to support modifying users on the LDAP server through the XNAT UI.