Mercurial > hg > orthanc-book
annotate Sphinx/source/plugins/authorization.rst @ 97:20b9ecb43eed
doc
| author | Sebastien Jodogne <s.jodogne@gmail.com> |
|---|---|
| date | Mon, 27 Mar 2017 17:50:08 +0200 |
| parents | 750f7ab733c1 |
| children | b56083f38695 |
| rev | line source |
|---|---|
|
96
750f7ab733c1
start documentation of authorization
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
1 .. _authorization: |
|
750f7ab733c1
start documentation of authorization
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
2 |
|
750f7ab733c1
start documentation of authorization
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
3 |
|
750f7ab733c1
start documentation of authorization
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
4 Advanced authorization plugin |
|
750f7ab733c1
start documentation of authorization
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
5 ============================= |
|
750f7ab733c1
start documentation of authorization
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
6 |
|
750f7ab733c1
start documentation of authorization
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
7 .. contents:: |
|
750f7ab733c1
start documentation of authorization
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
8 |
|
750f7ab733c1
start documentation of authorization
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
9 This **official plugin by Osimis** extends Orthanc with advanced |
| 97 | 10 authorization mechanism. For each incoming REST request to some URI, |
| 11 the plugin will query a Web service to know whether the access is | |
| 12 granted to the user. | |
|
96
750f7ab733c1
start documentation of authorization
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
13 |
| 97 | 14 Source code is `freely available under the terms of the AGPLv3 license |
| 15 <https://bitbucket.org/osimis/orthanc-authorization>`__. | |
| 16 | |
|
96
750f7ab733c1
start documentation of authorization
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
17 |
|
750f7ab733c1
start documentation of authorization
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
18 Compilation |
|
750f7ab733c1
start documentation of authorization
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
19 ----------- |
|
750f7ab733c1
start documentation of authorization
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
20 |
|
750f7ab733c1
start documentation of authorization
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
21 .. highlight:: bash |
|
750f7ab733c1
start documentation of authorization
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
22 |
|
750f7ab733c1
start documentation of authorization
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
23 The procedure to compile these plugins is similar of that for the |
|
750f7ab733c1
start documentation of authorization
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
24 :ref:`core of Orthanc <binaries>`. The following commands should work |
|
750f7ab733c1
start documentation of authorization
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
25 for every UNIX-like distribution (including GNU/Linux):: |
|
750f7ab733c1
start documentation of authorization
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
26 |
|
750f7ab733c1
start documentation of authorization
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
27 $ mkdir Build |
|
750f7ab733c1
start documentation of authorization
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
28 $ cd Build |
|
750f7ab733c1
start documentation of authorization
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
29 $ cmake .. -DSTATIC_BUILD=ON -DCMAKE_BUILD_TYPE=Release |
|
750f7ab733c1
start documentation of authorization
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
30 $ make |
|
750f7ab733c1
start documentation of authorization
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
31 |
|
750f7ab733c1
start documentation of authorization
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
32 The compilation will produce a shared library ``OrthancAuthorization`` |
|
750f7ab733c1
start documentation of authorization
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
33 that contains the authorization plugin. |
|
750f7ab733c1
start documentation of authorization
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
34 |
|
750f7ab733c1
start documentation of authorization
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
35 Usage |
|
750f7ab733c1
start documentation of authorization
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
36 ----- |
|
750f7ab733c1
start documentation of authorization
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
37 |
|
750f7ab733c1
start documentation of authorization
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
38 .. highlight:: json |
|
750f7ab733c1
start documentation of authorization
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
39 |
|
750f7ab733c1
start documentation of authorization
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
40 You of course first have to :ref:`install Orthanc <compiling>`. Once |
|
750f7ab733c1
start documentation of authorization
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
41 Orthanc is installed, you must change the :ref:`configuration file |
|
750f7ab733c1
start documentation of authorization
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
42 <configuration>` to tell Orthanc where it can find the plugin: This is |
|
750f7ab733c1
start documentation of authorization
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
43 done by properly modifying the ``Plugins`` option. You could for |
|
750f7ab733c1
start documentation of authorization
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
44 instance use the following configuration file:: |
|
750f7ab733c1
start documentation of authorization
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
45 |
|
750f7ab733c1
start documentation of authorization
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
46 { |
|
750f7ab733c1
start documentation of authorization
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
47 "Name" : "MyOrthanc", |
|
750f7ab733c1
start documentation of authorization
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
48 [...] |
|
750f7ab733c1
start documentation of authorization
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
49 "Plugins" : [ |
|
750f7ab733c1
start documentation of authorization
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
50 "/home/user/OrthancAuthorization/Build/libOrthancAuthorization.so" |
| 97 | 51 ], |
| 52 "Authorization" : { | |
| 53 "WebService" : "http://localhost:8000/" | |
| 54 } | |
|
96
750f7ab733c1
start documentation of authorization
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
55 } |
|
750f7ab733c1
start documentation of authorization
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
56 |
|
750f7ab733c1
start documentation of authorization
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
57 Orthanc must of course be restarted after the modification of its |
|
750f7ab733c1
start documentation of authorization
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
58 configuration file. |
|
750f7ab733c1
start documentation of authorization
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
59 |
| 97 | 60 |
| 61 Web Service | |
| 62 ----------- | |
| 63 | |
| 64 This section describes how a Web service suitable for the | |
| 65 authorization plugin can be designed. | |
| 66 | |
| 67 **Note:** The behavior described in this section is implemented by the | |
| 68 ``AuthorizationWebService`` C++ class in the source code. It is | |
| 69 possible to define a different authorization back-end by deriving | |
| 70 from interface ``IAuthorizationService``. | |
| 71 | |
| 72 | |
| 73 Incoming request | |
| 74 ^^^^^^^^^^^^^^^^ | |
| 75 | |
| 76 For each HTTP/REST request that Orthanc receives, the plugin will | |
| 77 issue a set of HTTP ``POST`` requests against the Web service that is | |
| 78 specified in the configuration file (in the basic configuration file | |
| 79 above, the Web service listening at ``http://localhost:8000/`` is | |
| 80 used). The body of each of those ``POST`` requests is a JSON file | |
| 81 similar to the following one:: | |
| 82 | |
| 83 { | |
| 84 "dicom-uid" : "123ABC", | |
| 85 "level" : "patient", | |
| 86 "method" : "get", | |
| 87 "orthanc-id" : "6eeded74-75005003-c3ae9738-d4a06a4f-6beedeb8" | |
| 88 } | |
| 89 | |
| 90 In this example, the user is accessing an URI that is related to some | |
| 91 DICOM resource, namely a patient whose identifier is ``123ABC``. In | |
| 92 such a case, the following fields will be set in the JSON body: | |
| 93 | |
| 94 * The ``level`` field specifies which type of resource the user is | |
| 95 accessing, according to the :ref:`DICOM model of the real world | |
| 96 <model-world>`. This field can be set to ``patient``, ``study``, | |
| 97 ``series``, or ``instance``. | |
| 98 * The ``method`` field specifies which HTTP method is used by the | |
| 99 to-be-authorized request. It can be set ``get``, ``post``, | |
| 100 ``delete`` or ``put``. | |
| 101 * The ``dicom-uid`` field gives the :ref:`DICOM identifier | |
| 102 <dicom-identifiers>` of the resource that will be accessed. If the | |
| 103 resource is a patient, this field contains the ``PatientID`` DICOM | |
| 104 tag. For a study, it contains its ``StudyInstanceUID``. For a | |
| 105 series, it contains its ``SeriesInstanceUID``. For an instance, it | |
| 106 contains its ``SOPInstanceUID``. | |
| 107 * The ``orthanc-id`` field gives the :ref:`Orthanc identifier | |
| 108 <orthanc-ids>` of the resource. | |
| 109 | |
| 110 When the user accesses a lower-level resource in the DICOM hierarchy | |
| 111 (a study, a series or an instance), the authorization plugin will | |
| 112 issue one separate call to the Web service for each level of the | |
| 113 hierarchy. For instance, here are the 3 successive requests that are | |
| 114 issued when accessing some series:: | |
| 115 | |
| 116 { | |
| 117 "dicom-uid" : "123ABC", | |
| 118 "level" : "patient", | |
| 119 "method" : "get", | |
| 120 "orthanc-id" : "6eeded74-75005003-c3ae9738-d4a06a4f-6beedeb8" | |
| 121 } | |
| 122 { | |
| 123 "dicom-uid" : "1.3.51.0.1.1.192.168.29.133.1681753.1681732", | |
| 124 "level" : "study", | |
| 125 "method" : "get", | |
| 126 "orthanc-id" : "6e2c0ec2-5d99c8ca-c1c21cee-79a09605-68391d12" | |
| 127 } | |
| 128 { | |
| 129 "dicom-uid" : "1.3.12.2.1107.5.2.33.37097.2012041612474981424569674.0.0.0", | |
| 130 "level" : "series", | |
| 131 "method" : "get", | |
| 132 "orthanc-id" : "6ca4c9f3-5e895cb3-4d82c6da-09e060fe-9c59f228" | |
| 133 } | |
| 134 | |
| 135 It the user is accessing a URI that is not directly related to an | |
| 136 individual DICOM resource, the JSON body will look as follows:: | |
| 137 | |
| 138 { | |
| 139 "level" : "system", | |
| 140 "method" : "get", | |
| 141 "uri" : "/changes" | |
| 142 } | |
| 143 | |
| 144 In such a situation, the following fields are set: | |
| 145 | |
| 146 * The ``level`` field is always set to ``system``. | |
| 147 * The ``method`` field is the same as above. | |
| 148 * The ``uri`` field provides the URI that was accessed by the user. | |
| 149 | |
| 150 **Important note:** The plugin will transparently parse the URIs of | |
| 151 the core :ref:`REST API of Orthanc <rest>`, of the :ref:`Web viewer | |
| 152 plugin <webviewer>`, of the :ref:`DICOMweb plugin <dicomweb>`, and of | |
| 153 the :ref:`whole-slide imaging plugin <wsi>`. Unrecognized URIs (such | |
| 154 as those introduced by other plugins) will be handled as a ``system`` | |
| 155 call. It is possible to introduce parsing support for more plugins by | |
| 156 modifying the ``DefaultAuthorizationParser`` C++ class in the source | |
| 157 code of the plugin. | |
| 158 | |
| 159 | |
| 160 Expected answer | |
| 161 ^^^^^^^^^^^^^^^ | |
| 162 | |
| 163 The Web service must answer by sending a JSON file that tells whether | |
| 164 the access is granted or not to the user. Here is a sample answer:: | |
| 165 | |
| 166 { | |
| 167 "granted": true, | |
| 168 "validity" : 5 | |
| 169 } | |
| 170 | |
| 171 Here is a description of these two fields: | |
| 172 | |
| 173 * ``granted`` tells whether access to the resource is granted | |
| 174 (``true``) or not granted (``false``). In the case the user is | |
| 175 accessing a DICOM resource, the access to *all* the levels of | |
| 176 the hierarchy above this resource must be granted (conjunction). | |
| 177 * ``validity`` tells the authorization plugin for how many seconds the | |
| 178 result of the Web service must be cached. If set to ``0`` second, | |
| 179 the cache entry will never expire. | |
| 180 | |
| 181 **Note:** The source code of the plugin contains a `basic example | |
| 182 <https://bitbucket.org/osimis/orthanc-authorization/src/default/Resources/TestService.js>`__ | |
| 183 of such a Web service written in node.js. | |
| 184 | |
| 185 | |
| 186 Authentication tokens | |
| 187 ^^^^^^^^^^^^^^^^^^^^^ | |
|
96
750f7ab733c1
start documentation of authorization
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
188 |
|
750f7ab733c1
start documentation of authorization
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
189 WIP |
|
750f7ab733c1
start documentation of authorization
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
190 |
| 97 | 191 1.2.1 |
| 192 | |
| 193 Cache | |
| 194 | |
| 195 | |
| 196 Full configuration | |
| 197 ------------------ | |
| 198 | |
| 199 WIP | |
| 200 |