Page tree
Skip to end of metadata
Go to start of metadata

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 will use its default authentication provider – the local XNAT database. The 'admin' and 'guest' accounts are the two database accounts that come with XNAT.

Many sites also want users to be able to log in via LDAP. Currently, this is the only other type of authentication provider that is supported in XNAT.

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.

Upgrading to XNAT 1.7?

If you have already set up LDAP for an earlier version of XNAT and want to upgrade to 1.7, you will need to put your old LDAP configuration in a jar in a new properties file instead of in the services.properties file.

Adding An Authentication Configuration

In order to add an authentication provider, you will need to create a properties file and add it to your XNAT webapp. There are two ways you can do this:

  1. You can create and install an XNAT plugin that contains this properties file. This way was added with the introduction of plugins in XNAT 1.7.0.
  2. You can add the file directly to the config directory in your XNAT's file system. This was the way of doing it in XNAT 1.6. It was removed in 1.7.0, but added back in 1.7.1. If you are on XNAT 1.7.0, you must upgrade your XNAT to a newer version or use way 1.

These two methods are not compatible with each other. If there are any providers configured in the config directory, those are what XNAT uses. If not, XNAT uses any providers configured via plugins. If none are configured there, XNAT will have only the default database provider.

Adding configurations directly to the file system

To add the properties files directly to the file system, do the following:

  • Go to your XNAT webapp's config directory. The default location for this will be /data/xnat/home/config
  • Create a new directory under config and name it auth.
  • Place your properties file(s) in this new directory

Once you have these properties files in auth, simply restart Tomcat.

Adding configurations via plugins

If you choose to put your properties files in a plugin, we recommend creating a separate plugin for each provider you intend to configure. One benefit of putting each configuration in a separate plugin is that you can then manage each of them separately (see Manage Plugins in the AdminUI for more information). However, you could bundle all of your configurations into a single plugin or add them to an existing plugin if you wish. 

Each file should be at this location relative to the top level of the plugin: META-INF/xnat/auth/PROVIDER_ID-provider.properties, where PROVIDER_ID is the id of the provider you are configuring.

XNAT 1.7 plugins are simply jars, so if you are creating a new plugin, simply jar the directory which contains your META-INF/xnat/auth/PROVIDER_ID-provider.properties files. In the command line, you would run the following command at the plugin root folder:

$ ./gradlew clean jar

Once you have these properties files in jars, simply shut down Tomcat, move the plugin jar file into the plugins folder (by default this is located at /data/xnat/home/plugins), and restart Tomcat.


If you have previously specified providers in the config directory, make sure to delete these before restarting Tomcat or the provider configuration in your plugins will be ignored.

Adding an LDAP Provider Configuration 

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 will want to create a separate properties file for each LDAP server.

To enable LDAP authentication, 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=LDAP
id=ldap1
type=ldap
address=ldap://ldapurl:389/dc=my,dc=domain
userdn=cn=MyServiceAccount,ou=MyGroup,dc=my,dc=domain
password=MyPassword
search.base=ou=people
search.filter=(uid={0})
namewhat you want your users to see on the login page, if they have a choice of authentication providers
iduniquely 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).
typeindicates what type of provider it is. The two types that are currently supported are "db" for the local XNAT database and "ldap"
addressthe URL of your LDAP server. Note the trailing parameters in the example URL. These should be included.
userdnthe server login configuration script that grants site-wide access to your LDAP server
passwordpassword for that user
search.baseconfigures where the LDAP server should look for user accounts
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:

search.filter=(sAMAccountName={0})

With OpenLDAP it might be more like this:

search.filter=(uid={0})
orderan 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.

This configuration syntax has changed slightly as of XNAT 1.6; 1.5 and older configurations (such as those referenced here) will not work with 1.6 or 1.7.

In particular, if you are copying the search filter over from your 1.5 authentication.properties, replace

%USER% (a homebrewed syntax used by XNAT 1.5)

with

{0} (Spring Security syntax)


Preserving Local Database Accounts

By default, users can log into XNAT only using credentials that are stored in a local database. However, if you specify any authentication providers, XNAT will no longer assume that you want the local database provider.

If you want both LDAP and database logins to be options for your users, you will need to create a properties file for the database provider (in addition to creating a properties file for the LDAP one). Fortunately, the database properties file is very simple.

Create a new file called localdb-provider.properties and copy the following code into it:

name=Database
id=localdb
type=db

Once you save this file, you can add it to your XNAT as a config or as a plugin, as specified above. 

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.