annotate Sphinx/source/plugins/authorization.rst @ 1113:a588960a72e5 default tip

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