Mercurial > hg > orthanc-book

comparison Sphinx/source/plugins/authorization.rst @ 920:1d9e0aa08fdd

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
auth plugin
author Alain Mazy <am@osimis.io>
date Fri, 17 Mar 2023 16:59:14 +0100
parents 8b48d42665c4
children 33e8cb14142f
comparison
equal deleted inserted replaced
919:5c1ce758f748 920:1d9e0aa08fdd
14 14
15 The `source code of this plugin 15 The `source code of this plugin
16 <https://hg.orthanc-server.com/orthanc-authorization/file/default>`__ is 16 <https://hg.orthanc-server.com/orthanc-authorization/file/default>`__ is
17 freely available under the terms of the AGPLv3 license. 17 freely available under the terms of the AGPLv3 license.
18 18
19 19 Binaries
20 Compilation 20 --------
21 ----------- 21
22 22 Binaries are available:
23 .. highlight:: bash 23
24 24 - in the `Windows Installers <https://www.orthanc-server.com/download-windows.php>`__ .
25 The procedure to compile this plugin is similar of that for the 25 - in the `MacOS package <https://www.orthanc-server.com/static.php?page=download-mac>`__ .
26 :ref:`core of Orthanc <binaries>`. The following commands should work 26 - in the :ref:`osimis/orthanc Docker images <docker-osimis>`
27 for most UNIX-like distribution (including GNU/Linux):: 27
28 28 Release notes
29 $ mkdir Build 29 -------------
30 $ cd Build 30
31 $ cmake .. -DSTATIC_BUILD=ON -DCMAKE_BUILD_TYPE=Release 31 Release notes are available `here <https://hg.orthanc-server.com/orthanc-authorization/file/tip/NEWS>`__.
32 $ make 32
33
34 The compilation will produce a shared library ``OrthancAuthorization``
35 that contains the authorization plugin.
36 33
37 Usage 34 Usage
38 ----- 35 -----
39 36
40 .. highlight:: json 37 .. highlight:: json
50 [...] 47 [...]
51 "Plugins" : [ 48 "Plugins" : [
52 "/home/user/OrthancAuthorization/Build/libOrthancAuthorization.so" 49 "/home/user/OrthancAuthorization/Build/libOrthancAuthorization.so"
53 ], 50 ],
54 "Authorization" : { 51 "Authorization" : {
55 "WebService" : "http://localhost:8000/", 52 "WebServiceRootUrl" : "http://localhost:8000/",
56 "WebServiceUsername": "my-user", 53 "WebServiceUsername": "my-user",
57 "WebServicePassword": "my-password", 54 "WebServicePassword": "my-password"
58 "WebServiceIdentifier": "my-id"
59 } 55 }
60 } 56 }
61 57
62 Orthanc must of course be restarted after the modification of its 58 Orthanc must of course be restarted after the modification of its
63 configuration file. 59 configuration file.
66 Web Service 62 Web Service
67 ----------- 63 -----------
68 64
69 This section describes how a Web service suitable for the 65 This section describes how a Web service suitable for the
70 authorization plugin can be designed. 66 authorization plugin can be designed.
71
72 **Note:** The behavior described in this section is implemented by the
73 ``AuthorizationWebService`` C++ class in the source code. It is
74 possible to define a different authorization back-end by deriving
75 from interface ``IAuthorizationService``.
76 67
77 68
78 Incoming request 69 Incoming request
79 ^^^^^^^^^^^^^^^^ 70 ^^^^^^^^^^^^^^^^
80 71
88 { 79 {
89 "dicom-uid" : "123ABC", 80 "dicom-uid" : "123ABC",
90 "level" : "patient", 81 "level" : "patient",
91 "method" : "get", 82 "method" : "get",
92 "orthanc-id" : "6eeded74-75005003-c3ae9738-d4a06a4f-6beedeb8", 83 "orthanc-id" : "6eeded74-75005003-c3ae9738-d4a06a4f-6beedeb8",
93 "identifier": "my-id" 84 "server-id": "my-id"
94 } 85 }
95 86
96 In this example, the user is accessing an URI that is related to some 87 In this example, the user is accessing an URI that is related to some
97 DICOM resource, namely a patient whose DICOM identifier is 88 DICOM resource, namely a patient whose DICOM identifier is
98 ``123ABC``. In such a case, the following fields will be set in the 89 ``123ABC``. In such a case, the following fields will be set in the
111 tag. For a study, it contains its ``StudyInstanceUID``. For a 102 tag. For a study, it contains its ``StudyInstanceUID``. For a
112 series, it contains its ``SeriesInstanceUID``. For an instance, it 103 series, it contains its ``SeriesInstanceUID``. For an instance, it
113 contains its ``SOPInstanceUID``. 104 contains its ``SOPInstanceUID``.
114 * The ``orthanc-id`` field gives the :ref:`Orthanc identifier 105 * The ``orthanc-id`` field gives the :ref:`Orthanc identifier
115 <orthanc-ids>` of the resource. 106 <orthanc-ids>` of the resource.
116 * The ``identifier`` field contains the value of the ``WebServiceIdentifier`` 107 * The ``server-id`` field contains the value of the ``WebServiceIdentifier``
117 configuration or ``null`` if this configuration is not defined. This allows 108 configuration or ``null`` if this configuration is not defined. This allows
118 the WebService to identity which Orthanc instance is calling it (new in v 0.3.0). 109 the WebService to identity which Orthanc instance is calling it (new in v 0.3.0).
119 110
120 When the user accesses a lower-level resource in the DICOM hierarchy 111 When the user accesses a lower-level resource in the DICOM hierarchy
121 (a study, a series or an instance), the authorization plugin will 112 (a study, a series or an instance), the authorization plugin will
211 { 202 {
212 "Name" : "MyOrthanc", 203 "Name" : "MyOrthanc",
213 [...] 204 [...]
214 "Authorization" : { 205 "Authorization" : {
215 "WebService" : "http://localhost:8000/", 206 "WebService" : "http://localhost:8000/",
216 "TokenHttpHeaders" : [ "hello" ] 207 "TokenHttpHeaders" : [ "token" ]
217 } 208 }
218 } 209 }
219 210
220 .. highlight:: text 211 .. highlight:: text
221 212
222 In such a situation, if some HTTP client issues the following call:: 213 In such a situation, if some HTTP client issues the following call::
223 214
224 # curl -H 'hello: world' http://localhost:8042/patients/6eeded74-75005003-c3ae9738-d4a06a4f-6beedeb8 215 # curl -H 'token: my-token' http://localhost:8042/patients/6eeded74-75005003-c3ae9738-d4a06a4f-6beedeb8
225 216
226 .. highlight:: json 217 .. highlight:: json
227 218
228 Here is the JSON body the Web service would receive:: 219 Here is the JSON body the Web service would receive::
229 220
230 { 221 {
231 "dicom-uid" : "123ABC", 222 "dicom-uid" : "123ABC",
232 "level" : "patient", 223 "level" : "patient",
233 "method" : "get", 224 "method" : "get",
234 "orthanc-id" : "6eeded74-75005003-c3ae9738-d4a06a4f-6beedeb8", 225 "orthanc-id" : "6eeded74-75005003-c3ae9738-d4a06a4f-6beedeb8",
235 "token-key" : "hello", 226 "token-key" : "token",
236 "token-value" : "world" 227 "token-value" : "my-token"
237 } 228 }
238 229
239 .. highlight:: text 230 .. highlight:: text
240 231
241 Note how the key and the value of the authentication token stored as a 232 Note how the key and the value of the authentication token stored as a
249 { 240 {
250 "dicom-uid" : "123ABC", 241 "dicom-uid" : "123ABC",
251 "level" : "patient", 242 "level" : "patient",
252 "method" : "get", 243 "method" : "get",
253 "orthanc-id" : "6eeded74-75005003-c3ae9738-d4a06a4f-6beedeb8", 244 "orthanc-id" : "6eeded74-75005003-c3ae9738-d4a06a4f-6beedeb8",
254 "token-key" : "hello", 245 "token-key" : "token",
255 "token-value" : "world" 246 "token-value" : "my-token"
256 } 247 }
257 248
258 **Note 1:** It is allowed to provide a list of HTTP tokens or a list 249 **Note 1:** It is allowed to provide a list of HTTP tokens or a list
259 of ``GET`` arguments in the configuration options. In this case, the 250 of ``GET`` arguments in the configuration options. In this case, the
260 authorization plugin will loop over all the available authentication 251 authorization plugin will loop over all the available authentication
271 Full configuration 262 Full configuration
272 ------------------ 263 ------------------
273 264
274 .. highlight:: json 265 .. highlight:: json
275 266
267 The full list of configuration is available `here <https://hg.orthanc-server.com/orthanc-authorization/file/tip/Plugin/DefaultConfiguration.json>`__.
268
276 Here is the list of all the configuration options:: 269 Here is the list of all the configuration options::
277 270
278 { 271 {
279 "Name" : "MyOrthanc", 272 "Authorization" : {
280 [...] 273 // The Base URL of the auth webservice. This is an alias for all 3 next configurations:
281 "Authorization" : { 274 // // "WebServiceUserProfileUrl" : " ROOT /user/get-profile",
282 "WebService" : "http://localhost:8000/", 275 // // "WebServiceTokenValidationUrl" : " ROOT /tokens/validate",
283 "WebServiceUsername": "my-user", // new in v 0.3.0 276 // // "WebServiceTokenCreationBaseUrl" : " ROOT /tokens/",
284 "WebServicePassword": "my-password", // new in v 0.3.0 277 // // "WebServiceTokenDecoderUrl" : " ROOT /tokens/decode",
285 "WebServiceIdentifier": "my-id", // new in v 0.3.0 278 // You should define it only if your auth webservice implements all 3 routes !
286 "TokenGetArguments" : [ "user" ], 279 // "WebServiceRootUrl" : "http://change-me:8000/",
287 "TokenHttpHeaders" : [ "hello" ], 280
288 "StandardConfigurations": [ // new in v 0.4.0 281 // The URL of the auth webservice route implementing user profile (optional)
289 "osimis-web-viewer", 282 // (this configuration was previously named "WebService" and its old name is still accepted
290 "stone-webviewer" 283 // for backward compatibility)
291 ], 284 // "WebServiceUserProfileUrl" : "http://change-me:8000/user/profile",
292 "UncheckedResources" : [ 285
293 "/series", 286 // The URL of the auth webservice route implementing resource level authorization (optional)
294 "/instances", 287 // "WebServiceTokenValidationUrl" : "http://change-me:8000/tokens/validate",
295 "/patients", 288
296 "/studies", 289 // The Base URL of the auth webservice route to create tokens (optional)
297 "/plugins/explorer.js", 290 // "WebServiceTokenCreationBaseUrl" : "http://change-me:8000/tokens/",
298 "/system" 291
299 ], 292 // The URL of the auth webservice route implementing token decoding (optional)
300 "UncheckedFolders" : [ 293 // "WebServiceTokenDecoderUrl": "http://change-me:8000/tokens/decode"
301 "/app/", 294
302 "/web-viewer/app/", 295 // The username and password to connect to the webservice (optional)
303 "/web-viewer/libs/", 296 //"WebServiceUsername": "change-me",
304 "/wsi/app/" 297 //"WebServicePassword": "change-me",
305 ], 298
306 "CheckedLevel" : "studies", // new in v 0.4.0 299 // An identifier added to the payload of each request to the auth webservice (optional)
307 "UncheckedLevels" : [ 300 //"WebServiceIdentifier": "change-me"
308 "patients", 301
309 "series", 302 // The name of the HTTP headers that may contain auth tokens
310 "instances" 303 //"TokenHttpHeaders" : [],
311 ] 304
312 } 305 // the name of the GET arguments that may contain auth tokens
313 } 306 //"TokenGetArguments" : [],
314 307
315 The following options have been described above: ``WebService``, 308 // A list of predefined configurations for well-known plugins
309 // "StandardConfigurations": [ // new in v 0.4.0
310 // "osimis-web-viewer",
311 // "stone-webviewer",
312 // "orthanc-explorer-2"
313 // ],
314
315 //"UncheckedResources" : [],
316 //"UncheckedFolders" : [],
317 //"CheckedLevel" : "studies",
318 //"UncheckedLevels" : [],
319
320 // Definition of required "user-permissions". This can be fully customized.
321 // You may define other permissions yourself as long as they match the permissions
322 // provided in the user-profile route implemented by the auth-service.
323 // You may test your regex in https://regex101.com/ by selecting .NET (C#) and removing the leading ^ and trailing $
324 // The default configuration is suitable for Orthanc-Explorer-2 (see TBD sample)
325 "Permissions" : [
326 ["post", "^/auth/tokens/decode$", ""],
327 ["post", "^/tools/lookup$", ""], // currently used to authorize downloads in Stone (to map the StudyInstanceUID into an OrthancID. Not ideal -> we should define a new API that has the resource ID in the path to be able to check it at resource level) but, on another hand, you do not get any Patient information from this route
328
329 // elemental browsing in OE2
330 ["post", "^/tools/find$", "all|view"],
331 ["get" , "^/(patients|studies|series|instances)/([a-f0-9-]+)$", "all|view"],
332 ["get" , "^/(patients|studies|series|instances)/([a-f0-9-]+)/(studies|study|series|instances)$", "all|view"],
333 ["get" , "^/instances/([a-f0-9-]+)/(tags|header)$", "all|view"],
334 ["get" , "^/statistics$", "all|view"],
335
336 // create links to open viewer or download resources
337 ["put", "^/auth/tokens/(viewer-instant-link|meddream-instant-link)$", "all|view"],
338 ["put", "^/auth/tokens/(download-instant-link)$", "all|download"],
339
340 // share a link to open a study
341 ["put", "^/auth/tokens/(stone-viewer-publication|meddream-viewer-publication|osimis-viewer-publication)$", "all|share"],
342
343 // uploads
344 ["post", "^/instances$", "all|upload"],
345
346 // monitor jobs you have created
347 ["get" , "^/jobs/([a-f0-9-]+)$", "all|send|modify|anonymize|q-r-remote-modalities"],
348
349 // interacting with peers/modalities/dicomweb
350 ["post", "^/(peers|modalities)/(.*)/store$", "all|send"],
351 ["get" , "^/(peers|modalities)$", "all|send|q-r-remote-modalities"],
352 ["post", "^/modalities/(.*)/echo$", "all|send|q-r-remote-modalities"],
353 ["post", "^/modalities/(.*)/query$", "all|q-r-remote-modalities"],
354 ["get", "^/queries/([a-f0-9-]+)/answers$", "all|q-r-remote-modalities"],
355 ["post", "^/modalities/(.*)/move$", "all|q-r-remote-modalities"],
356 ["get" , "^/DICOM_WEB_ROOT/servers$", "all|send|q-r-remote-modalities"],
357 ["get" , "^/DICOM_WEB_ROOT/(servers)/(.*)/stow$", "all|send"],
358
359 // modifications/anonymization
360 ["post", "^/(patients|studies|series|instances)/([a-f0-9-]+)/modify(.*)$", "all|modify"],
361 ["post", "^/(patients|studies|series|instances)/([a-f0-9-]+)/anonymize(.*)$", "all|anonymize"],
362
363 // deletes
364 ["delete" , "^/(patients|studies|series|instances)/([a-f0-9-]+)$", "all|delete"],
365
366 // settings
367 ["put", "^/tools/log-level$", "all|settings"],
368 ["get", "^/tools/log-level$", "all|settings"]
369 ]
370 }
371 }
372
373 The following options have been described above: ``WebServiceRootUrl``,
316 ``TokenGetArguments``, and ``TokenHttpHeaders``. Here are the 374 ``TokenGetArguments``, and ``TokenHttpHeaders``. Here are the
317 remaining options: 375 remaining options:
318 376
319 * ``StandardConfigurations`` is a helper configuration to pre-populate 377 * ``StandardConfigurations`` is a helper configuration to pre-populate
320 ``UncheckedResources``, ``UncheckedFolders``, ``TokenGetArguments``, 378 ``UncheckedResources``, ``UncheckedFolders``, ``TokenGetArguments``,
345 { 403 {
346 // disable basic authentication since it is replaced by the authorization plugin 404 // disable basic authentication since it is replaced by the authorization plugin
347 "AuthenticationEnabled": false, 405 "AuthenticationEnabled": false,
348 406
349 "Authorization" : { 407 "Authorization" : {
350 "WebService" : "http://localhost:8000/shares/validate", 408 "WebServiceTokenValidationUrl" : "http://localhost:8000/shares/validate",
351 "StandardConfigurations": [ 409 "StandardConfigurations": [
352 "stone-webviewer" 410 "stone-webviewer"
353 ], 411 ],
354 "CheckedLevel" : "studies" 412 "CheckedLevel" : "studies"
355 } 413 }
356 } 414 }
415
416 .. _orthanc-explorer-authorization:
417
418 Integration with the Orthanc Explorer 2
419 ---------------------------------------
420
421 More info to come soon.
357 422
358 423
359 .. _orthanc-explorer-authorization: 424 .. _orthanc-explorer-authorization:
360 425
361 Integration with the Orthanc Explorer 426 Integration with the Orthanc Explorer
372 and ``authorization``. 437 and ``authorization``.
373 438
374 Please note that the Orthanc Explorer has not been designed to handle 439 Please note that the Orthanc Explorer has not been designed to handle
375 the authorization so, when an authorization is not granted, it will simply 440 the authorization so, when an authorization is not granted, it will simply
376 display an empty page or an error message. 441 display an empty page or an error message.
442
443
444 Compilation
445 -----------
446
447 .. highlight:: bash
448
449 The procedure to compile this plugin is similar of that for the
450 :ref:`core of Orthanc <binaries>`. The following commands should work
451 for most UNIX-like distribution (including GNU/Linux)::
452
453 $ mkdir Build
454 $ cd Build
455 $ cmake .. -DSTATIC_BUILD=ON -DCMAKE_BUILD_TYPE=Release
456 $ make
457
458 The compilation will produce a shared library ``OrthancAuthorization``
459 that contains the authorization plugin.