Configuring Authentication Providers

Introduction

This documentation provides instructions on how to set up and manage authentication providers in XNAT. 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. However, XNAT provides the ability to integrate authentication through external repositories such as LDAP and OpenID through its authentication provider API. 

Enabling external authentication methods requires installing and configuring one or more plugins. 

• To enable LDAP authentication, install and configure the XNAT LDAP Authentication Plugin

• To enable OpenID authentication, install and configure the OpenID Auth Plugin

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

Most authentication provider implementations require other properties as well, but properties and acceptable values for those are 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

The list of enabled authentication providers is managed in the Security section of the Site Administration page. The specific setting is labeled Enabled Authentication Providers as shown in the image below. To alter the list, do the following: 

Instructions for Enabling Providers

1. Login to XNAT as a Site Administrator

2. Navigate to the Administer > Site Administration in the top navigation

3. Once the screen opens to the Site Administration screen, select Security on the left-hand side of the page. Or, go to the "Find Setting" input in the upper right corner of the Admin UI and enter "enabledProviders". 

Note: By default, localdb is the sole authentication provider in XNAT. To add a new provider, the user has to type the name of the provider.id and spell it exactly as it appears in the installed properties file. 

4. Set the Enabled Authentication Provider value to a comma separated list of providers identified using the provider.id property. If you choose to remove "localdb" in favor of another installed provider, only that method of logging in will be available to users. 

5. Click Save in the footer of the panel to save your settings. 

Note: These changes go into effect as soon as you click the Save button, i.e. no Tomcat restart is required. As soon as you save this change, your Users will be able to view the enabled provider(s) on the XNAT login screen. 

Disabling a Provider

Following the same instructions as above, you can remove an authentication method from the list. This will disable that authentication provider.  

Enabled Providers are 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

Initial Sign-in and Account Linking

Depending on how the LDAP and OpenID providers are configured, after signing in for the first time the user may be led to a screen to either create a new account or login to an existing XNAT localdb account, to merge this new provider-enabled identity with an existing one. Below is a screenshot of the Register A New Account screen.

Once this process is completed, the user will now be able to login to XNAT using their provider credentials.

User Logins with Multiple LDAP Providers

If you have configured more than one LDAP provider source, 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.

User Password Management

When using external authentication, all management of that user account and its password must be done through that external authentication source. Users cannot perform tasks such as resetting their LDAP or OpenID password through the XNAT User Interface (UI).

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

Command Line / API Usage

In order to access XNAT data via scripts when an external authentication provider is enabled, use Alias Tokens to authenticate the user. 

See: Generating an Alias Token for Scripted Authentication

Additional Settings for Restricting localdb Account Creation

Available in XNAT 1.8.4 and higher

The following settings were added 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