Mercurial > hg > orthanc-book
annotate Sphinx/source/plugins/authorization.rst @ 635:8c4b1154cc8b
mobile
| author | Sebastien Jodogne <s.jodogne@gmail.com> |
|---|---|
| date | Mon, 19 Apr 2021 08:43:47 +0200 |
| parents | 6a3d48510b0b |
| children | 525d59a7c198 |
| 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 |
|
556
6a3d48510b0b
Python sample: "Forbid or allow access to REST resources (authorization)", deprecating advanced authorization plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
449
diff
changeset
|
4 Advanced authorization plugin (deprecated) |
|
6a3d48510b0b
Python sample: "Forbid or allow access to REST resources (authorization)", deprecating advanced authorization plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
449
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 |
|
556
6a3d48510b0b
Python sample: "Forbid or allow access to REST resources (authorization)", deprecating advanced authorization plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
449
diff
changeset
|
9 .. note:: This plugin is now deprecated and is not maintained anymore. |
|
6a3d48510b0b
Python sample: "Forbid or allow access to REST resources (authorization)", deprecating advanced authorization plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
449
diff
changeset
|
10 The :ref:`Python plugin <python_authorization>` provides a |
|
6a3d48510b0b
Python sample: "Forbid or allow access to REST resources (authorization)", deprecating advanced authorization plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
449
diff
changeset
|
11 more intuitive and flexible solution. |
|
6a3d48510b0b
Python sample: "Forbid or allow access to REST resources (authorization)", deprecating advanced authorization plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
449
diff
changeset
|
12 |
| 98 | 13 This **official plugin by Osimis** extends Orthanc with an advanced |
| 97 | 14 authorization mechanism. For each incoming REST request to some URI, |
| 15 the plugin will query a Web service to know whether the access is | |
| 98 | 16 granted to the user. If access is not granted, the HTTP status code is |
| 17 set to ``403`` (Forbidden). | |
|
96
750f7ab733c1
start documentation of authorization
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
18 |
| 98 | 19 The `source code of this plugin |
| 449 | 20 <https://hg.orthanc-server.com/orthanc-authorization/file/default>`__ is |
| 361 | 21 freely available under the terms of the AGPLv3 license. |
| 97 | 22 |
|
96
750f7ab733c1
start documentation of authorization
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
23 |
|
750f7ab733c1
start documentation of authorization
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
24 Compilation |
|
750f7ab733c1
start documentation of authorization
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
25 ----------- |
|
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 .. highlight:: bash |
|
750f7ab733c1
start documentation of authorization
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
28 |
| 98 | 29 The procedure to compile this plugin is similar of that for the |
|
96
750f7ab733c1
start documentation of authorization
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
30 :ref:`core of Orthanc <binaries>`. The following commands should work |
|
750f7ab733c1
start documentation of authorization
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
31 for every UNIX-like distribution (including GNU/Linux):: |
|
750f7ab733c1
start documentation of authorization
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
32 |
|
750f7ab733c1
start documentation of authorization
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
33 $ mkdir Build |
|
750f7ab733c1
start documentation of authorization
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
34 $ cd Build |
|
750f7ab733c1
start documentation of authorization
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
35 $ cmake .. -DSTATIC_BUILD=ON -DCMAKE_BUILD_TYPE=Release |
|
750f7ab733c1
start documentation of authorization
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
36 $ make |
|
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 The compilation will produce a shared library ``OrthancAuthorization`` |
|
750f7ab733c1
start documentation of authorization
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
39 that contains the authorization plugin. |
|
750f7ab733c1
start documentation of authorization
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
40 |
|
750f7ab733c1
start documentation of authorization
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
41 Usage |
|
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 |
|
750f7ab733c1
start documentation of authorization
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
44 .. highlight:: json |
|
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 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
|
47 Orthanc is installed, you must change the :ref:`configuration file |
|
750f7ab733c1
start documentation of authorization
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
48 <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
|
49 done by properly modifying the ``Plugins`` option. You could for |
|
750f7ab733c1
start documentation of authorization
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
50 instance use the following configuration file:: |
|
750f7ab733c1
start documentation of authorization
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
51 |
|
750f7ab733c1
start documentation of authorization
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
52 { |
|
750f7ab733c1
start documentation of authorization
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
53 "Name" : "MyOrthanc", |
|
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 "Plugins" : [ |
|
750f7ab733c1
start documentation of authorization
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
56 "/home/user/OrthancAuthorization/Build/libOrthancAuthorization.so" |
| 97 | 57 ], |
| 58 "Authorization" : { | |
| 59 "WebService" : "http://localhost:8000/" | |
| 60 } | |
|
96
750f7ab733c1
start documentation of authorization
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
61 } |
|
750f7ab733c1
start documentation of authorization
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
62 |
|
750f7ab733c1
start documentation of authorization
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
63 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
|
64 configuration file. |
|
750f7ab733c1
start documentation of authorization
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
65 |
| 97 | 66 |
| 67 Web Service | |
| 68 ----------- | |
| 69 | |
| 70 This section describes how a Web service suitable for the | |
| 71 authorization plugin can be designed. | |
| 72 | |
| 73 **Note:** The behavior described in this section is implemented by the | |
| 74 ``AuthorizationWebService`` C++ class in the source code. It is | |
| 75 possible to define a different authorization back-end by deriving | |
| 76 from interface ``IAuthorizationService``. | |
| 77 | |
| 78 | |
| 79 Incoming request | |
| 80 ^^^^^^^^^^^^^^^^ | |
| 81 | |
| 82 For each HTTP/REST request that Orthanc receives, the plugin will | |
| 83 issue a set of HTTP ``POST`` requests against the Web service that is | |
| 84 specified in the configuration file (in the basic configuration file | |
| 85 above, the Web service listening at ``http://localhost:8000/`` is | |
| 86 used). The body of each of those ``POST`` requests is a JSON file | |
| 87 similar to the following one:: | |
| 88 | |
| 89 { | |
| 90 "dicom-uid" : "123ABC", | |
| 91 "level" : "patient", | |
| 92 "method" : "get", | |
| 93 "orthanc-id" : "6eeded74-75005003-c3ae9738-d4a06a4f-6beedeb8" | |
| 94 } | |
| 95 | |
| 96 In this example, the user is accessing an URI that is related to some | |
| 98 | 97 DICOM resource, namely a patient whose DICOM identifier is |
| 98 ``123ABC``. In such a case, the following fields will be set in the | |
| 99 JSON body: | |
| 97 | 100 |
| 101 * The ``level`` field specifies which type of resource the user is | |
| 102 accessing, according to the :ref:`DICOM model of the real world | |
| 103 <model-world>`. This field can be set to ``patient``, ``study``, | |
| 104 ``series``, or ``instance``. | |
| 105 * The ``method`` field specifies which HTTP method is used by the | |
| 98 | 106 to-be-authorized request. It can be set to ``get``, ``post``, |
| 107 ``delete``, or ``put``. | |
| 97 | 108 * The ``dicom-uid`` field gives the :ref:`DICOM identifier |
| 98 | 109 <dicom-identifiers>` of the resource that is accessed. If the |
| 97 | 110 resource is a patient, this field contains the ``PatientID`` DICOM |
| 111 tag. For a study, it contains its ``StudyInstanceUID``. For a | |
| 112 series, it contains its ``SeriesInstanceUID``. For an instance, it | |
| 113 contains its ``SOPInstanceUID``. | |
| 114 * The ``orthanc-id`` field gives the :ref:`Orthanc identifier | |
| 115 <orthanc-ids>` of the resource. | |
| 116 | |
| 117 When the user accesses a lower-level resource in the DICOM hierarchy | |
| 118 (a study, a series or an instance), the authorization plugin will | |
| 119 issue one separate call to the Web service for each level of the | |
| 120 hierarchy. For instance, here are the 3 successive requests that are | |
| 121 issued when accessing some series:: | |
| 122 | |
| 123 { | |
| 124 "dicom-uid" : "123ABC", | |
| 125 "level" : "patient", | |
| 126 "method" : "get", | |
| 127 "orthanc-id" : "6eeded74-75005003-c3ae9738-d4a06a4f-6beedeb8" | |
| 128 } | |
| 129 { | |
| 130 "dicom-uid" : "1.3.51.0.1.1.192.168.29.133.1681753.1681732", | |
| 131 "level" : "study", | |
| 132 "method" : "get", | |
| 133 "orthanc-id" : "6e2c0ec2-5d99c8ca-c1c21cee-79a09605-68391d12" | |
| 134 } | |
| 135 { | |
| 136 "dicom-uid" : "1.3.12.2.1107.5.2.33.37097.2012041612474981424569674.0.0.0", | |
| 137 "level" : "series", | |
| 138 "method" : "get", | |
| 139 "orthanc-id" : "6ca4c9f3-5e895cb3-4d82c6da-09e060fe-9c59f228" | |
| 140 } | |
| 141 | |
| 142 It the user is accessing a URI that is not directly related to an | |
| 143 individual DICOM resource, the JSON body will look as follows:: | |
| 144 | |
| 145 { | |
| 146 "level" : "system", | |
| 147 "method" : "get", | |
| 148 "uri" : "/changes" | |
| 149 } | |
| 150 | |
| 151 In such a situation, the following fields are set: | |
| 152 | |
| 153 * The ``level`` field is always set to ``system``. | |
| 154 * The ``method`` field is the same as above. | |
| 155 * The ``uri`` field provides the URI that was accessed by the user. | |
| 156 | |
| 157 **Important note:** The plugin will transparently parse the URIs of | |
| 158 the core :ref:`REST API of Orthanc <rest>`, of the :ref:`Web viewer | |
| 159 plugin <webviewer>`, of the :ref:`DICOMweb plugin <dicomweb>`, and of | |
| 160 the :ref:`whole-slide imaging plugin <wsi>`. Unrecognized URIs (such | |
| 161 as those introduced by other plugins) will be handled as a ``system`` | |
| 162 call. It is possible to introduce parsing support for more plugins by | |
| 163 modifying the ``DefaultAuthorizationParser`` C++ class in the source | |
| 164 code of the plugin. | |
| 165 | |
| 166 | |
| 167 Expected answer | |
| 168 ^^^^^^^^^^^^^^^ | |
| 169 | |
| 170 The Web service must answer by sending a JSON file that tells whether | |
| 171 the access is granted or not to the user. Here is a sample answer:: | |
| 172 | |
| 173 { | |
| 174 "granted": true, | |
| 175 "validity" : 5 | |
| 176 } | |
| 177 | |
| 178 Here is a description of these two fields: | |
| 179 | |
| 180 * ``granted`` tells whether access to the resource is granted | |
| 181 (``true``) or not granted (``false``). In the case the user is | |
| 98 | 182 accessing a DICOM resource, the access to *all* the levels of the |
| 183 hierarchy above this resource must be granted (logical conjunction | |
| 184 over the levels). | |
| 97 | 185 * ``validity`` tells the authorization plugin for how many seconds the |
| 186 result of the Web service must be cached. If set to ``0`` second, | |
| 187 the cache entry will never expire. | |
| 188 | |
| 189 **Note:** The source code of the plugin contains a `basic example | |
| 449 | 190 <https://hg.orthanc-server.com/orthanc-authorization/file/default/Resources/TestService.js>`__ |
| 97 | 191 of such a Web service written in node.js. |
| 192 | |
| 193 | |
| 194 Authentication tokens | |
| 195 ^^^^^^^^^^^^^^^^^^^^^ | |
|
96
750f7ab733c1
start documentation of authorization
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
196 |
| 98 | 197 It is obviously desirable to limit access to the resources depending |
| 198 on the user that is logged in. Real-life Web framework such as Django | |
| 199 would send the identity of the authenticated user either as an HTTP | |
| 200 header, or as an additional argument for ``GET`` requests. The | |
| 201 authorization plugin allows to forward these authentication tokens to | |
| 202 the Web service. | |
| 203 | |
| 204 To configure the authentication plugin to use some HTTP header, one | |
| 205 must provide the option ``TokenHttpHeaders`` the configuration file of | |
| 206 Orthanc as follows:: | |
| 207 | |
| 208 { | |
| 209 "Name" : "MyOrthanc", | |
| 210 [...] | |
| 211 "Authorization" : { | |
| 212 "WebService" : "http://localhost:8000/", | |
| 213 "TokenHttpHeaders" : [ "hello" ] | |
| 214 } | |
| 215 } | |
| 216 | |
| 217 .. highlight:: text | |
| 218 | |
| 219 In such a situation, if some HTTP client issues the following call:: | |
| 220 | |
| 221 # curl -H 'hello: world' http://localhost:8042/patients/6eeded74-75005003-c3ae9738-d4a06a4f-6beedeb8 | |
| 222 | |
| 223 .. highlight:: json | |
| 224 | |
| 225 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
|
226 |
| 98 | 227 { |
| 228 "dicom-uid" : "123ABC", | |
| 229 "level" : "patient", | |
| 230 "method" : "get", | |
| 231 "orthanc-id" : "6eeded74-75005003-c3ae9738-d4a06a4f-6beedeb8", | |
| 232 "token-key" : "hello", | |
| 233 "token-value" : "world" | |
| 234 } | |
| 235 | |
| 236 .. highlight:: text | |
| 237 | |
| 238 Note how the key and the value of the authentication token stored as a | |
| 239 HTTP header are forwarded to the Web service. | |
| 240 | |
| 241 The same mechanism can be used if the authentication token is provided | |
| 242 as some ``GET`` argument by setting the ``TokenGetArguments`` | |
| 243 configuration option:: | |
| 97 | 244 |
| 98 | 245 # curl http://localhost:8042/patients/6eeded74-75005003-c3ae9738-d4a06a4f-6beedeb8?hello=world |
| 246 { | |
| 247 "dicom-uid" : "123ABC", | |
| 248 "level" : "patient", | |
| 249 "method" : "get", | |
| 250 "orthanc-id" : "6eeded74-75005003-c3ae9738-d4a06a4f-6beedeb8", | |
| 251 "token-key" : "hello", | |
| 252 "token-value" : "world" | |
| 253 } | |
| 254 | |
| 255 **Note 1:** It is allowed to provide a list of HTTP tokens or a list | |
| 256 of ``GET`` arguments in the configuration options. In this case, the | |
| 257 authorization plugin will loop over all the available authentication | |
| 258 tokens, until it finds one for which the access is granted (logical | |
| 259 disjunction over the authentication tokens). | |
| 260 | |
| 261 **Note 2:** The cache entry that remembers whether some access was | |
| 262 granted in the past, depends on the value of the token. | |
| 263 | |
| 264 **Note 3:** The support of authentication tokens provided as ``GET`` | |
| 265 arguments requires a version of Orthanc that is above 1.2.1. | |
| 97 | 266 |
| 267 | |
| 268 Full configuration | |
| 269 ------------------ | |
| 270 | |
| 98 | 271 .. highlight:: json |
| 272 | |
| 273 Here is the list of all the configuration options:: | |
| 97 | 274 |
| 98 | 275 { |
| 276 "Name" : "MyOrthanc", | |
| 277 [...] | |
| 278 "Authorization" : { | |
| 279 "WebService" : "http://localhost:8000/", | |
| 280 "TokenGetArguments" : [ "user" ], | |
| 281 "TokenHttpHeaders" : [ "hello" ], | |
| 282 "UncheckedResources" : [ | |
| 283 "/series", | |
| 284 "/instances", | |
| 285 "/patients", | |
| 286 "/studies", | |
| 287 "/plugins/explorer.js", | |
| 288 "/system" | |
| 289 ], | |
| 290 "UncheckedFolders" : [ | |
| 291 "/app/", | |
| 292 "/web-viewer/app/", | |
| 293 "/web-viewer/libs/", | |
| 294 "/wsi/app/" | |
| 295 ], | |
| 296 "UncheckedLevels" : [ "study" ] | |
| 297 } | |
| 298 } | |
| 299 | |
| 300 The following options have been described above: ``WebService``, | |
| 301 ``TokenGetArguments``, and ``TokenHttpHeaders``. Here are the | |
| 302 remaining options: | |
| 303 | |
| 304 * ``UncheckedResources`` specifies a list of resources for which the | |
| 305 authentication plugin is not triggered, and to which access is | |
| 306 always granted. | |
| 307 | |
| 308 * ``UncheckedFolders`` is similar to ``UncheckedResources`` for folders: | |
| 309 Access to all the URIs below the unchecked folders is always granted. | |
| 310 | |
| 311 * ``UncheckedLevels`` allows to specify which levels of the | |
| 312 :ref:`DICOM hierarchy <model-world>` are ignored by the authorization | |
| 313 plugin. This can be used to reduce the number of calls to the Web | |
| 314 service. Think for instance about an authorization mechanism that | |
| 315 simply associates its studies to a set of granted users: In this case, | |
| 316 the series and instance levels can be ignored. | |
| 274 | 317 |
| 318 | |
| 319 .. _orthanc-explorer-authorization: | |
| 320 | |
| 321 Integration with the Orthanc Explorer | |
| 322 ------------------------------------- | |
| 323 | |
| 324 Starting from Orthanc 1.5.8, you can pass authorization tokens in the url | |
| 325 search params when opening the Orthanc explorer i.e. | |
| 326 http://localhost:8042/app/explorer.html?token=1234. This token will be | |
| 327 included as an HTTP header in every request sent to the Orthanc Rest API. | |
| 328 It will also be included in the url search params when opening the Orthanc | |
| 329 or Osimis viewer. | |
| 330 | |
| 331 Only 3 tokens name will be recognized and forwarded: ``token``, ``auth-token`` | |
| 332 and ``authorization``. | |
| 333 | |
| 334 Please note that the Orthanc Explorer has not been designed to handle | |
| 335 the authorization so, when an authorization is not granted, it will simply | |
| 336 display an empty page or an error message. |