# HG changeset patch # User Sebastien Jodogne # Date 1490629808 -7200 # Node ID 20b9ecb43eed3db287091c65622853b90e979f53 # Parent 750f7ab733c1fdfff3fb6c36d720d269ba774500 doc diff -r 750f7ab733c1 -r 20b9ecb43eed Sphinx/source/plugins/authorization.rst --- a/Sphinx/source/plugins/authorization.rst Wed Mar 22 16:45:42 2017 +0100 +++ b/Sphinx/source/plugins/authorization.rst Mon Mar 27 17:50:08 2017 +0200 @@ -7,12 +7,13 @@ .. contents:: This **official plugin by Osimis** extends Orthanc with advanced -authorization mechanism. +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. -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. Authorization credentials can be retrieved either from a GET -argument, or from a HTTP header. +Source code is `freely available under the terms of the AGPLv3 license +`__. + Compilation ----------- @@ -47,16 +48,153 @@ [...] "Plugins" : [ "/home/user/OrthancAuthorization/Build/libOrthancAuthorization.so" - ] + ], + "Authorization" : { + "WebService" : "http://localhost:8000/" + } } -.. highlight:: text - Orthanc must of course be restarted after the modification of its configuration file. -Configuration -------------- + +Web Service +----------- + +This section describes how a Web service suitable for the +authorization plugin can be designed. + +**Note:** The behavior described in this section is implemented by the +``AuthorizationWebService`` C++ class in the source code. It is +possible to define a different authorization back-end by deriving +from interface ``IAuthorizationService``. + + +Incoming request +^^^^^^^^^^^^^^^^ + +For each HTTP/REST request that Orthanc receives, the plugin will +issue a set of HTTP ``POST`` requests against the Web service that is +specified in the configuration file (in the basic configuration file +above, the Web service listening at ``http://localhost:8000/`` is +used). The body of each of those ``POST`` requests is a JSON file +similar to the following one:: + + { + "dicom-uid" : "123ABC", + "level" : "patient", + "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 +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``. +* The ``dicom-uid`` field gives the :ref:`DICOM identifier + ` of the resource that will be 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 + ` of the resource. + +When the user accesses a lower-level resource in the DICOM hierarchy +(a study, a series or an instance), the authorization plugin will +issue one separate call to the Web service for each level of the +hierarchy. For instance, here are the 3 successive requests that are +issued when accessing some series:: + + { + "dicom-uid" : "123ABC", + "level" : "patient", + "method" : "get", + "orthanc-id" : "6eeded74-75005003-c3ae9738-d4a06a4f-6beedeb8" + } + { + "dicom-uid" : "1.3.51.0.1.1.192.168.29.133.1681753.1681732", + "level" : "study", + "method" : "get", + "orthanc-id" : "6e2c0ec2-5d99c8ca-c1c21cee-79a09605-68391d12" + } + { + "dicom-uid" : "1.3.12.2.1107.5.2.33.37097.2012041612474981424569674.0.0.0", + "level" : "series", + "method" : "get", + "orthanc-id" : "6ca4c9f3-5e895cb3-4d82c6da-09e060fe-9c59f228" + } + +It the user is accessing a URI that is not directly related to an +individual DICOM resource, the JSON body will look as follows:: + + { + "level" : "system", + "method" : "get", + "uri" : "/changes" + } + +In such a situation, the following fields are set: + +* The ``level`` field is always set to ``system``. +* The ``method`` field is the same as above. +* The ``uri`` field provides the URI that was accessed by the user. + +**Important note:** The plugin will transparently parse the URIs of +the core :ref:`REST API of Orthanc `, of the :ref:`Web viewer +plugin `, of the :ref:`DICOMweb plugin `, and of +the :ref:`whole-slide imaging plugin `. Unrecognized URIs (such +as those introduced by other plugins) will be handled as a ``system`` +call. It is possible to introduce parsing support for more plugins by +modifying the ``DefaultAuthorizationParser`` C++ class in the source +code of the plugin. + + +Expected answer +^^^^^^^^^^^^^^^ + +The Web service must answer by sending a JSON file that tells whether +the access is granted or not to the user. Here is a sample answer:: + + { + "granted": true, + "validity" : 5 + } + +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 + the hierarchy above this resource must be granted (conjunction). +* ``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 +`__ +of such a Web service written in node.js. + + +Authentication tokens +^^^^^^^^^^^^^^^^^^^^^ WIP +1.2.1 + +Cache + + +Full configuration +------------------ + +WIP +