Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 3 Next »

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 only the default database authentication provider. 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. This page explains how to configure one or many LDAP authentication providers for your XNAT. 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 file.

Adding Configuration

There are two places you can put your newly created authentication provider properties files: in your config directory (under an auth subdirectory) or in a plugin. If you choose to put them in a plugin, you can either add them to an existing plugin, add them to a plugin your create for all the authentication providers, or place them in separate plugins for each provider. One benefit of putting each provider in a separate plugin is that you can then manage each of them separately through Administer->Site Administration->Manage Plugins (make sure you follow the documentation for developing plugins if you want your plugins to show up in Manage Plugins). Regardless of which plugins you put them in, each file should be at this location relative to the top level of the plugin: META-INF/xnat/auth/ If you instead want to put these files in your config directory (which allows you to modify them without having to modify a plugin jar), you should create a subdirectory under config named 'auth' and put the properties files there. 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.

Local Database Providers

By default, users can log into XNAT only using credentials that are stored in a local database. If this is the only way you want people to be able to log in to your XNAT, then you will not need to specify any authentication providers. However, if you specify any authentication providers, XNAT will no longer assume that you want the local database provider, so 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. Your file should look something like this:


LDAP Providers

You can also configure XNAT to also support LDAP authentication.  It's known to work with ActiveDirectory and OpenLDAP; other LDAP implementations have not been tested but should work too. To authenticate against an LDAP server, or multiple servers, you will want to create a separate properties file for each LDAP server. Users will then be able to log in using their LDAP credentials and will not have to remember a new username and password. 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 (of course you will need to change these properties to match those of your LDAP):


This configuration has changed slightly as of 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, replace

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


{0} (Spring Security syntax)

These values would be used if you wanted the provider to access an LDAP server with URL ldap://ldapurl:389/dc=my,dc=domain.  Authentication would be performed by attempting to bind with the DN uid=<user-login-name>,ou=people,dc=my,dc=domain.  

name is what you want your users to see. On the login page, there is a dropdown from which users select the provider they want to use. If you want the database provider to be listed as "XNAT" instead of "Database", simply set


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 and ldap.

userdn/password are credentials for the LDAP account that you're connecting with to perform the authentication.  Typically this is a service account, not an actual person's account.

search.filter is 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:


Deploying via plugin

Once you have created a properties file for each of the authentication providers you want, you can either add them to an existing plugin or create a new one. These files should be located at META-INF/xnat/auth/ within your plugin(s). Plugins are simply jars, so if you are creating a new plugin, simply jar the directory which contains your META-INF/xnat/auth/ properties files. 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 under the folder configured as xnat.home), 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. 

Deploying via config directory

Once you have created a properties file for each of the authentication providers you want, you will need to create a directory named 'auth' under your 'config' directory (by default config is under the folder configured as xnat.home). Your properties files should then be placed in that auth directory. Once you have these properties files in auth, simply restart Tomcat.


  • No labels