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.