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 4 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 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 add the file directly to the config directory in your XNAT's file system. 
  2. You can create and install an XNAT plugin that contains this properties file. 
     

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/home/xnat/config
  • Create a new directory under config and name it auth.
  • Place your properties file(s) in this new directory

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 in the Admin UI (Go to Administer->Site Administration->Manage Plugins). 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 name of the provider you are configuring.

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 (of course you will need to change these properties to match those of your LDAP):

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})

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)

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/PROVIDER_ID-provider.properties 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/PROVIDER_ID-provider.properties 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.

Preserving Local Database Accounts

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 localdb-provider.properties file should look something like this:

name=Database
id=localdb
type=db
  • No labels