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 |