# HG changeset patch # User Sebastien Jodogne # Date 1490642058 -7200 # Node ID b56083f38695575f89191a1298a33e86384df05d # Parent 20b9ecb43eed3db287091c65622853b90e979f53 authorization diff -r 20b9ecb43eed -r b56083f38695 Sphinx/source/plugins/authorization.rst --- 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 -`__. +The `source code of this plugin +`__ 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 `. 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 `. 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 - ` of the resource that will be accessed. If the + ` 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 ` 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. +