Mercurial > hg > orthanc-book
annotate Sphinx/source/plugins/authorization.rst @ 985:ab706fe809ba
minimal quality message
author | Alain Mazy <am@osimis.io> |
---|---|
date | Thu, 28 Sep 2023 16:43:56 +0200 |
parents | 0b237d3c7f52 |
children | 1316bc62b5d5 |
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 |
851
f282da89c1c1
auth plugin not deprecated anymore
Alain Mazy <am@osimis.io>
parents:
761
diff
changeset
|
4 Advanced authorization plugin |
f282da89c1c1
auth plugin not deprecated anymore
Alain Mazy <am@osimis.io>
parents:
761
diff
changeset
|
5 ============================= |
96
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 |
98 | 9 This **official plugin by Osimis** extends Orthanc with an 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 | |
98 | 12 granted to the user. If access is not granted, the HTTP status code is |
13 set to ``403`` (Forbidden). | |
96
750f7ab733c1
start documentation of authorization
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
14 |
750f7ab733c1
start documentation of authorization
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
15 |
921 | 16 How to get it ? |
17 --------------- | |
18 | |
19 The source code is available on `Mercurial <https://hg.orthanc-server.com/orthanc-authorization/>`__. | |
96
750f7ab733c1
start documentation of authorization
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
20 |
921 | 21 Binaries are included in: |
96
750f7ab733c1
start documentation of authorization
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
22 |
921 | 23 - The `osimis/orthanc Docker image <https://hub.docker.com/r/osimis/orthanc>`__ |
24 - The `Windows Installer <https://www.orthanc-server.com/download-windows.php>`__ | |
25 - The `MacOS packages <https://orthanc.osimis.io/osx/stable/orthancAndPluginsOSX.stable.zip>`__ | |
96
750f7ab733c1
start documentation of authorization
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
26 |
920 | 27 Release notes are available `here <https://hg.orthanc-server.com/orthanc-authorization/file/tip/NEWS>`__. |
28 | |
921 | 29 Compilation instructions are available below. |
30 | |
96
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 Usage |
750f7ab733c1
start documentation of authorization
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
33 ----- |
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 .. highlight:: json |
750f7ab733c1
start documentation of authorization
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
36 |
921 | 37 Once Orthanc is installed, you must change the :ref:`configuration file |
96
750f7ab733c1
start documentation of authorization
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
38 <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
|
39 done by properly modifying the ``Plugins`` option. You could for |
750f7ab733c1
start documentation of authorization
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
40 instance use the following configuration file:: |
750f7ab733c1
start documentation of authorization
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
41 |
750f7ab733c1
start documentation of authorization
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
42 { |
750f7ab733c1
start documentation of authorization
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
43 "Name" : "MyOrthanc", |
750f7ab733c1
start documentation of authorization
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
44 [...] |
750f7ab733c1
start documentation of authorization
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
45 "Plugins" : [ |
750f7ab733c1
start documentation of authorization
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
46 "/home/user/OrthancAuthorization/Build/libOrthancAuthorization.so" |
97 | 47 ], |
48 "Authorization" : { | |
920 | 49 "WebServiceRootUrl" : "http://localhost:8000/", |
878 | 50 "WebServiceUsername": "my-user", |
920 | 51 "WebServicePassword": "my-password" |
97 | 52 } |
96
750f7ab733c1
start documentation of authorization
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
53 } |
750f7ab733c1
start documentation of authorization
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
54 |
750f7ab733c1
start documentation of authorization
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
55 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
|
56 configuration file. |
750f7ab733c1
start documentation of authorization
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
57 |
97 | 58 |
59 Web Service | |
60 ----------- | |
61 | |
62 This section describes how a Web service suitable for the | |
63 authorization plugin can be designed. | |
64 | |
65 | |
66 Incoming request | |
67 ^^^^^^^^^^^^^^^^ | |
68 | |
69 For each HTTP/REST request that Orthanc receives, the plugin will | |
70 issue a set of HTTP ``POST`` requests against the Web service that is | |
71 specified in the configuration file (in the basic configuration file | |
945 | 72 above, the Web service listening at ``http://localhost:8000/tokens/validate`` is |
97 | 73 used). The body of each of those ``POST`` requests is a JSON file |
74 similar to the following one:: | |
75 | |
76 { | |
77 "dicom-uid" : "123ABC", | |
78 "level" : "patient", | |
79 "method" : "get", | |
878 | 80 "orthanc-id" : "6eeded74-75005003-c3ae9738-d4a06a4f-6beedeb8", |
945 | 81 "server-id": null, |
82 "uri": null | |
97 | 83 } |
84 | |
85 In this example, the user is accessing an URI that is related to some | |
98 | 86 DICOM resource, namely a patient whose DICOM identifier is |
87 ``123ABC``. In such a case, the following fields will be set in the | |
88 JSON body: | |
97 | 89 |
90 * The ``level`` field specifies which type of resource the user is | |
91 accessing, according to the :ref:`DICOM model of the real world | |
92 <model-world>`. This field can be set to ``patient``, ``study``, | |
93 ``series``, or ``instance``. | |
94 * The ``method`` field specifies which HTTP method is used by the | |
98 | 95 to-be-authorized request. It can be set to ``get``, ``post``, |
96 ``delete``, or ``put``. | |
97 | 97 * The ``dicom-uid`` field gives the :ref:`DICOM identifier |
98 | 98 <dicom-identifiers>` of the resource that is accessed. If the |
97 | 99 resource is a patient, this field contains the ``PatientID`` DICOM |
100 tag. For a study, it contains its ``StudyInstanceUID``. For a | |
101 series, it contains its ``SeriesInstanceUID``. For an instance, it | |
102 contains its ``SOPInstanceUID``. | |
103 * The ``orthanc-id`` field gives the :ref:`Orthanc identifier | |
104 <orthanc-ids>` of the resource. | |
920 | 105 * The ``server-id`` field contains the value of the ``WebServiceIdentifier`` |
878 | 106 configuration or ``null`` if this configuration is not defined. This allows |
107 the WebService to identity which Orthanc instance is calling it (new in v 0.3.0). | |
97 | 108 |
109 When the user accesses a lower-level resource in the DICOM hierarchy | |
110 (a study, a series or an instance), the authorization plugin will | |
111 issue one separate call to the Web service for each level of the | |
112 hierarchy. For instance, here are the 3 successive requests that are | |
113 issued when accessing some series:: | |
114 | |
115 { | |
116 "dicom-uid" : "123ABC", | |
117 "level" : "patient", | |
118 "method" : "get", | |
119 "orthanc-id" : "6eeded74-75005003-c3ae9738-d4a06a4f-6beedeb8" | |
120 } | |
121 { | |
122 "dicom-uid" : "1.3.51.0.1.1.192.168.29.133.1681753.1681732", | |
123 "level" : "study", | |
124 "method" : "get", | |
125 "orthanc-id" : "6e2c0ec2-5d99c8ca-c1c21cee-79a09605-68391d12" | |
126 } | |
127 { | |
128 "dicom-uid" : "1.3.12.2.1107.5.2.33.37097.2012041612474981424569674.0.0.0", | |
129 "level" : "series", | |
130 "method" : "get", | |
131 "orthanc-id" : "6ca4c9f3-5e895cb3-4d82c6da-09e060fe-9c59f228" | |
132 } | |
133 | |
134 It the user is accessing a URI that is not directly related to an | |
135 individual DICOM resource, the JSON body will look as follows:: | |
136 | |
137 { | |
138 "level" : "system", | |
139 "method" : "get", | |
140 "uri" : "/changes" | |
141 } | |
142 | |
143 In such a situation, the following fields are set: | |
144 | |
145 * The ``level`` field is always set to ``system``. | |
146 * The ``method`` field is the same as above. | |
147 * The ``uri`` field provides the URI that was accessed by the user. | |
148 | |
149 **Important note:** The plugin will transparently parse the URIs of | |
150 the core :ref:`REST API of Orthanc <rest>`, of the :ref:`Web viewer | |
151 plugin <webviewer>`, of the :ref:`DICOMweb plugin <dicomweb>`, and of | |
152 the :ref:`whole-slide imaging plugin <wsi>`. Unrecognized URIs (such | |
153 as those introduced by other plugins) will be handled as a ``system`` | |
154 call. It is possible to introduce parsing support for more plugins by | |
155 modifying the ``DefaultAuthorizationParser`` C++ class in the source | |
156 code of the plugin. | |
157 | |
158 | |
159 Expected answer | |
160 ^^^^^^^^^^^^^^^ | |
161 | |
162 The Web service must answer by sending a JSON file that tells whether | |
163 the access is granted or not to the user. Here is a sample answer:: | |
164 | |
165 { | |
166 "granted": true, | |
167 "validity" : 5 | |
168 } | |
169 | |
170 Here is a description of these two fields: | |
171 | |
172 * ``granted`` tells whether access to the resource is granted | |
173 (``true``) or not granted (``false``). In the case the user is | |
98 | 174 accessing a DICOM resource, the access to *all* the levels of the |
175 hierarchy above this resource must be granted (logical conjunction | |
176 over the levels). | |
97 | 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 | |
449 | 182 <https://hg.orthanc-server.com/orthanc-authorization/file/default/Resources/TestService.js>`__ |
97 | 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 |
98 | 189 It is obviously desirable to limit access to the resources depending |
190 on the user that is logged in. Real-life Web framework such as Django | |
191 would send the identity of the authenticated user either as an HTTP | |
192 header, or as an additional argument for ``GET`` requests. The | |
193 authorization plugin allows to forward these authentication tokens to | |
194 the Web service. | |
195 | |
196 To configure the authentication plugin to use some HTTP header, one | |
197 must provide the option ``TokenHttpHeaders`` the configuration file of | |
198 Orthanc as follows:: | |
199 | |
200 { | |
201 "Name" : "MyOrthanc", | |
202 [...] | |
203 "Authorization" : { | |
204 "WebService" : "http://localhost:8000/", | |
920 | 205 "TokenHttpHeaders" : [ "token" ] |
98 | 206 } |
207 } | |
208 | |
209 .. highlight:: text | |
210 | |
211 In such a situation, if some HTTP client issues the following call:: | |
212 | |
920 | 213 # curl -H 'token: my-token' http://localhost:8042/patients/6eeded74-75005003-c3ae9738-d4a06a4f-6beedeb8 |
98 | 214 |
215 .. highlight:: json | |
216 | |
217 Here is the JSON body the Web service would receive:: | |
96
750f7ab733c1
start documentation of authorization
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
218 |
98 | 219 { |
220 "dicom-uid" : "123ABC", | |
221 "level" : "patient", | |
222 "method" : "get", | |
223 "orthanc-id" : "6eeded74-75005003-c3ae9738-d4a06a4f-6beedeb8", | |
920 | 224 "token-key" : "token", |
225 "token-value" : "my-token" | |
98 | 226 } |
227 | |
228 .. highlight:: text | |
229 | |
230 Note how the key and the value of the authentication token stored as a | |
231 HTTP header are forwarded to the Web service. | |
232 | |
233 The same mechanism can be used if the authentication token is provided | |
234 as some ``GET`` argument by setting the ``TokenGetArguments`` | |
235 configuration option:: | |
97 | 236 |
945 | 237 # curl http://localhost:8042/patients/6eeded74-75005003-c3ae9738-d4a06a4f-6beedeb8?token=my-token |
98 | 238 { |
239 "dicom-uid" : "123ABC", | |
240 "level" : "patient", | |
241 "method" : "get", | |
242 "orthanc-id" : "6eeded74-75005003-c3ae9738-d4a06a4f-6beedeb8", | |
920 | 243 "token-key" : "token", |
244 "token-value" : "my-token" | |
98 | 245 } |
246 | |
247 **Note 1:** It is allowed to provide a list of HTTP tokens or a list | |
248 of ``GET`` arguments in the configuration options. In this case, the | |
249 authorization plugin will loop over all the available authentication | |
250 tokens, until it finds one for which the access is granted (logical | |
251 disjunction over the authentication tokens). | |
252 | |
253 **Note 2:** The cache entry that remembers whether some access was | |
254 granted in the past, depends on the value of the token. | |
255 | |
256 **Note 3:** The support of authentication tokens provided as ``GET`` | |
257 arguments requires a version of Orthanc that is above 1.2.1. | |
97 | 258 |
259 | |
260 Full configuration | |
261 ------------------ | |
262 | |
98 | 263 .. highlight:: json |
264 | |
920 | 265 The full list of configuration is available `here <https://hg.orthanc-server.com/orthanc-authorization/file/tip/Plugin/DefaultConfiguration.json>`__. |
266 | |
98 | 267 Here is the list of all the configuration options:: |
97 | 268 |
98 | 269 { |
945 | 270 "Authorization" : { |
271 // The Base URL of the auth webservice. This is an alias for all 3 next configurations: | |
272 // // "WebServiceUserProfileUrl" : " ROOT /user/get-profile", | |
273 // // "WebServiceTokenValidationUrl" : " ROOT /tokens/validate", | |
274 // // "WebServiceTokenCreationBaseUrl" : " ROOT /tokens/", | |
275 // // "WebServiceTokenDecoderUrl" : " ROOT /tokens/decode", | |
276 // You should define it only if your auth webservice implements all 3 routes ! | |
277 // "WebServiceRootUrl" : "http://change-me:8000/", | |
920 | 278 |
945 | 279 // The URL of the auth webservice route implementing user profile (optional) |
280 // (this configuration was previously named "WebService" and its old name is still accepted | |
281 // for backward compatibility) | |
282 // "WebServiceUserProfileUrl" : "http://change-me:8000/user/profile", | |
920 | 283 |
945 | 284 // The URL of the auth webservice route implementing resource level authorization (optional) |
285 // "WebServiceTokenValidationUrl" : "http://change-me:8000/tokens/validate", | |
286 | |
287 // The Base URL of the auth webservice route to create tokens (optional) | |
288 // "WebServiceTokenCreationBaseUrl" : "http://change-me:8000/tokens/", | |
920 | 289 |
945 | 290 // The URL of the auth webservice route implementing token decoding (optional) |
291 // "WebServiceTokenDecoderUrl": "http://change-me:8000/tokens/decode" | |
920 | 292 |
945 | 293 // The username and password to connect to the webservice (optional) |
294 //"WebServiceUsername": "change-me", | |
295 //"WebServicePassword": "change-me", | |
296 | |
297 // An identifier added to the payload of each request to the auth webservice (optional) | |
298 //"WebServiceIdentifier": "change-me" | |
920 | 299 |
945 | 300 // The name of the HTTP headers that may contain auth tokens |
301 //"TokenHttpHeaders" : [], | |
302 | |
303 // The name of the GET arguments that may contain auth tokens | |
304 //"TokenGetArguments" : [], | |
920 | 305 |
945 | 306 // A list of predefined configurations for well-known plugins |
307 // "StandardConfigurations": [ // new in v 0.4.0 | |
308 // "osimis-web-viewer", | |
309 // "stone-webviewer", | |
310 // "orthanc-explorer-2" | |
311 // ], | |
920 | 312 |
945 | 313 //"UncheckedResources" : [], |
314 //"UncheckedFolders" : [], | |
315 //"CheckedLevel" : "studies", | |
316 //"UncheckedLevels" : [], | |
920 | 317 |
945 | 318 // Definition of required "user-permissions". This can be fully customized. |
319 // You may define other permissions yourself as long as they match the permissions | |
320 // provided in the user-profile route implemented by the auth-service. | |
321 // You may test your regex in https://regex101.com/ by selecting .NET (C#) and removing the leading ^ and trailing $ | |
322 // The default configuration is suitable for Orthanc-Explorer-2 (see https://github.com/orthanc-team/orthanc-auth-service) | |
323 "Permissions" : [ | |
324 ["post", "^/auth/tokens/decode$", ""], | |
325 ["post", "^/tools/lookup$", ""], | |
920 | 326 |
945 | 327 // elemental browsing in OE2 |
328 ["post", "^/tools/find$", "all|view"], | |
329 ["get" , "^/(patients|studies|series|instances)/([a-f0-9-]+)$", "all|view"], | |
330 ... | |
331 ] | |
332 } | |
98 | 333 } |
334 | |
920 | 335 The following options have been described above: ``WebServiceRootUrl``, |
98 | 336 ``TokenGetArguments``, and ``TokenHttpHeaders``. Here are the |
337 remaining options: | |
338 | |
893 | 339 * ``StandardConfigurations`` is a helper configuration to pre-populate |
340 ``UncheckedResources``, ``UncheckedFolders``, ``TokenGetArguments``, | |
341 and ``TokenHttpHeaders`` of well-known plugins. | |
342 Allowed values are ``osimis-web-viewer``, ``stone-webviewer``. | |
343 | |
344 * ``CheckedLevel`` may replace ``UncheckedLevels`` when authorization | |
345 is checked only at one level of the DICOM hierarchy. This is the most | |
346 common use-case. | |
347 | |
98 | 348 * ``UncheckedResources`` specifies a list of resources for which the |
349 authentication plugin is not triggered, and to which access is | |
350 always granted. | |
351 | |
352 * ``UncheckedFolders`` is similar to ``UncheckedResources`` for folders: | |
353 Access to all the URIs below the unchecked folders is always granted. | |
354 | |
355 * ``UncheckedLevels`` allows to specify which levels of the | |
356 :ref:`DICOM hierarchy <model-world>` are ignored by the authorization | |
357 plugin. This can be used to reduce the number of calls to the Web | |
358 service. Think for instance about an authorization mechanism that | |
359 simply associates its studies to a set of granted users: In this case, | |
360 the series and instance levels can be ignored. | |
274 | 361 |
362 | |
893 | 363 Here is a minimal configuration for the :ref:`Stone Web viewer <stone_webviewer>`:: |
364 | |
365 { | |
366 // disable basic authentication since it is replaced by the authorization plugin | |
367 "AuthenticationEnabled": false, | |
368 | |
369 "Authorization" : { | |
920 | 370 "WebServiceTokenValidationUrl" : "http://localhost:8000/shares/validate", |
893 | 371 "StandardConfigurations": [ |
372 "stone-webviewer" | |
373 ], | |
374 "CheckedLevel" : "studies" | |
375 } | |
376 } | |
377 | |
950 | 378 .. _orthanc-explorer-2-authorization: |
920 | 379 |
380 Integration with the Orthanc Explorer 2 | |
381 --------------------------------------- | |
382 | |
950 | 383 This project contains a `complete example <https://github.com/orthanc-team/orthanc-auth-service>`__ |
945 | 384 of a Web services integrating with :ref:`Orthanc Explorer 2 <orthanc-explorer-2>` to implement |
385 user level permissions and sharing of single studies. | |
386 | |
387 This sample also shows how to implement all routes that the webservice might provide: | |
388 | |
389 - ``/tokens/validate`` to validate tokens identifying either a user or granting access to a single resource | |
390 - ``/tokens/{token_type}`` to generate tokens granting access to specific DICOM resources. | |
391 - ``/tokens/decode`` to extract the info from a token | |
392 - ``/user/get-profile`` to return the user profile linked to a given token. This profile | |
393 includes a list of permissions. | |
920 | 394 |
893 | 395 |
274 | 396 .. _orthanc-explorer-authorization: |
397 | |
398 Integration with the Orthanc Explorer | |
399 ------------------------------------- | |
400 | |
401 Starting from Orthanc 1.5.8, you can pass authorization tokens in the url | |
402 search params when opening the Orthanc explorer i.e. | |
403 http://localhost:8042/app/explorer.html?token=1234. This token will be | |
404 included as an HTTP header in every request sent to the Orthanc Rest API. | |
405 It will also be included in the url search params when opening the Orthanc | |
406 or Osimis viewer. | |
407 | |
408 Only 3 tokens name will be recognized and forwarded: ``token``, ``auth-token`` | |
409 and ``authorization``. | |
410 | |
411 Please note that the Orthanc Explorer has not been designed to handle | |
412 the authorization so, when an authorization is not granted, it will simply | |
413 display an empty page or an error message. | |
920 | 414 |
415 | |
416 Compilation | |
417 ----------- | |
418 | |
419 .. highlight:: bash | |
420 | |
421 The procedure to compile this plugin is similar of that for the | |
422 :ref:`core of Orthanc <binaries>`. The following commands should work | |
423 for most UNIX-like distribution (including GNU/Linux):: | |
424 | |
425 $ mkdir Build | |
426 $ cd Build | |
427 $ cmake .. -DSTATIC_BUILD=ON -DCMAKE_BUILD_TYPE=Release | |
428 $ make | |
429 | |
430 The compilation will produce a shared library ``OrthancAuthorization`` | |
431 that contains the authorization plugin. |