Skip to main content
Skip table of contents

Configuring Authentication Providers


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. 

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, 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
  • type is now auth.method
Defines a human-readable name for the provider. This should be unique on the system.
Defines the ID for this provider. This must be unique on the system. This value is to enable the provider in XNAT.
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.
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.
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.
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 properties and acceptable values for those are dependent on the provider implementation. For example, here is a sample LDAP configuration file.


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

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


Hide User Registration Options
If set to TRUE, this setting will disable new user localdb registration and conceal all links to the registration page. This will not block external users users from registering for the site via project access request email.
Disable Local DB Project Access Requests
If set to TRUE, this setting will disable the ability to send project access requests to external emails (un-registered users).
Disable External Project Access Requests
If set to TRUE, this setting will prevent localdb registration of un-registered users via project access request email.  The project access request email will redirect users to the LDAP/External Login registration page instead of the localdb registration page.

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.