Authentication

The authentication process

Typical interactions with an XNAT instance require a user name and a password. When you initialize a project using datalad xnat-init for a given XNAT URL you will thus be prompted to supply those credentials in the command line:

$ datalad xnat-init <myxnatinstance>
  You need to authenticate with '<myxnatinstance>' credentials. <myxnatinstance>/app/template/Register.vm provides information on how to gain access
  user: <myusername>
  password: <mypassword>
  password (repeat): <mypassword>

Afterwards, these credentials are stored internally in your systems keyring under the credential name datalad-<myxnatinstance>, and subsequent interactions to this XNAT instance will authenticate automatically using the stored credentials.

Multiple different credentials

If you have multiple XNAT instances with different user names or passwords you want to authenticate against, the name of the credential should automatically authenticate you with the correct user password combination based on the XNAT URL. If you nevertheless want to enfore a specific credential to be used, you can supply the --credential <name> parameter to xnat-init. If <name> matches an existing credential in your keyring, the given credential will be used for authentication. If <name> does not match an existing credential, you will be prompted for user name and password, and the supplied credentials will be saved under the <name> you specified.

Authenticating as anonymous

Typical interactions with an XNAT instance require a user name and a password. Some XNAT instances, however, allow anonymous access, such as XNAT central. In order to authenticate as an anonymous user, supply the special value anonymous to the --credential parameter.

$ datalad xnat-init --credential anonymous https://central.xnat.org
  [INFO   ] Querying https://central.xnat.org for projects available to user anonymous
  No project name specified. The following projects are available on https://central.xnat.org for user anonymous:
  [...]

If things go wrong during authentication

Unauthorized Errors: If the authentication process fails, datalad xnat-init will throw an error:

xnat_init(error): . (dataset) [Request to XNAT server failed: Unauthorized]

In this case, read on in the last paragraph on how to update your credential.

Faulty XNAT URLs: If the provided XNAT URL is fault, and can be appropriately reached, you may see an error like this:

xnat_init(error): . (dataset) [During authentication the XNAT server sent MissingSchema(Invalid URL 'myxnatinstance/data/JSESSION': No schema supplied. Perhaps you meant http://<wrongurl>/data/JSESSION?)]

In this case, double check the URL you provided. Open an issue if you need help or think that you found a bug.

Updating credentials

"Oh no, I accidentally mistyped my password!" If you supplied wrong credentials, or previously working credentials expired and stopped working, you can re-enter new credentials with the configuration datalad.credentials.force-ask=1:

$ datalad -c datalad.credentials.force-ask=1 xnat-init <url>
You need to authenticate with [...]
user: <user>
password: <password>

Alternatively, find your system's secure Keyring (your systems credential store) and remove or replace your password in there.