Mercurial > hg > orthanc-book
annotate 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 |
| 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 |
| 98 | 15 The `source code of this plugin |
| 449 | 16 <https://hg.orthanc-server.com/orthanc-authorization/file/default>`__ is |
| 361 | 17 freely available under the terms of the AGPLv3 license. |
| 97 | 18 |
| 920 | 19 Binaries |
| 20 -------- | |
|
96
750f7ab733c1
start documentation of authorization
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
21 |
| 920 | 22 Binaries are available: |
|
96
750f7ab733c1
start documentation of authorization
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
23 |
| 920 | 24 - in the `Windows Installers <https://www.orthanc-server.com/download-windows.php>`__ . |
| 25 - in the `MacOS package <https://www.orthanc-server.com/static.php?page=download-mac>`__ . | |
| 26 - in the :ref:`osimis/orthanc Docker images <docker-osimis>` | |
|
96
750f7ab733c1
start documentation of authorization
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
27 |
| 920 | 28 Release notes |
| 29 ------------- | |
|
96
750f7ab733c1
start documentation of authorization
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
30 |
| 920 | 31 Release notes are available `here <https://hg.orthanc-server.com/orthanc-authorization/file/tip/NEWS>`__. |
| 32 | |
|
96
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 Usage |
|
750f7ab733c1
start documentation of authorization
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
35 ----- |
|
750f7ab733c1
start documentation of authorization
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
36 |
|
750f7ab733c1
start documentation of authorization
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
37 .. highlight:: json |
|
750f7ab733c1
start documentation of authorization
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
38 |
|
750f7ab733c1
start documentation of authorization
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
39 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
|
40 Orthanc is installed, you must change the :ref:`configuration file |
|
750f7ab733c1
start documentation of authorization
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
41 <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
|
42 done by properly modifying the ``Plugins`` option. You could for |
|
750f7ab733c1
start documentation of authorization
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
43 instance use the following configuration file:: |
|
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 { |
|
750f7ab733c1
start documentation of authorization
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
46 "Name" : "MyOrthanc", |
|
750f7ab733c1
start documentation of authorization
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
47 [...] |
|
750f7ab733c1
start documentation of authorization
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
48 "Plugins" : [ |
|
750f7ab733c1
start documentation of authorization
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
49 "/home/user/OrthancAuthorization/Build/libOrthancAuthorization.so" |
| 97 | 50 ], |
| 51 "Authorization" : { | |
| 920 | 52 "WebServiceRootUrl" : "http://localhost:8000/", |
| 878 | 53 "WebServiceUsername": "my-user", |
| 920 | 54 "WebServicePassword": "my-password" |
| 97 | 55 } |
|
96
750f7ab733c1
start documentation of authorization
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
56 } |
|
750f7ab733c1
start documentation of authorization
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
57 |
|
750f7ab733c1
start documentation of authorization
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
58 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
|
59 configuration file. |
|
750f7ab733c1
start documentation of authorization
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
60 |
| 97 | 61 |
| 62 Web Service | |
| 63 ----------- | |
| 64 | |
| 65 This section describes how a Web service suitable for the | |
| 66 authorization plugin can be designed. | |
| 67 | |
| 68 | |
| 69 Incoming request | |
| 70 ^^^^^^^^^^^^^^^^ | |
| 71 | |
| 72 For each HTTP/REST request that Orthanc receives, the plugin will | |
| 73 issue a set of HTTP ``POST`` requests against the Web service that is | |
| 74 specified in the configuration file (in the basic configuration file | |
| 75 above, the Web service listening at ``http://localhost:8000/`` is | |
| 76 used). The body of each of those ``POST`` requests is a JSON file | |
| 77 similar to the following one:: | |
| 78 | |
| 79 { | |
| 80 "dicom-uid" : "123ABC", | |
| 81 "level" : "patient", | |
| 82 "method" : "get", | |
| 878 | 83 "orthanc-id" : "6eeded74-75005003-c3ae9738-d4a06a4f-6beedeb8", |
| 920 | 84 "server-id": "my-id" |
| 97 | 85 } |
| 86 | |
| 87 In this example, the user is accessing an URI that is related to some | |
| 98 | 88 DICOM resource, namely a patient whose DICOM identifier is |
| 89 ``123ABC``. In such a case, the following fields will be set in the | |
| 90 JSON body: | |
| 97 | 91 |
| 92 * The ``level`` field specifies which type of resource the user is | |
| 93 accessing, according to the :ref:`DICOM model of the real world | |
| 94 <model-world>`. This field can be set to ``patient``, ``study``, | |
| 95 ``series``, or ``instance``. | |
| 96 * The ``method`` field specifies which HTTP method is used by the | |
| 98 | 97 to-be-authorized request. It can be set to ``get``, ``post``, |
| 98 ``delete``, or ``put``. | |
| 97 | 99 * The ``dicom-uid`` field gives the :ref:`DICOM identifier |
| 98 | 100 <dicom-identifiers>` of the resource that is accessed. If the |
| 97 | 101 resource is a patient, this field contains the ``PatientID`` DICOM |
| 102 tag. For a study, it contains its ``StudyInstanceUID``. For a | |
| 103 series, it contains its ``SeriesInstanceUID``. For an instance, it | |
| 104 contains its ``SOPInstanceUID``. | |
| 105 * The ``orthanc-id`` field gives the :ref:`Orthanc identifier | |
| 106 <orthanc-ids>` of the resource. | |
| 920 | 107 * The ``server-id`` field contains the value of the ``WebServiceIdentifier`` |
| 878 | 108 configuration or ``null`` if this configuration is not defined. This allows |
| 109 the WebService to identity which Orthanc instance is calling it (new in v 0.3.0). | |
| 97 | 110 |
| 111 When the user accesses a lower-level resource in the DICOM hierarchy | |
| 112 (a study, a series or an instance), the authorization plugin will | |
| 113 issue one separate call to the Web service for each level of the | |
| 114 hierarchy. For instance, here are the 3 successive requests that are | |
| 115 issued when accessing some series:: | |
| 116 | |
| 117 { | |
| 118 "dicom-uid" : "123ABC", | |
| 119 "level" : "patient", | |
| 120 "method" : "get", | |
| 121 "orthanc-id" : "6eeded74-75005003-c3ae9738-d4a06a4f-6beedeb8" | |
| 122 } | |
| 123 { | |
| 124 "dicom-uid" : "1.3.51.0.1.1.192.168.29.133.1681753.1681732", | |
| 125 "level" : "study", | |
| 126 "method" : "get", | |
| 127 "orthanc-id" : "6e2c0ec2-5d99c8ca-c1c21cee-79a09605-68391d12" | |
| 128 } | |
| 129 { | |
| 130 "dicom-uid" : "1.3.12.2.1107.5.2.33.37097.2012041612474981424569674.0.0.0", | |
| 131 "level" : "series", | |
| 132 "method" : "get", | |
| 133 "orthanc-id" : "6ca4c9f3-5e895cb3-4d82c6da-09e060fe-9c59f228" | |
| 134 } | |
| 135 | |
| 136 It the user is accessing a URI that is not directly related to an | |
| 137 individual DICOM resource, the JSON body will look as follows:: | |
| 138 | |
| 139 { | |
| 140 "level" : "system", | |
| 141 "method" : "get", | |
| 142 "uri" : "/changes" | |
| 143 } | |
| 144 | |
| 145 In such a situation, the following fields are set: | |
| 146 | |
| 147 * The ``level`` field is always set to ``system``. | |
| 148 * The ``method`` field is the same as above. | |
| 149 * The ``uri`` field provides the URI that was accessed by the user. | |
| 150 | |
| 151 **Important note:** The plugin will transparently parse the URIs of | |
| 152 the core :ref:`REST API of Orthanc <rest>`, of the :ref:`Web viewer | |
| 153 plugin <webviewer>`, of the :ref:`DICOMweb plugin <dicomweb>`, and of | |
| 154 the :ref:`whole-slide imaging plugin <wsi>`. Unrecognized URIs (such | |
| 155 as those introduced by other plugins) will be handled as a ``system`` | |
| 156 call. It is possible to introduce parsing support for more plugins by | |
| 157 modifying the ``DefaultAuthorizationParser`` C++ class in the source | |
| 158 code of the plugin. | |
| 159 | |
| 160 | |
| 161 Expected answer | |
| 162 ^^^^^^^^^^^^^^^ | |
| 163 | |
| 164 The Web service must answer by sending a JSON file that tells whether | |
| 165 the access is granted or not to the user. Here is a sample answer:: | |
| 166 | |
| 167 { | |
| 168 "granted": true, | |
| 169 "validity" : 5 | |
| 170 } | |
| 171 | |
| 172 Here is a description of these two fields: | |
| 173 | |
| 174 * ``granted`` tells whether access to the resource is granted | |
| 175 (``true``) or not granted (``false``). In the case the user is | |
| 98 | 176 accessing a DICOM resource, the access to *all* the levels of the |
| 177 hierarchy above this resource must be granted (logical conjunction | |
| 178 over the levels). | |
| 97 | 179 * ``validity`` tells the authorization plugin for how many seconds the |
| 180 result of the Web service must be cached. If set to ``0`` second, | |
| 181 the cache entry will never expire. | |
| 182 | |
| 183 **Note:** The source code of the plugin contains a `basic example | |
| 449 | 184 <https://hg.orthanc-server.com/orthanc-authorization/file/default/Resources/TestService.js>`__ |
| 97 | 185 of such a Web service written in node.js. |
| 186 | |
| 187 | |
| 188 Authentication tokens | |
| 189 ^^^^^^^^^^^^^^^^^^^^^ | |
|
96
750f7ab733c1
start documentation of authorization
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
190 |
| 98 | 191 It is obviously desirable to limit access to the resources depending |
| 192 on the user that is logged in. Real-life Web framework such as Django | |
| 193 would send the identity of the authenticated user either as an HTTP | |
| 194 header, or as an additional argument for ``GET`` requests. The | |
| 195 authorization plugin allows to forward these authentication tokens to | |
| 196 the Web service. | |
| 197 | |
| 198 To configure the authentication plugin to use some HTTP header, one | |
| 199 must provide the option ``TokenHttpHeaders`` the configuration file of | |
| 200 Orthanc as follows:: | |
| 201 | |
| 202 { | |
| 203 "Name" : "MyOrthanc", | |
| 204 [...] | |
| 205 "Authorization" : { | |
| 206 "WebService" : "http://localhost:8000/", | |
| 920 | 207 "TokenHttpHeaders" : [ "token" ] |
| 98 | 208 } |
| 209 } | |
| 210 | |
| 211 .. highlight:: text | |
| 212 | |
| 213 In such a situation, if some HTTP client issues the following call:: | |
| 214 | |
| 920 | 215 # curl -H 'token: my-token' http://localhost:8042/patients/6eeded74-75005003-c3ae9738-d4a06a4f-6beedeb8 |
| 98 | 216 |
| 217 .. highlight:: json | |
| 218 | |
| 219 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
|
220 |
| 98 | 221 { |
| 222 "dicom-uid" : "123ABC", | |
| 223 "level" : "patient", | |
| 224 "method" : "get", | |
| 225 "orthanc-id" : "6eeded74-75005003-c3ae9738-d4a06a4f-6beedeb8", | |
| 920 | 226 "token-key" : "token", |
| 227 "token-value" : "my-token" | |
| 98 | 228 } |
| 229 | |
| 230 .. highlight:: text | |
| 231 | |
| 232 Note how the key and the value of the authentication token stored as a | |
| 233 HTTP header are forwarded to the Web service. | |
| 234 | |
| 235 The same mechanism can be used if the authentication token is provided | |
| 236 as some ``GET`` argument by setting the ``TokenGetArguments`` | |
| 237 configuration option:: | |
| 97 | 238 |
| 98 | 239 # curl http://localhost:8042/patients/6eeded74-75005003-c3ae9738-d4a06a4f-6beedeb8?hello=world |
| 240 { | |
| 241 "dicom-uid" : "123ABC", | |
| 242 "level" : "patient", | |
| 243 "method" : "get", | |
| 244 "orthanc-id" : "6eeded74-75005003-c3ae9738-d4a06a4f-6beedeb8", | |
| 920 | 245 "token-key" : "token", |
| 246 "token-value" : "my-token" | |
| 98 | 247 } |
| 248 | |
| 249 **Note 1:** It is allowed to provide a list of HTTP tokens or a list | |
| 250 of ``GET`` arguments in the configuration options. In this case, the | |
| 251 authorization plugin will loop over all the available authentication | |
| 252 tokens, until it finds one for which the access is granted (logical | |
| 253 disjunction over the authentication tokens). | |
| 254 | |
| 255 **Note 2:** The cache entry that remembers whether some access was | |
| 256 granted in the past, depends on the value of the token. | |
| 257 | |
| 258 **Note 3:** The support of authentication tokens provided as ``GET`` | |
| 259 arguments requires a version of Orthanc that is above 1.2.1. | |
| 97 | 260 |
| 261 | |
| 262 Full configuration | |
| 263 ------------------ | |
| 264 | |
| 98 | 265 .. highlight:: json |
| 266 | |
| 920 | 267 The full list of configuration is available `here <https://hg.orthanc-server.com/orthanc-authorization/file/tip/Plugin/DefaultConfiguration.json>`__. |
| 268 | |
| 98 | 269 Here is the list of all the configuration options:: |
| 97 | 270 |
| 98 | 271 { |
| 920 | 272 "Authorization" : { |
| 273 // The Base URL of the auth webservice. This is an alias for all 3 next configurations: | |
| 274 // // "WebServiceUserProfileUrl" : " ROOT /user/get-profile", | |
| 275 // // "WebServiceTokenValidationUrl" : " ROOT /tokens/validate", | |
| 276 // // "WebServiceTokenCreationBaseUrl" : " ROOT /tokens/", | |
| 277 // // "WebServiceTokenDecoderUrl" : " ROOT /tokens/decode", | |
| 278 // You should define it only if your auth webservice implements all 3 routes ! | |
| 279 // "WebServiceRootUrl" : "http://change-me:8000/", | |
| 280 | |
| 281 // The URL of the auth webservice route implementing user profile (optional) | |
| 282 // (this configuration was previously named "WebService" and its old name is still accepted | |
| 283 // for backward compatibility) | |
| 284 // "WebServiceUserProfileUrl" : "http://change-me:8000/user/profile", | |
| 285 | |
| 286 // The URL of the auth webservice route implementing resource level authorization (optional) | |
| 287 // "WebServiceTokenValidationUrl" : "http://change-me:8000/tokens/validate", | |
| 288 | |
| 289 // The Base URL of the auth webservice route to create tokens (optional) | |
| 290 // "WebServiceTokenCreationBaseUrl" : "http://change-me:8000/tokens/", | |
| 291 | |
| 292 // The URL of the auth webservice route implementing token decoding (optional) | |
| 293 // "WebServiceTokenDecoderUrl": "http://change-me:8000/tokens/decode" | |
| 294 | |
| 295 // The username and password to connect to the webservice (optional) | |
| 296 //"WebServiceUsername": "change-me", | |
| 297 //"WebServicePassword": "change-me", | |
| 298 | |
| 299 // An identifier added to the payload of each request to the auth webservice (optional) | |
| 300 //"WebServiceIdentifier": "change-me" | |
| 301 | |
| 302 // The name of the HTTP headers that may contain auth tokens | |
| 303 //"TokenHttpHeaders" : [], | |
| 304 | |
| 305 // the name of the GET arguments that may contain auth tokens | |
| 306 //"TokenGetArguments" : [], | |
| 307 | |
| 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 } | |
| 98 | 371 } |
| 372 | |
| 920 | 373 The following options have been described above: ``WebServiceRootUrl``, |
| 98 | 374 ``TokenGetArguments``, and ``TokenHttpHeaders``. Here are the |
| 375 remaining options: | |
| 376 | |
| 893 | 377 * ``StandardConfigurations`` is a helper configuration to pre-populate |
| 378 ``UncheckedResources``, ``UncheckedFolders``, ``TokenGetArguments``, | |
| 379 and ``TokenHttpHeaders`` of well-known plugins. | |
| 380 Allowed values are ``osimis-web-viewer``, ``stone-webviewer``. | |
| 381 | |
| 382 * ``CheckedLevel`` may replace ``UncheckedLevels`` when authorization | |
| 383 is checked only at one level of the DICOM hierarchy. This is the most | |
| 384 common use-case. | |
| 385 | |
| 98 | 386 * ``UncheckedResources`` specifies a list of resources for which the |
| 387 authentication plugin is not triggered, and to which access is | |
| 388 always granted. | |
| 389 | |
| 390 * ``UncheckedFolders`` is similar to ``UncheckedResources`` for folders: | |
| 391 Access to all the URIs below the unchecked folders is always granted. | |
| 392 | |
| 393 * ``UncheckedLevels`` allows to specify which levels of the | |
| 394 :ref:`DICOM hierarchy <model-world>` are ignored by the authorization | |
| 395 plugin. This can be used to reduce the number of calls to the Web | |
| 396 service. Think for instance about an authorization mechanism that | |
| 397 simply associates its studies to a set of granted users: In this case, | |
| 398 the series and instance levels can be ignored. | |
| 274 | 399 |
| 400 | |
| 893 | 401 Here is a minimal configuration for the :ref:`Stone Web viewer <stone_webviewer>`:: |
| 402 | |
| 403 { | |
| 404 // disable basic authentication since it is replaced by the authorization plugin | |
| 405 "AuthenticationEnabled": false, | |
| 406 | |
| 407 "Authorization" : { | |
| 920 | 408 "WebServiceTokenValidationUrl" : "http://localhost:8000/shares/validate", |
| 893 | 409 "StandardConfigurations": [ |
| 410 "stone-webviewer" | |
| 411 ], | |
| 412 "CheckedLevel" : "studies" | |
| 413 } | |
| 414 } | |
| 415 | |
| 920 | 416 .. _orthanc-explorer-authorization: |
| 417 | |
| 418 Integration with the Orthanc Explorer 2 | |
| 419 --------------------------------------- | |
| 420 | |
| 421 More info to come soon. | |
| 422 | |
| 893 | 423 |
| 274 | 424 .. _orthanc-explorer-authorization: |
| 425 | |
| 426 Integration with the Orthanc Explorer | |
| 427 ------------------------------------- | |
| 428 | |
| 429 Starting from Orthanc 1.5.8, you can pass authorization tokens in the url | |
| 430 search params when opening the Orthanc explorer i.e. | |
| 431 http://localhost:8042/app/explorer.html?token=1234. This token will be | |
| 432 included as an HTTP header in every request sent to the Orthanc Rest API. | |
| 433 It will also be included in the url search params when opening the Orthanc | |
| 434 or Osimis viewer. | |
| 435 | |
| 436 Only 3 tokens name will be recognized and forwarded: ``token``, ``auth-token`` | |
| 437 and ``authorization``. | |
| 438 | |
| 439 Please note that the Orthanc Explorer has not been designed to handle | |
| 440 the authorization so, when an authorization is not granted, it will simply | |
| 441 display an empty page or an error message. | |
| 920 | 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. |