Mercurial > hg > orthanc-book
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
97:20b9ecb43eed | 98:b56083f38695 |
---|---|
4 Advanced authorization plugin | 4 Advanced authorization plugin |
5 ============================= | 5 ============================= |
6 | 6 |
7 .. contents:: | 7 .. contents:: |
8 | 8 |
9 This **official plugin by Osimis** extends Orthanc with advanced | 9 This **official plugin by Osimis** extends Orthanc with an advanced |
10 authorization mechanism. For each incoming REST request to some URI, | 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 | 11 the plugin will query a Web service to know whether the access is |
12 granted to the user. | 12 granted to the user. If access is not granted, the HTTP status code is |
13 | 13 set to ``403`` (Forbidden). |
14 Source code is `freely available under the terms of the AGPLv3 license | 14 |
15 <https://bitbucket.org/osimis/orthanc-authorization>`__. | 15 The `source code of this plugin |
16 <https://bitbucket.org/osimis/orthanc-authorization>`__ is freely | |
17 available under the terms of the AGPLv3 license. | |
16 | 18 |
17 | 19 |
18 Compilation | 20 Compilation |
19 ----------- | 21 ----------- |
20 | 22 |
21 .. highlight:: bash | 23 .. highlight:: bash |
22 | 24 |
23 The procedure to compile these plugins is similar of that for the | 25 The procedure to compile this plugin is similar of that for the |
24 :ref:`core of Orthanc <binaries>`. The following commands should work | 26 :ref:`core of Orthanc <binaries>`. The following commands should work |
25 for every UNIX-like distribution (including GNU/Linux):: | 27 for every UNIX-like distribution (including GNU/Linux):: |
26 | 28 |
27 $ mkdir Build | 29 $ mkdir Build |
28 $ cd Build | 30 $ cd Build |
86 "method" : "get", | 88 "method" : "get", |
87 "orthanc-id" : "6eeded74-75005003-c3ae9738-d4a06a4f-6beedeb8" | 89 "orthanc-id" : "6eeded74-75005003-c3ae9738-d4a06a4f-6beedeb8" |
88 } | 90 } |
89 | 91 |
90 In this example, the user is accessing an URI that is related to some | 92 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 | 93 DICOM resource, namely a patient whose DICOM identifier is |
92 such a case, the following fields will be set in the JSON body: | 94 ``123ABC``. In such a case, the following fields will be set in the |
95 JSON body: | |
93 | 96 |
94 * The ``level`` field specifies which type of resource the user is | 97 * The ``level`` field specifies which type of resource the user is |
95 accessing, according to the :ref:`DICOM model of the real world | 98 accessing, according to the :ref:`DICOM model of the real world |
96 <model-world>`. This field can be set to ``patient``, ``study``, | 99 <model-world>`. This field can be set to ``patient``, ``study``, |
97 ``series``, or ``instance``. | 100 ``series``, or ``instance``. |
98 * The ``method`` field specifies which HTTP method is used by the | 101 * The ``method`` field specifies which HTTP method is used by the |
99 to-be-authorized request. It can be set ``get``, ``post``, | 102 to-be-authorized request. It can be set to ``get``, ``post``, |
100 ``delete`` or ``put``. | 103 ``delete``, or ``put``. |
101 * The ``dicom-uid`` field gives the :ref:`DICOM identifier | 104 * The ``dicom-uid`` field gives the :ref:`DICOM identifier |
102 <dicom-identifiers>` of the resource that will be accessed. If the | 105 <dicom-identifiers>` of the resource that is accessed. If the |
103 resource is a patient, this field contains the ``PatientID`` DICOM | 106 resource is a patient, this field contains the ``PatientID`` DICOM |
104 tag. For a study, it contains its ``StudyInstanceUID``. For a | 107 tag. For a study, it contains its ``StudyInstanceUID``. For a |
105 series, it contains its ``SeriesInstanceUID``. For an instance, it | 108 series, it contains its ``SeriesInstanceUID``. For an instance, it |
106 contains its ``SOPInstanceUID``. | 109 contains its ``SOPInstanceUID``. |
107 * The ``orthanc-id`` field gives the :ref:`Orthanc identifier | 110 * The ``orthanc-id`` field gives the :ref:`Orthanc identifier |
170 | 173 |
171 Here is a description of these two fields: | 174 Here is a description of these two fields: |
172 | 175 |
173 * ``granted`` tells whether access to the resource is granted | 176 * ``granted`` tells whether access to the resource is granted |
174 (``true``) or not granted (``false``). In the case the user is | 177 (``true``) or not granted (``false``). In the case the user is |
175 accessing a DICOM resource, the access to *all* the levels of | 178 accessing a DICOM resource, the access to *all* the levels of the |
176 the hierarchy above this resource must be granted (conjunction). | 179 hierarchy above this resource must be granted (logical conjunction |
180 over the levels). | |
177 * ``validity`` tells the authorization plugin for how many seconds the | 181 * ``validity`` tells the authorization plugin for how many seconds the |
178 result of the Web service must be cached. If set to ``0`` second, | 182 result of the Web service must be cached. If set to ``0`` second, |
179 the cache entry will never expire. | 183 the cache entry will never expire. |
180 | 184 |
181 **Note:** The source code of the plugin contains a `basic example | 185 **Note:** The source code of the plugin contains a `basic example |
184 | 188 |
185 | 189 |
186 Authentication tokens | 190 Authentication tokens |
187 ^^^^^^^^^^^^^^^^^^^^^ | 191 ^^^^^^^^^^^^^^^^^^^^^ |
188 | 192 |
189 WIP | 193 It is obviously desirable to limit access to the resources depending |
190 | 194 on the user that is logged in. Real-life Web framework such as Django |
191 1.2.1 | 195 would send the identity of the authenticated user either as an HTTP |
192 | 196 header, or as an additional argument for ``GET`` requests. The |
193 Cache | 197 authorization plugin allows to forward these authentication tokens to |
198 the Web service. | |
199 | |
200 To configure the authentication plugin to use some HTTP header, one | |
201 must provide the option ``TokenHttpHeaders`` the configuration file of | |
202 Orthanc as follows:: | |
203 | |
204 { | |
205 "Name" : "MyOrthanc", | |
206 [...] | |
207 "Authorization" : { | |
208 "WebService" : "http://localhost:8000/", | |
209 "TokenHttpHeaders" : [ "hello" ] | |
210 } | |
211 } | |
212 | |
213 .. highlight:: text | |
214 | |
215 In such a situation, if some HTTP client issues the following call:: | |
216 | |
217 # curl -H 'hello: world' http://localhost:8042/patients/6eeded74-75005003-c3ae9738-d4a06a4f-6beedeb8 | |
218 | |
219 .. highlight:: json | |
220 | |
221 Here is the JSON body the Web service would receive:: | |
222 | |
223 { | |
224 "dicom-uid" : "123ABC", | |
225 "level" : "patient", | |
226 "method" : "get", | |
227 "orthanc-id" : "6eeded74-75005003-c3ae9738-d4a06a4f-6beedeb8", | |
228 "token-key" : "hello", | |
229 "token-value" : "world" | |
230 } | |
231 | |
232 .. highlight:: text | |
233 | |
234 Note how the key and the value of the authentication token stored as a | |
235 HTTP header are forwarded to the Web service. | |
236 | |
237 The same mechanism can be used if the authentication token is provided | |
238 as some ``GET`` argument by setting the ``TokenGetArguments`` | |
239 configuration option:: | |
240 | |
241 # curl http://localhost:8042/patients/6eeded74-75005003-c3ae9738-d4a06a4f-6beedeb8?hello=world | |
242 { | |
243 "dicom-uid" : "123ABC", | |
244 "level" : "patient", | |
245 "method" : "get", | |
246 "orthanc-id" : "6eeded74-75005003-c3ae9738-d4a06a4f-6beedeb8", | |
247 "token-key" : "hello", | |
248 "token-value" : "world" | |
249 } | |
250 | |
251 **Note 1:** It is allowed to provide a list of HTTP tokens or a list | |
252 of ``GET`` arguments in the configuration options. In this case, the | |
253 authorization plugin will loop over all the available authentication | |
254 tokens, until it finds one for which the access is granted (logical | |
255 disjunction over the authentication tokens). | |
256 | |
257 **Note 2:** The cache entry that remembers whether some access was | |
258 granted in the past, depends on the value of the token. | |
259 | |
260 **Note 3:** The support of authentication tokens provided as ``GET`` | |
261 arguments requires a version of Orthanc that is above 1.2.1. | |
194 | 262 |
195 | 263 |
196 Full configuration | 264 Full configuration |
197 ------------------ | 265 ------------------ |
198 | 266 |
199 WIP | 267 .. highlight:: json |
200 | 268 |
269 Here is the list of all the configuration options:: | |
270 | |
271 { | |
272 "Name" : "MyOrthanc", | |
273 [...] | |
274 "Authorization" : { | |
275 "WebService" : "http://localhost:8000/", | |
276 "TokenGetArguments" : [ "user" ], | |
277 "TokenHttpHeaders" : [ "hello" ], | |
278 "UncheckedResources" : [ | |
279 "/series", | |
280 "/instances", | |
281 "/patients", | |
282 "/studies", | |
283 "/plugins/explorer.js", | |
284 "/system" | |
285 ], | |
286 "UncheckedFolders" : [ | |
287 "/app/", | |
288 "/web-viewer/app/", | |
289 "/web-viewer/libs/", | |
290 "/wsi/app/" | |
291 ], | |
292 "UncheckedLevels" : [ "study" ] | |
293 } | |
294 } | |
295 | |
296 The following options have been described above: ``WebService``, | |
297 ``TokenGetArguments``, and ``TokenHttpHeaders``. Here are the | |
298 remaining options: | |
299 | |
300 * ``UncheckedResources`` specifies a list of resources for which the | |
301 authentication plugin is not triggered, and to which access is | |
302 always granted. | |
303 | |
304 * ``UncheckedFolders`` is similar to ``UncheckedResources`` for folders: | |
305 Access to all the URIs below the unchecked folders is always granted. | |
306 | |
307 * ``UncheckedLevels`` allows to specify which levels of the | |
308 :ref:`DICOM hierarchy <model-world>` are ignored by the authorization | |
309 plugin. This can be used to reduce the number of calls to the Web | |
310 service. Think for instance about an authorization mechanism that | |
311 simply associates its studies to a set of granted users: In this case, | |
312 the series and instance levels can be ignored. | |
313 |