OpenID Authentication Plugin
Introduction
OpenID is an interoperable authentication protocol based on the OAuth 2.0 framework. It simplifies the way to verify the identity of users based on the authentication performed by an Authorization Server. This document provides instructions on how to configure authentication providers and provides Property Names and Descriptions specific to OpenID authentication plugin.
Installing the OpenID Plugin
Download the latest version of the XNAT OpenID Authentication Plugin at https://bitbucket.org/xnatx/openid-auth-plugin/downloads/, and follow the instructions here: Deploying Plugins in XNAT.
Be sure to check the OpenID Plugin Compatibility Matrix for compatibility with your version of XNAT
Before you can use this plugin to enable authentication against your OpenID server, you must create an authentication provider properties file in your XNAT server.
Configuring OpenID as an Authentication Provider
XNAT searches for authentication server configurations by searching for files whose names match the pattern: *-provider.properties
It searches in the following locations:
- On the classpath in the folder
META-INF/xnat/auth - On the file system in
{XNAT_HOME}/config/auth
This plugin uses any entries located in any of those properties files where the property auth.method is set to "openid" (which points to XdatUserAuthService.OpenID) to define a new OpenID repository configuration. A site can have multiple authentication providers. See Configuring Authentication Providers for more information on enabling and disabling authentication providers in XNAT.
Property Names and Descriptions
One can use the file openid-provider-sample-AAF.properties as starting point for the desired provider configurations.
The various configuration options for the XNAT OpenID authentication provider plugin are described below. The properties that are marked with an asterisk (*) are default provider options and not specific to the OpenID plugin.
Note: When upgrading from earlier versions of XNAT, previous versions of XNAT used the properties "id" and "type" to specify the provider ID and type of authentication. These properties are no longer supported: id is replaced by "provider.id" and type by "auth.method".
Property | Description |
|---|---|
name* | Defines a human-readable name for the provider. This should be unique on the system, and shows up on the login page if multiple providers are enabled. |
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 OpenID authentication provider, this is always OpenID. |
auto.enabled* | Indicates 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* | Indicates 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. |
OpenID Server specific properties. The "X" in the property name below should be replaced by the value of provider.id | |
siteUrl | The XNAT Host url |
openid.X.clientId | Client ID on the OpenID Authentication Server |
openid.X.clientSecret | Client Secret on the OpenID Authentication Server |
openid.X.accessTokenUri | Access token URI |
openid.X.userAuthUri | User Authentication URI on the OpenID Server |
openid.X.scopes | Comma separated scope |
openid.X.link | HTML <a> element which will generate the link displayed on the login page |
openid.X.shouldFilterEmailDomains | Flag that sets if email domains should be checked |
openid.X.allowedEmailDomains | Domains which are allowed to login, only checked when 'shouldFilterEmailDomains' is true |
openid.X.forceUserCreate | Flag to force the user creation process, normally this should be set to true |
openid.X.emailProperty | Property names to use when creating users |
openid.X.givenNameProperty | |
openid.X.familyNameProperty | |
When upgrading from OpenID Plugin version 1.3.0 to newer versions, the properties file needs to be modified. Newer versions do not use the "enabled" property anymore and each OpenID provider should have its own property file.
Enabling and Using OpenID to Authenticate into your XNAT
See Configuring Authentication Providers