Mercurial > hg > orthanc-book
annotate Sphinx/source/plugins/authorization.rst @ 1112:ad26102adccc default tip
fix broken link
| author | Alain Mazy <am@orthanc.team> |
|---|---|
| date | Wed, 23 Oct 2024 16:52:30 +0200 |
| parents | d57ca05c6478 |
| children |
| 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, |
| 1020 | 11 the plugin will query an external Web service to check whether the access should be granted. |
| 12 If access is not granted, the HTTP status code is set to ``403`` (Forbidden). | |
| 13 | |
| 14 The request must include either an ``HTTP header`` or a ``GET argument`` that may | |
| 15 either identify a ``user`` or an access to a single DICOM ``resource`` (an instance, | |
| 16 a series, a study or a patient). | |
| 17 | |
| 18 In the text below, the ``HTTP header`` and the ``GET argument`` is named the ``token``. | |
| 19 | |
|
96
750f7ab733c1
start documentation of authorization
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
20 |
|
1007
7fbd7a6a1d56
added note about deprecation of advanced authorization plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
1004
diff
changeset
|
21 **Status:** This plugin was `deprecated |
|
7fbd7a6a1d56
added note about deprecation of advanced authorization plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
1004
diff
changeset
|
22 <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
|
23 between 2020 and 2022, but its active development has been resumed |
| 1020 | 24 since May 2022 and is intensively used in the `orthanc-auth-service <https://github.com/orthanc-team/orthanc-auth-service>`__ |
| 25 project that provides user permissions and sharing of single studies. | |
|
1007
7fbd7a6a1d56
added note about deprecation of advanced authorization plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
1004
diff
changeset
|
26 |
|
96
750f7ab733c1
start documentation of authorization
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
27 |
| 921 | 28 How to get it ? |
| 29 --------------- | |
| 30 | |
|
991
1316bc62b5d5
migration to UCLouvain servers
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
950
diff
changeset
|
31 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
|
32 |
| 921 | 33 Binaries are included in: |
|
96
750f7ab733c1
start documentation of authorization
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
34 |
|
1023
5d4701d8fe28
replaced osimis/orthanc by orthancteam/orthanc
Alain Mazy <am@osimis.io>
parents:
1020
diff
changeset
|
35 - The `orthancteam/orthanc Docker image <https://hub.docker.com/r/orthancteam/orthanc>`__ |
| 921 | 36 - 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
|
37 - 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
|
38 |
|
991
1316bc62b5d5
migration to UCLouvain servers
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
950
diff
changeset
|
39 Release notes are available `here <https://orthanc.uclouvain.be/hg/orthanc-authorization/file/tip/NEWS>`__. |
| 920 | 40 |
| 921 | 41 Compilation instructions are available below. |
| 42 | |
|
96
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 Usage |
|
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 .. highlight:: json |
|
750f7ab733c1
start documentation of authorization
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
48 |
| 921 | 49 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
|
50 <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
|
51 done by properly modifying the ``Plugins`` option. You could for |
|
750f7ab733c1
start documentation of authorization
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
52 instance use the following configuration file:: |
|
750f7ab733c1
start documentation of authorization
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
53 |
|
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 "Name" : "MyOrthanc", |
|
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 "Plugins" : [ |
|
750f7ab733c1
start documentation of authorization
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
58 "/home/user/OrthancAuthorization/Build/libOrthancAuthorization.so" |
| 97 | 59 ], |
| 60 "Authorization" : { | |
| 1020 | 61 // .. all options are document below |
| 97 | 62 } |
|
96
750f7ab733c1
start documentation of authorization
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
63 } |
|
750f7ab733c1
start documentation of authorization
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
64 |
|
750f7ab733c1
start documentation of authorization
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
65 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
|
66 configuration file. |
|
750f7ab733c1
start documentation of authorization
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
67 |
| 97 | 68 |
| 1020 | 69 User based authorization vs resource based tokens |
| 70 ------------------------------------------------- | |
| 71 | |
| 72 The plugin can work in 2 modes that can be combined: | |
| 97 | 73 |
| 1020 | 74 * **User based authorization** is used e.g. in :ref:`Orthanc Explorer 2 <orthanc-explorer-2>` |
| 75 to allow various ``actions`` based on ``permissions`` defined in a ``user profile``. | |
| 76 * **Resource based authorization** is used e.g. to share a link that | |
| 77 grants access to a single DICOM resource (e.g. a study). | |
| 97 | 78 |
| 79 | |
| 1020 | 80 External Web Service |
| 81 -------------------- | |
| 82 | |
| 83 This section describes how an external Web service suitable for the | |
| 84 authorization plugin can be designed. | |
| 97 | 85 |
| 86 For each HTTP/REST request that Orthanc receives, the plugin will | |
| 87 issue a set of HTTP ``POST`` requests against the Web service that is | |
| 1020 | 88 specified in the configuration file. |
| 89 | |
| 90 Depending on the kind of authorization you'd like to use, your Web service shall | |
| 91 implement part or all of these routes: | |
| 92 | |
| 93 - ``/tokens/validate`` to validate tokens identifying a DICOM **resource** | |
| 94 - ``/tokens/{token_type}`` to generate tokens granting access to specific DICOM **resources**. | |
| 95 - ``/tokens/decode`` to extract the info from a **resource** token | |
| 96 - ``/user/get-profile`` to return the **user profile** linked to a given token. This profile | |
| 97 must include a list of permissions. | |
| 98 | |
| 99 These routes url may be defined individually or globally in the configuration file. | |
| 100 | |
| 101 **Note:** The source code of the plugin contains a `basic example | |
| 102 <https://orthanc.uclouvain.be/hg/orthanc-authorization/file/default/Resources/TestService.js>`__ | |
| 103 of a simple Web service that implements only the ``validate`` route. | |
| 104 | |
| 105 The `orthanc-auth-service project <https://github.com/orthanc-team/orthanc-auth-service>`__ | |
| 106 provides a full implementation of the Web service. It notably contains a `definition of | |
| 107 all the requests and responses <https://github.com/orthanc-team/orthanc-auth-service/blob/main/sources/orthanc_auth_service/shares/models.py>`__ used between the plugin and the Web service. | |
| 108 | |
| 109 | |
| 110 Resource tokens generation: /tokens/{token_type} | |
| 111 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
| 112 | |
| 113 The tokens can actually be generated anywhere, e.g, in the `orthanc-auth-service project <https://github.com/orthanc-team/orthanc-auth-service>`__, | |
| 114 the **user tokens** are generated by KeyCloak. But a user logged into Orthanc can also | |
| 115 generate links to share a single study in Orthanc Explorer 2. In this case, OE2 will | |
| 116 call the authorization plugin that will forward the call to the Authorization Web Service (this route) | |
| 117 that will generate a **resource token**. | |
| 118 | |
| 119 The implementation of this route is optional and only required if you want to generate share links | |
| 120 in OE2. | |
| 121 | |
| 122 Your Web service receives this kind of POST requests:: | |
| 123 | |
| 124 { | |
| 125 "id": "your-optional-id", | |
| 126 "type": "depending-on-your-web-service", // will instruct your Web service how to generate the url to access the resource (if relevant) | |
| 127 "resources": [ // a list of Orthanc resources that can be identified either by the orthanc id | |
| 128 // or their DICOM ID (SOPInstanceUID, StudyInstanceUID, PatientID, SeriesInstanceUID) | |
| 129 { | |
| 130 "dicom-uid": "1.2.3", | |
| 131 "orthanc-id": "6eeded74-75005003-c3ae9738-d4a06a4f-6beedeb8", | |
| 132 "level": "study", // one of "patient", "study", "series", "instance", "system" | |
| 133 "url": "/optional/system/url" // only for system level resources | |
| 134 } | |
| 135 ], | |
| 136 "expiration-date": "2027-04-23T19:25:43.511Z", // optional | |
| 137 "validity-duration": 3600 // validity duration (in seconds) | |
| 138 } | |
| 139 | |
| 140 And your Web service must provide this kind of responses:: | |
| 97 | 141 |
| 142 { | |
| 1020 | 143 "request": {}, // a copy of the request |
| 144 "token": "my-super-safe-resource-token", // the token that will identify the resource | |
| 145 "url": "http://optional.link.to/ui/app/token-landing.html?token=my-super-safe-resource-token" // optional: url to access the shared resource | |
| 146 } | |
| 147 | |
| 148 | |
| 149 Resource tokens decoding: /tokens/decode | |
| 150 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
| 151 | |
| 152 This route is quite specific to OE2 shares: When a user opens OE2 with a **resource token**, | |
| 153 it usually lands on a specific landing page that calls this route to extract the content | |
| 154 of the token to know e.g which viewer must be opened to display the DICOM resource or to check | |
| 155 if the token has expired. | |
| 156 | |
| 157 The implementation of this route is optional and only required if you want to open the share links | |
| 158 in OE2. | |
| 159 | |
| 160 Your Web service receives this kind of POST requests:: | |
| 161 | |
| 162 { | |
| 163 "token-key": "token", // the name of the token (HTTP Header or GET argument) | |
| 164 "token-value": "my-super-safe-resource-token" // the token to be decoded | |
| 165 } | |
| 166 | |
| 167 And your Web service must provide this kind of responses:: | |
| 168 | |
| 169 { | |
| 170 "token-type": "depending-on-your-web-service", // the type of the token | |
| 171 "redirect-url": "http://your.domain.com/orthanc/stone-webviewer/index.html?study=...&token=....", | |
| 172 "error-code": "expired" // optional; one of "expired", "invalid", "unknown". This is used to display | |
| 173 // a friendly user message in OE2 in case of error. | |
| 174 } | |
| 175 | |
| 176 | |
| 177 Resource tokens validation: /tokens/validate | |
| 178 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
| 179 | |
| 180 This route must absolutely be implemented if you want to implement **resource** based authentication, | |
| 181 For each query that is made through Orthanc, Orthanc will use the response of this route | |
| 182 to grant access or not to the API route. | |
| 183 | |
| 184 Consider that a user issues this request:: | |
| 185 | |
| 186 curl -H "auth-token-header: my-super-safe-resource-token" http://localhost:8042/patients/6eeded74-75005003-c3ae9738-d4a06a4f-6beedeb8 | |
| 187 | |
| 188 Your Web service receives this kind of POST requests:: | |
| 189 | |
| 190 { | |
| 191 "dicom-uid": "123ABC", | |
| 192 "orthanc-id": "6eeded74-75005003-c3ae9738-d4a06a4f-6beedeb8", | |
| 193 "level": "patient", | |
| 194 "method": "get", | |
| 195 "token-key": "auth-token-header", | |
| 196 "token-value": "my-super-safe-resource-token", | |
| 197 "server-id": "optional-id-ex-orthanc-public" | |
| 97 | 198 } |
| 199 | |
| 200 In this example, the user is accessing an URI that is related to some | |
| 98 | 201 DICOM resource, namely a patient whose DICOM identifier is |
| 1020 | 202 ``123ABC`` and orthanc id ``6eeded74-75005003-c3ae9738-d4a06a4f-6beedeb8``. |
| 203 In such a case, the following fields will be set in the JSON body: | |
| 97 | 204 |
| 205 * The ``level`` field specifies which type of resource the user is | |
| 206 accessing, according to the :ref:`DICOM model of the real world | |
| 207 <model-world>`. This field can be set to ``patient``, ``study``, | |
| 208 ``series``, or ``instance``. | |
| 209 * The ``method`` field specifies which HTTP method is used by the | |
| 98 | 210 to-be-authorized request. It can be set to ``get``, ``post``, |
| 211 ``delete``, or ``put``. | |
| 97 | 212 * The ``dicom-uid`` field gives the :ref:`DICOM identifier |
| 98 | 213 <dicom-identifiers>` of the resource that is accessed. If the |
| 97 | 214 resource is a patient, this field contains the ``PatientID`` DICOM |
| 215 tag. For a study, it contains its ``StudyInstanceUID``. For a | |
| 216 series, it contains its ``SeriesInstanceUID``. For an instance, it | |
| 217 contains its ``SOPInstanceUID``. | |
| 218 * The ``orthanc-id`` field gives the :ref:`Orthanc identifier | |
| 219 <orthanc-ids>` of the resource. | |
| 920 | 220 * The ``server-id`` field contains the value of the ``WebServiceIdentifier`` |
| 878 | 221 configuration or ``null`` if this configuration is not defined. This allows |
| 222 the WebService to identity which Orthanc instance is calling it (new in v 0.3.0). | |
| 97 | 223 |
| 224 | |
| 225 It the user is accessing a URI that is not directly related to an | |
| 226 individual DICOM resource, the JSON body will look as follows:: | |
| 227 | |
| 228 { | |
| 229 "level" : "system", | |
| 230 "method" : "get", | |
| 1020 | 231 "uri" : "/changes", |
| 232 "token-key": "auth-token-header", | |
| 233 "token-value": "my-super-safe-resource-token", | |
| 234 "server-id": "optional-id-ex-orthanc-public" | |
| 97 | 235 } |
| 236 | |
| 237 In such a situation, the following fields are set: | |
| 238 | |
| 239 * The ``level`` field is always set to ``system``. | |
| 240 * The ``method`` field is the same as above. | |
| 241 * The ``uri`` field provides the URI that was accessed by the user. | |
| 1020 | 242 |
| 97 | 243 |
| 1020 | 244 And your Web service must provide this kind of responses:: |
| 97 | 245 |
| 246 { | |
| 247 "granted": true, | |
| 1020 | 248 "validity": 60 |
| 97 | 249 } |
| 250 | |
| 1020 | 251 Where: |
| 97 | 252 |
| 253 * ``granted`` tells whether access to the resource is granted | |
| 254 (``true``) or not granted (``false``). In the case the user is | |
| 98 | 255 accessing a DICOM resource, the access to *all* the levels of the |
| 256 hierarchy above this resource must be granted (logical conjunction | |
| 257 over the levels). | |
| 97 | 258 * ``validity`` tells the authorization plugin for how many seconds the |
| 259 result of the Web service must be cached. If set to ``0`` second, | |
| 1020 | 260 the cache entry will never expire. By setting a ``validity`` duration, |
| 261 Orthanc can cache the response to avoid asking the same question | |
| 262 thousands of times to your web-service e.g. when opening a study in a web viewer. | |
| 97 | 263 |
| 264 | |
|
96
750f7ab733c1
start documentation of authorization
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
265 |
| 1020 | 266 **Note** depending on your configuration, the Web service might receive multiple requests, one for |
| 267 each level of the hierarchy that must be checked (see in the configuration below). E.G:: | |
|
96
750f7ab733c1
start documentation of authorization
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff
changeset
|
268 |
| 98 | 269 { |
| 270 "dicom-uid" : "123ABC", | |
| 271 "level" : "patient", | |
| 272 "method" : "get", | |
| 273 "orthanc-id" : "6eeded74-75005003-c3ae9738-d4a06a4f-6beedeb8", | |
| 1020 | 274 ... |
| 275 } | |
| 276 { | |
| 277 "dicom-uid" : "1.3.51.0.1.1.192.168.29.133.1681753.1681732", | |
| 278 "level" : "study", | |
| 279 "method" : "get", | |
| 280 "orthanc-id" : "6e2c0ec2-5d99c8ca-c1c21cee-79a09605-68391d12", | |
| 281 ... | |
| 282 } | |
| 283 { | |
| 284 "dicom-uid" : "1.3.12.2.1107.5.2.33.37097.2012041612474981424569674.0.0.0", | |
| 285 "level" : "series", | |
| 286 "method" : "get", | |
| 287 "orthanc-id" : "6ca4c9f3-5e895cb3-4d82c6da-09e060fe-9c59f228", | |
| 288 ... | |
| 98 | 289 } |
| 290 | |
| 1020 | 291 |
| 292 **Important note:** The plugin will transparently parse the URIs of | |
| 293 the core :ref:`REST API of Orthanc <rest>` and the most common official plugins. | |
| 294 Unrecognized URIs (such | |
| 295 as those introduced by other non official plugins) will be handled as a ``system`` | |
| 296 call. It is possible to introduce parsing support for more plugins by | |
| 297 modifying the ``DefaultAuthorizationParser`` C++ class in the source | |
| 298 code of the plugin. | |
| 299 | |
| 300 | |
| 301 | |
| 302 | |
| 303 Get User profile: /user/get-profile | |
| 304 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
| 305 | |
| 306 This route must absolutely be implemented if you want to implement **user** permissions based authorization. | |
| 98 | 307 |
| 1020 | 308 Note that **user** based authorization has been implemented with the OE2 integration in mind. |
| 309 It has currently not been designed for other use cases. | |
| 310 | |
| 311 For each query that is made through Orthanc, if no **resource token** granting access to the route was found, | |
| 312 Orthanc will possibly try to retrieve a **user profile** to identify a possible user for this token. | |
| 313 | |
| 314 Consider that a user issues this request:: | |
| 315 | |
| 316 curl -H "auth-token-header: my-super-safe-user-token" http://localhost:8042/studies/6e2c0ec2-5d99c8ca-c1c21cee-79a09605-68391d12 | |
| 98 | 317 |
| 1020 | 318 |
| 319 Your Web service receives this kind of POST requests:: | |
| 320 | |
| 321 { | |
| 322 "token-key": "auth-token-header", | |
| 323 "token-value": "my-super-safe-user-token", | |
| 324 "server-id": "optional-id-ex-orthanc-public" | |
| 325 } | |
| 326 | |
| 327 And your Web service must provide this kind of responses:: | |
| 97 | 328 |
| 98 | 329 { |
| 1020 | 330 "name": "John Who", // The name of the user (e.g. to display in OE2) |
| 331 "authorized-labels": [ // A list of labels the user has access to. | |
| 332 "my-label", // use "*" to grant access to all labels | |
| 333 "his-label" | |
| 334 ], | |
| 335 "permissions": [ // A list of permissions for this user | |
| 336 "view", | |
| 337 "upload", | |
| 338 "..." | |
| 339 ] | |
| 340 "validity": 60 // the validity duration (in seconds) of this response. | |
| 341 } | |
| 342 | |
| 343 By setting a ``validity`` duration, Orthanc can cache the response to avoid asking the same question | |
| 344 thousands of times to your web-service e.g. when opening a study in a web viewer. | |
| 345 | |
| 346 If a list of ``authorized-labels`` has been returned, the authorization plugin will add a label filter to each call to | |
| 347 ``tools/find`` to include only the labels the user has access to or, when accessing a specific DICOM resource, the plugin will | |
| 348 check that the resource has one of these ``authorized-labels``. | |
| 349 | |
| 350 The list of ``permissions`` are defined in the plugin configuration. | |
| 351 E.g, the following configuration defines that a user must have either the ``all`` or the ``view`` permission to | |
| 352 be authorized to issue GET requests to ``/studies/{orthanc-id}``, provided that the study has one of the labels | |
| 353 that is listed in the ``authorized-labels`` :: | |
| 354 | |
| 355 ["get" , "^/(patients|studies|series|instances)/([a-f0-9-]+)$", "all|view"], | |
| 356 | |
| 357 | |
| 358 This permission defines that a user must have either the ``all`` or the ``share`` permission to be | |
| 359 authorized to issue a PUT request to generate a **resource token** to share a single DICOM study:: | |
| 360 | |
| 361 ["put", "^/auth/tokens/(stone-viewer-publication||ohif-viewer-publication)$", "all|share"], | |
| 362 | |
| 363 | |
| 364 | |
| 365 | |
| 366 Authentication tokens | |
| 367 ^^^^^^^^^^^^^^^^^^^^^ | |
| 368 | |
| 369 To configure the authentication plugin to use some HTTP header or GET argument, one | |
| 370 must provide these options:: | |
| 371 | |
| 372 { | |
| 373 "Authorization" : { | |
| 374 ... | |
| 375 "TokenHttpHeaders" : [ "token-header" ], | |
| 376 "TokenGetArguments" : [ "token-in-url" ], | |
| 377 } | |
| 98 | 378 } |
| 379 | |
| 380 **Note 1:** It is allowed to provide a list of HTTP tokens or a list | |
| 381 of ``GET`` arguments in the configuration options. In this case, the | |
| 382 authorization plugin will loop over all the available authentication | |
| 383 tokens, until it finds one for which the access is granted (logical | |
| 384 disjunction over the authentication tokens). | |
| 385 | |
| 386 **Note 2:** The cache entry that remembers whether some access was | |
| 387 granted in the past, depends on the value of the token. | |
| 388 | |
| 389 **Note 3:** The support of authentication tokens provided as ``GET`` | |
| 390 arguments requires a version of Orthanc that is above 1.2.1. | |
| 97 | 391 |
| 392 | |
| 393 Full configuration | |
| 394 ------------------ | |
| 395 | |
| 98 | 396 .. highlight:: json |
| 397 | |
|
991
1316bc62b5d5
migration to UCLouvain servers
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
950
diff
changeset
|
398 The full list of configuration is available `here <https://orthanc.uclouvain.be/hg/orthanc-authorization/file/tip/Plugin/DefaultConfiguration.json>`__. |
| 920 | 399 |
| 98 | 400 Here is the list of all the configuration options:: |
| 97 | 401 |
| 98 | 402 { |
| 945 | 403 "Authorization" : { |
| 1020 | 404 // The Base URL of the auth webservice. This is an alias for all next 4 configurations: |
| 945 | 405 // // "WebServiceUserProfileUrl" : " ROOT /user/get-profile", |
| 406 // // "WebServiceTokenValidationUrl" : " ROOT /tokens/validate", | |
| 407 // // "WebServiceTokenCreationBaseUrl" : " ROOT /tokens/", | |
| 408 // // "WebServiceTokenDecoderUrl" : " ROOT /tokens/decode", | |
| 1020 | 409 // You should define it only if your auth webservice implements all 4 routes ! |
| 945 | 410 // "WebServiceRootUrl" : "http://change-me:8000/", |
| 920 | 411 |
| 945 | 412 // The URL of the auth webservice route implementing user profile (optional) |
| 413 // "WebServiceUserProfileUrl" : "http://change-me:8000/user/profile", | |
| 920 | 414 |
| 945 | 415 // The URL of the auth webservice route implementing resource level authorization (optional) |
| 416 // "WebServiceTokenValidationUrl" : "http://change-me:8000/tokens/validate", | |
| 417 | |
| 418 // The Base URL of the auth webservice route to create tokens (optional) | |
| 419 // "WebServiceTokenCreationBaseUrl" : "http://change-me:8000/tokens/", | |
| 920 | 420 |
| 945 | 421 // The URL of the auth webservice route implementing token decoding (optional) |
| 422 // "WebServiceTokenDecoderUrl": "http://change-me:8000/tokens/decode" | |
| 920 | 423 |
| 945 | 424 // The username and password to connect to the webservice (optional) |
| 425 //"WebServiceUsername": "change-me", | |
| 426 //"WebServicePassword": "change-me", | |
| 427 | |
| 1020 | 428 // An identifier added to the payload of each request to the auth webservice (optional). |
| 429 // It is used to identify the Orthanc instance that is sending the request to the auth webservice | |
| 945 | 430 //"WebServiceIdentifier": "change-me" |
| 920 | 431 |
| 945 | 432 // The name of the HTTP headers that may contain auth tokens |
| 433 //"TokenHttpHeaders" : [], | |
| 434 | |
| 435 // The name of the GET arguments that may contain auth tokens | |
| 436 //"TokenGetArguments" : [], | |
| 920 | 437 |
| 945 | 438 // A list of predefined configurations for well-known plugins |
| 439 // "StandardConfigurations": [ // new in v 0.4.0 | |
| 440 // "osimis-web-viewer", | |
| 441 // "stone-webviewer", | |
| 1039 | 442 // "orthanc-explorer-2", |
| 443 // "ohif" | |
| 945 | 444 // ], |
| 920 | 445 |
| 945 | 446 //"UncheckedResources" : [], |
| 447 //"UncheckedFolders" : [], | |
| 448 //"CheckedLevel" : "studies", | |
| 449 //"UncheckedLevels" : [], | |
| 920 | 450 |
| 945 | 451 // Definition of required "user-permissions". This can be fully customized. |
| 452 // You may define other permissions yourself as long as they match the permissions | |
| 453 // provided in the user-profile route implemented by the auth-service. | |
| 454 // You may test your regex in https://regex101.com/ by selecting .NET (C#) and removing the leading ^ and trailing $ | |
| 455 // The default configuration is suitable for Orthanc-Explorer-2 (see https://github.com/orthanc-team/orthanc-auth-service) | |
| 456 "Permissions" : [ | |
| 457 ["post", "^/auth/tokens/decode$", ""], | |
| 458 ["post", "^/tools/lookup$", ""], | |
| 920 | 459 |
| 945 | 460 // elemental browsing in OE2 |
| 461 ["post", "^/tools/find$", "all|view"], | |
| 462 ["get" , "^/(patients|studies|series|instances)/([a-f0-9-]+)$", "all|view"], | |
| 463 ... | |
| 464 ] | |
| 465 } | |
| 98 | 466 } |
| 467 | |
| 920 | 468 The following options have been described above: ``WebServiceRootUrl``, |
| 98 | 469 ``TokenGetArguments``, and ``TokenHttpHeaders``. Here are the |
| 470 remaining options: | |
| 471 | |
| 893 | 472 * ``StandardConfigurations`` is a helper configuration to pre-populate |
| 473 ``UncheckedResources``, ``UncheckedFolders``, ``TokenGetArguments``, | |
| 474 and ``TokenHttpHeaders`` of well-known plugins. | |
| 475 Allowed values are ``osimis-web-viewer``, ``stone-webviewer``. | |
| 476 | |
| 477 * ``CheckedLevel`` may replace ``UncheckedLevels`` when authorization | |
| 478 is checked only at one level of the DICOM hierarchy. This is the most | |
| 479 common use-case. | |
| 480 | |
| 98 | 481 * ``UncheckedResources`` specifies a list of resources for which the |
| 482 authentication plugin is not triggered, and to which access is | |
| 483 always granted. | |
| 484 | |
| 1019 | 485 * ``UncheckedFolders`` specifies a list of root paths for which the |
| 486 authentication plugin is not triggered when receiving a GET request. | |
| 487 This is actually mainly used to grant access to static resources e.g. | |
| 488 HTML and JS resources from plugins like :ref:`Orthanc Explorer 2 <orthanc-explorer-2>`. | |
| 98 | 489 |
| 490 * ``UncheckedLevels`` allows to specify which levels of the | |
| 491 :ref:`DICOM hierarchy <model-world>` are ignored by the authorization | |
| 492 plugin. This can be used to reduce the number of calls to the Web | |
| 493 service. Think for instance about an authorization mechanism that | |
| 494 simply associates its studies to a set of granted users: In this case, | |
| 495 the series and instance levels can be ignored. | |
| 274 | 496 |
| 1020 | 497 * ``WebServiceIdentifier`` is used to identify the Orthanc instance that |
| 498 is calling the Web service. This value is copied in ``server-id`` in | |
| 499 the requests to the web services (new in v 0.3.0). | |
| 500 | |
| 274 | 501 |
| 893 | 502 Here is a minimal configuration for the :ref:`Stone Web viewer <stone_webviewer>`:: |
| 503 | |
| 504 { | |
| 505 // disable basic authentication since it is replaced by the authorization plugin | |
| 506 "AuthenticationEnabled": false, | |
| 507 | |
| 508 "Authorization" : { | |
| 920 | 509 "WebServiceTokenValidationUrl" : "http://localhost:8000/shares/validate", |
| 893 | 510 "StandardConfigurations": [ |
| 511 "stone-webviewer" | |
| 512 ], | |
| 513 "CheckedLevel" : "studies" | |
| 514 } | |
| 515 } | |
| 516 | |
| 950 | 517 .. _orthanc-explorer-2-authorization: |
| 920 | 518 |
| 519 Integration with the Orthanc Explorer 2 | |
| 520 --------------------------------------- | |
| 521 | |
| 950 | 522 This project contains a `complete example <https://github.com/orthanc-team/orthanc-auth-service>`__ |
| 945 | 523 of a Web services integrating with :ref:`Orthanc Explorer 2 <orthanc-explorer-2>` to implement |
| 524 user level permissions and sharing of single studies. | |
| 525 | |
| 1020 | 526 This sample also shows how to implement the 4 routes that the webservice might provide. |
| 920 | 527 |
| 893 | 528 |
| 274 | 529 .. _orthanc-explorer-authorization: |
| 530 | |
| 531 Integration with the Orthanc Explorer | |
| 532 ------------------------------------- | |
| 533 | |
|
1004
17bf6fafb884
added links to uclouvain
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
993
diff
changeset
|
534 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
|
535 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
|
536 ``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
|
537 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
|
538 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
|
539 when opening the Orthanc or :ref:`Osimis Web viewer |
|
17bf6fafb884
added links to uclouvain
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
993
diff
changeset
|
540 <osimis_webviewer>`. |
| 274 | 541 |
| 542 Only 3 tokens name will be recognized and forwarded: ``token``, ``auth-token`` | |
| 543 and ``authorization``. | |
| 544 | |
| 545 Please note that the Orthanc Explorer has not been designed to handle | |
| 546 the authorization so, when an authorization is not granted, it will simply | |
| 547 display an empty page or an error message. | |
| 920 | 548 |
| 549 | |
| 550 Compilation | |
| 551 ----------- | |
| 552 | |
| 553 .. highlight:: bash | |
| 554 | |
| 555 The procedure to compile this plugin is similar of that for the | |
| 556 :ref:`core of Orthanc <binaries>`. The following commands should work | |
| 557 for most UNIX-like distribution (including GNU/Linux):: | |
| 558 | |
| 559 $ mkdir Build | |
| 560 $ cd Build | |
| 561 $ cmake .. -DSTATIC_BUILD=ON -DCMAKE_BUILD_TYPE=Release | |
| 562 $ make | |
| 563 | |
| 564 The compilation will produce a shared library ``OrthancAuthorization`` | |
| 565 that contains the authorization plugin. |