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