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 21 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 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.

Upgrading?

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:

  1. 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.
  2. 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.
  3. 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:

provider.providers.enabled=db, mainrepo

provider.db.name=Database
provider.db.id=db
provider.db.type=db

provider.mainrepo.name=Main
provider.mainrepo.id=mainrepo
provider.mainrepo.type=ldap
provider.mainrepo.address=ldap://ldap.miskatonic.edu
provider.mainrepo.userdn=cn=readonly,dc=miskatonic,dc=edu
provider.mainrepo.password=password
provider.mainrepo.search.base=ou=users,dc=xnat,dc=org
provider.mainrepo.search.filter=(uid={0})

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: nameid, and typeEvery 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:

  1. Move all of the properties for the provider to a file named something like mainrepo-provider.properties
  2. Remove the provider.mainrepo prefix from all of the properties
  3. Rename id to provider.id and type to auth.method
  4. You can also add new properties supported in 1.7.5 or later: visible, auto.enabled, and auto.verified
  5. Move your properties file to the config/auth folder

The mainrepo provider configuration file would look something like this:

name=Main
provider.id=mainrepo
auth.method=ldap
visible=true
auto.enabled=false
auto.verified=true
address=ldap://ldap.miskatonic.edu
userdn=cn=readonly,dc=miskatonic,dc=edu
password=password
search.base=ou=users,dc=xnat,dc=org
search.filter=(uid={0})


Adding configurations via plugins

Related Documentation

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=LDAP
provider.id=ldap1
auth.method=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.

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.



  • No labels