Merge pull request #128 from datalad/docs-auth

DOC: More on authentication

docs/source/settingup.rst

@@ -63,4 +63,4 @@ After initialization, run ``xnat-update`` to download all files for the project.
 
 .. rubric:: Footnotes
 
-.. [#f1] While installable for Windows 10, the extension may not be able to perform all functionality documented here. Please get in touch if you are familiar with Windows `to help us fix bugs <https://github.com/datalad/datalad-osf/issues?q=is%3Aissue+is%3Aopen+windows>`_.
+.. [#f1] While installable for Windows 10, the extension may not be able to perform all functionality documented here. Please get in touch if you are familiar with Windows `to help us fix bugs <https://github.com/datalad/datalad-xnat>`_.

docs/source/tutorial/authentication.rst

@@ -3,9 +3,84 @@
 Authentication
 ==============
 
-"Oh no, I accidentally mistyped my password!"
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
+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:
+
+.. code-block:: bash
+
+   $ 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 <https://central.xnat.org/>`_.
+In order to authenticate as an anonymous user, supply the special value ``anonymous`` to
+the ``--credential`` parameter.
+
+.. code-block:: bash
+
+   $ 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:
+
+.. code-block:: bash
+
+   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:
+
+.. code-block:: bash
+
+   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 <https://github.com/datalad/datalad-xnat/issues/new>`_ 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``:
@@ -17,4 +92,4 @@ stopped working, you can re-enter new credentials with the configuration
    user: <user>
    password: <password>
 
-Alternatively, find your system's secure Keyring (your systems credential store) and remove or replace your password in there.
+Alternatively, find your system's secure Keyring (your systems credential store) and remove or replace your password in there.