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 2 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 your plugins directory instead of in the services.properties file.

Adding Configuration to Plugin

Properties files for each authentication provider can either be added to an existing plugin, added to a plugin your create for all the authentication providers, or placed 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. 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/PROVIDER_ID-provider.properties.

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

name=Database
id=localdb
type=db

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

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

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 authentication.properties, replace

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

with

{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

name=XNAT

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:

search.filter=(sAMAccountName={0})

With OpenLDAP it might be more like this:

search.filter=(uid={0})

Deploying the plugin(s)

Once you have created a properties file for each of the authentication providers you want, you will need to 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.

  • No labels