orthanc-book: Sphinx/source/plugins/authorization.rst comparison

comparison Sphinx/source/plugins/authorization.rst @ 98:b56083f38695

authorization

author	Sebastien Jodogne <s.jodogne@gmail.com>
date	Mon, 27 Mar 2017 21:14:18 +0200
parents	20b9ecb43eed
children	c310a795c133

comparison

equal deleted inserted replaced

-:20b9ecb43eed
+:b56083f38695
 Advanced authorization plugin
 =============================
 .. 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
 -----------
 .. 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)::
 $ mkdir Build
 $ cd Build
 "method" : "get",
 "orthanc-id" : "6eeded74-75005003-c3ae9738-d4a06a4f-6beedeb8"
 }
 In this example, the user is accessing an URI that is related to some
-DICOM resource, namely a patient whose identifier is ``123ABC``. In
+DICOM resource, namely a patient whose DICOM identifier is
-such a case, the following fields will be set in the JSON body:
+``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``,
+to-be-authorized request. It can be set to ``get``, ``post``,
-``delete`` or ``put``.
+``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
 contains its ``SOPInstanceUID``.
 * The ``orthanc-id`` field gives the :ref:`Orthanc identifier
 Here is a description of these two fields:
 * ``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
+accessing a DICOM resource, the access to *all* the levels of the
-the hierarchy above this resource must be granted (conjunction).
+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.
 **Note:** The source code of the plugin contains a `basic example
 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
-1.2.1
+would send the identity of the authenticated user either as an HTTP
+header, or as an additional argument for ``GET`` requests. The
-Cache
+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::
+{
+"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::
+# 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.

Mercurial > hg > orthanc-book

comparison Sphinx/source/plugins/authorization.rst @ 98:b56083f38695