Configuring Authentication Providers

The authentication providers you configure for your XNAT determine how your site's users will be able to log in. By default, XNAT uses its local database as an authentication provider.

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.

This page explains how to configure external authentication providers for your XNAT, and how to preserve or remove your local database account access while doing so.

Installing Authentication Provider Configurations

To add an authentication provider, create a properties file and add it to your XNAT installation:

1. SSH into your XNAT server and navigate to the config directory in your XNAT home folder. The default location for this is /data/xnat/home/config.
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. For each authentication provider, create a file named uniquelabel-provider.properties, where uniquelabel identifies your provider. The file format are specified below.
4. Copy each properties file to the config/auth directory and restart Tomcat to initialize them in XNAT.

Defining a Configuration Properties File for an Authentication Provider

All XNAT authentication providers share a common set of properties:

Most authentication provider implementations require other properties as well, but which properties and acceptable values for those is dependent on the provider implementation. For example, here is a sample LDAP configuration file.

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

Note the additional LDAP-specific properties "address", "userdn", "password", "search.base" and "search.filter". Full documentation and example LDAP configuration files are available in the documentation for the XNAT LDAP Authentication Plugin.

Enabling and Disabling Authentication Providers

Earlier versions of XNAT used a value set in a properties file to determine which configured providers should actually be enabled at run time. XNAT 1.7.5 has moved this to the Security section of the Site Administration page. The specific setting is labeled Enabled Authentication Providers.

All authentication providers that should be active and enabled should be specified by the provider.id value, with each provider separated by a comma. These changes go into effect as soon as you click the Save button, i.e. no Tomcat restart is required.

User Logins With Additional 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, if only one provider is enabled, all logins will be validated against that source.

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.

See XNAT User Management for more information about how to manage your user accounts. 

Additional Settings for Restricting localdb Account Creation

The following settings were added in 1.8.4 to restrict registering for the site via localdb. These settings can be found in: Site Admin UI > Security Settings > User Authentication Settings.
These settings are useful for sites that are set up for external login only or who want to prevent additional users from registering for localdb accounts. 

Settings

securityNewUserRegistrationDisabled

securityExternalUserParDisabled

securityLocalDbParRegistrationDisabled