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