Mercurial > hg > orthanc-book
comparison Sphinx/source/plugins/authorization.rst @ 920:1d9e0aa08fdd
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. |