Installing and Administering the MFA Plugin for XNAT
The MFA plugin is a lightweight add-on for XNAT and does not create or require new datatypes. It can be installed or uninstalled without negatively affecting your system.
Installing the MFA Plugin
The latest version of the MFA plugin can be found here: https://bitbucket.org/xnatx/mfa_plugin/downloads/, or built from a local copy of the code repo. Be sure to check the MFA Plugin Compatibility Matrix for compatibility with your XNAT version. Follow the standard instructions for Deploying Plugins in XNAT to install.
Administering the MFA Plugin
Once installed, the MFA plugin is fairly easy to set up and run. The MFA plugin comes preconfigured to work with the Google Authenticator Service by default, and can also send emails with one-time-passcodes as a fallback method. As a site admin, you also have fine-grained controls over whether to require MFA for admins and non-admins, as well as the ability to grant or remove MFA exceptions for users. You can also reset a user’s MFA method and device if they are having trouble.
Setting Site Configurations
Log in as an XNAT Administrator and go to Plugin Settings → MFA Settings.
MFA Configuration Settings
Setting | Description |
|---|---|
Require MFA for Non-Admins | Default: FALSE This setting toggles whether all XNAT users aside from site administrators will be required to use MFA to log in. For the purposes of this panel, plugin-specific administrative roles such as a Container Manager are treated as “non-admins” |
Require MFA for Administrators | Default: FALSE This setting toggles whether all XNAT site administrators will be required to use MFA to log in. Setting this to be “TRUE” will immediately require you to set an MFA method to be logged back in as a site admin |
Each of these site config settings can be set via API:
POST - /xapi/mfa/configure?requireAdminMfa=[true/false]&requireMfa=[true/false]MFA Preferences
Setting | Description |
|---|---|
Preferred MFA Method | Default: Google Authenticator This setting allows you to choose whether to use Google Authenticator or the user’s email as the primary MFA method. We recommend Google Authenticator over email since the user’s email is already part of their primary user identity. This preference can be set via API:
CODE
Other authenticator applications such as Microsoft Authenticator or 1Password can also be used to scan the QR code and provide a valid OTP |
Allow Email as Backup MFA Option | Default: True This setting allows you to provide a fallback method for users who cannot access their MFA device. Users will see an option to have an OTP sent to their email address. Note that if the primary MFA method set above is “email”, this setting has no effect on user experience. This preference can be set via API:
CODE
|
Admin Email MFA Notification | Default: False This setting toggles whether or not to notify the site admin via email when a user reverts to email rather than Google Authenticator. This preference can be set via API:
CODE
|
Administering MFA Users
Site administrators can also provide fine-grained control of individual users' MFA settings via the MFA User Management tab in XNAT Plugin Settings.
In this panel, site administrators can see a list of all enabled and verified site users, with a listing of their individual MFA statuses. These include:
MFA Method – shows the active method used for MFA. If a user falls back to email rather than the site default, their method will be listed as “email”.
MFA Registered – shows whether the user has actively registered an MFA device via Google Authenticator. Note that if you are only using email for OTPs, this may always say “false”.
Exempted – Allows you to toggle whether or not to exempt the individual user from the MFA requirement. This can be set via API at:
POST - /xapi/mfa/exempt/{username}/[true/false]Note that any existing user exemptions are removed when the RequireMfa or RequireAdminMfa settings are turned on.
Reset – Allows you to reset the MFA method and deregister an MFA device for an individual user. This will allow them to re-enroll in MFA via Google Authenticator if they have lost their device. This can be set via API at:
POST - /xapi/mfa/{username}/unregister You can choose to reset MFA for all users, including yourself, if absolutely necessary using the “Reset All Users” button above the MFA users table.