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.

For XNAT 1.7.5 and later, enabling external authentication methods requires installing and configuring one or more plugins. 

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:

If you are migrating property definitions from versions of XNAT prior to 1.7.5, keep in mind:

  • id is now provider.id
  • type is now auth.method
PropertyRequired?DefaultDescription
name
Defines a human-readable name for the provider. This should be unique on the system.
provider.id
Defines the ID for this provider. This must be unique on the system. This value is to enable the provider in XNAT.
auth.method
Indicates the method to be used for authentication. This basically maps directly to the provider implementation. For the LDAP authentication provider, this is always ldap.
auto.enabled
falseIndicates whether user accounts that authenticate using the provider definition should automatically be enabled on the system. If true, users can use the system right away. If false, an administrator needs to review and enable the account manually before the user can access the system.
auto.verified
falseIndicates whether user accounts that authenticate using the provider definition should automatically be verified on the system. If false, users must receive an email from the system and click the provided link before they can access the system.
visible
trueIndicates whether the provider is visible to users (i.e. displayed on the login page)

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.

This is also settable through the REST API, which can be particularly useful if you have removed "localdb" access and need to restore it. See: Enabling Authentication Providers via the SiteConfig API



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. 



$label.name