--- a/Sphinx/source/plugins/authorization.rst	Mon Mar 27 17:50:08 2017 +0200
+++ b/Sphinx/source/plugins/authorization.rst	Mon Mar 27 21:14:18 2017 +0200
@@ -6,13 +6,15 @@
 
 .. contents::
 
-This **official plugin by Osimis** extends Orthanc with advanced
+This **official plugin by Osimis** extends Orthanc with an advanced
 authorization mechanism. For each incoming REST request to some URI,
 the plugin will query a Web service to know whether the access is
-granted to the user.
+granted to the user. If access is not granted, the HTTP status code is
+set to ``403`` (Forbidden).
 
-Source code is `freely available under the terms of the AGPLv3 license
-<https://bitbucket.org/osimis/orthanc-authorization>`__.
+The `source code of this plugin
+<https://bitbucket.org/osimis/orthanc-authorization>`__ is freely
+available under the terms of the AGPLv3 license.
 
 
 Compilation
@@ -20,7 +22,7 @@
 
 .. highlight:: bash
 
-The procedure to compile these plugins is similar of that for the
+The procedure to compile this plugin is similar of that for the
 :ref:`core of Orthanc <binaries>`. The following commands should work
 for every UNIX-like distribution (including GNU/Linux)::
 
@@ -88,18 +90,19 @@
   }
 
 In this example, the user is accessing an URI that is related to some
-DICOM resource, namely a patient whose identifier is ``123ABC``. In
-such a case, the following fields will be set in the JSON body:
+DICOM resource, namely a patient whose DICOM identifier is
+``123ABC``. In such a case, the following fields will be set in the
+JSON body:
  
 * The ``level`` field specifies which type of resource the user is
   accessing, according to the :ref:`DICOM model of the real world
   <model-world>`. This field can be set to ``patient``, ``study``,
   ``series``, or ``instance``.
 * The ``method`` field specifies which HTTP method is used by the
-  to-be-authorized request. It can be set ``get``, ``post``,
-  ``delete`` or ``put``.
+  to-be-authorized request. It can be set to ``get``, ``post``,
+  ``delete``, or ``put``.
 * The ``dicom-uid`` field gives the :ref:`DICOM identifier
-  <dicom-identifiers>` of the resource that will be accessed. If the
+  <dicom-identifiers>` of the resource that is accessed. If the
   resource is a patient, this field contains the ``PatientID`` DICOM
   tag. For a study, it contains its ``StudyInstanceUID``.  For a
   series, it contains its ``SeriesInstanceUID``. For an instance, it
@@ -172,8 +175,9 @@
 
 * ``granted`` tells whether access to the resource is granted
   (``true``) or not granted (``false``). In the case the user is
-  accessing a DICOM resource, the access to *all* the levels of
-  the hierarchy above this resource must be granted (conjunction).
+  accessing a DICOM resource, the access to *all* the levels of the
+  hierarchy above this resource must be granted (logical conjunction
+  over the levels).
 * ``validity`` tells the authorization plugin for how many seconds the
   result of the Web service must be cached. If set to ``0`` second,
   the cache entry will never expire.
@@ -186,15 +190,124 @@
 Authentication tokens
 ^^^^^^^^^^^^^^^^^^^^^
 
-WIP
+It is obviously desirable to limit access to the resources depending
+on the user that is logged in. Real-life Web framework such as Django
+would send the identity of the authenticated user either as an HTTP
+header, or as an additional argument for ``GET`` requests. The
+authorization plugin allows to forward these authentication tokens to
+the Web service.
+
+To configure the authentication plugin to use some HTTP header, one
+must provide the option ``TokenHttpHeaders`` the configuration file of
+Orthanc as follows::
+
+  {
+    "Name" : "MyOrthanc",
+    [...]
+    "Authorization" : {
+      "WebService" : "http://localhost:8000/",
+      "TokenHttpHeaders" : [ "hello" ]
+    }
+  }
+
+.. highlight:: text
+
+In such a situation, if some HTTP client issues the following call::
+
+  # curl -H 'hello: world' http://localhost:8042/patients/6eeded74-75005003-c3ae9738-d4a06a4f-6beedeb8
+
+.. highlight:: json
+
+Here is the JSON body the Web service would receive::
 
-1.2.1
+  {
+    "dicom-uid" : "123ABC",
+    "level" : "patient",
+    "method" : "get",
+    "orthanc-id" : "6eeded74-75005003-c3ae9738-d4a06a4f-6beedeb8",
+    "token-key" : "hello",
+    "token-value" : "world"
+  }
+
+.. highlight:: text
+
+Note how the key and the value of the authentication token stored as a
+HTTP header are forwarded to the Web service.
+
+The same mechanism can be used if the authentication token is provided
+as some ``GET`` argument by setting the ``TokenGetArguments``
+configuration option::
 
-Cache
+  # curl http://localhost:8042/patients/6eeded74-75005003-c3ae9738-d4a06a4f-6beedeb8?hello=world
+  {
+    "dicom-uid" : "123ABC",
+    "level" : "patient",
+    "method" : "get",
+    "orthanc-id" : "6eeded74-75005003-c3ae9738-d4a06a4f-6beedeb8",
+    "token-key" : "hello",
+    "token-value" : "world"
+  }
+
+**Note 1:** It is allowed to provide a list of HTTP tokens or a list
+of ``GET`` arguments in the configuration options. In this case, the
+authorization plugin will loop over all the available authentication
+tokens, until it finds one for which the access is granted (logical
+disjunction over the authentication tokens).
+
+**Note 2:** The cache entry that remembers whether some access was
+granted in the past, depends on the value of the token.
+
+**Note 3:** The support of authentication tokens provided as ``GET``
+arguments requires a version of Orthanc that is above 1.2.1.
 
 
 Full configuration
 ------------------
 
-WIP
+.. highlight:: json
+
+Here is the list of all the configuration options::
 
+  {
+    "Name" : "MyOrthanc",
+    [...]
+    "Authorization" : {
+      "WebService" : "http://localhost:8000/",
+      "TokenGetArguments" : [ "user" ],
+      "TokenHttpHeaders" : [ "hello" ],
+      "UncheckedResources" : [
+        "/series",
+        "/instances",
+        "/patients",
+        "/studies",
+        "/plugins/explorer.js",
+        "/system"
+      ],
+      "UncheckedFolders" : [
+        "/app/",
+        "/web-viewer/app/",
+        "/web-viewer/libs/",
+        "/wsi/app/"
+      ],
+      "UncheckedLevels" : [ "study" ]
+    }
+  }
+
+The following options have been described above: ``WebService``,
+``TokenGetArguments``, and ``TokenHttpHeaders``. Here are the
+remaining options:
+
+* ``UncheckedResources`` specifies a list of resources for which the
+  authentication plugin is not triggered, and to which access is
+  always granted.
+
+* ``UncheckedFolders`` is similar to ``UncheckedResources`` for folders:
+  Access to all the URIs below the unchecked folders is always granted.
+
+* ``UncheckedLevels`` allows to specify which levels of the
+  :ref:`DICOM hierarchy <model-world>` are ignored by the authorization
+  plugin. This can be used to reduce the number of calls to the Web
+  service. Think for instance about an authorization mechanism that
+  simply associates its studies to a set of granted users: In this case,
+  the series and instance levels can be ignored.
+