Mercurial > hg > orthanc-book

comparison Sphinx/source/plugins/authorization.rst @ 97:20b9ecb43eed

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
doc
author Sebastien Jodogne <s.jodogne@gmail.com>
date Mon, 27 Mar 2017 17:50:08 +0200
parents 750f7ab733c1
children b56083f38695
comparison
equal deleted inserted replaced
96:750f7ab733c1 97:20b9ecb43eed
5 ============================= 5 =============================
6 6
7 .. contents:: 7 .. contents::
8 8
9 This **official plugin by Osimis** extends Orthanc with advanced 9 This **official plugin by Osimis** extends Orthanc with advanced
10 authorization mechanism. 10 authorization mechanism. For each incoming REST request to some URI,
11 11 the plugin will query a Web service to know whether the access is
12 For each incoming REST request to some URI, the plugin will query a 12 granted to the user.
13 Web service to know whether the access is granted to the 13
14 user. Authorization credentials can be retrieved either from a GET 14 Source code is `freely available under the terms of the AGPLv3 license
15 argument, or from a HTTP header. 15 <https://bitbucket.org/osimis/orthanc-authorization>`__.
16
16 17
17 Compilation 18 Compilation
18 ----------- 19 -----------
19 20
20 .. highlight:: bash 21 .. highlight:: bash
45 { 46 {
46 "Name" : "MyOrthanc", 47 "Name" : "MyOrthanc",
47 [...] 48 [...]
48 "Plugins" : [ 49 "Plugins" : [
49 "/home/user/OrthancAuthorization/Build/libOrthancAuthorization.so" 50 "/home/user/OrthancAuthorization/Build/libOrthancAuthorization.so"
50 ] 51 ],
51 } 52 "Authorization" : {
52 53 "WebService" : "http://localhost:8000/"
53 .. highlight:: text 54 }
55 }
54 56
55 Orthanc must of course be restarted after the modification of its 57 Orthanc must of course be restarted after the modification of its
56 configuration file. 58 configuration file.
57 59
58 Configuration 60
59 ------------- 61 Web Service
62 -----------
63
64 This section describes how a Web service suitable for the
65 authorization plugin can be designed.
66
67 **Note:** The behavior described in this section is implemented by the
68 ``AuthorizationWebService`` C++ class in the source code. It is
69 possible to define a different authorization back-end by deriving
70 from interface ``IAuthorizationService``.
71
72
73 Incoming request
74 ^^^^^^^^^^^^^^^^
75
76 For each HTTP/REST request that Orthanc receives, the plugin will
77 issue a set of HTTP ``POST`` requests against the Web service that is
78 specified in the configuration file (in the basic configuration file
79 above, the Web service listening at ``http://localhost:8000/`` is
80 used). The body of each of those ``POST`` requests is a JSON file
81 similar to the following one::
82
83 {
84 "dicom-uid" : "123ABC",
85 "level" : "patient",
86 "method" : "get",
87 "orthanc-id" : "6eeded74-75005003-c3ae9738-d4a06a4f-6beedeb8"
88 }
89
90 In this example, the user is accessing an URI that is related to some
91 DICOM resource, namely a patient whose identifier is ``123ABC``. In
92 such a case, the following fields will be set in the JSON body:
93
94 * The ``level`` field specifies which type of resource the user is
95 accessing, according to the :ref:`DICOM model of the real world
96 <model-world>`. This field can be set to ``patient``, ``study``,
97 ``series``, or ``instance``.
98 * The ``method`` field specifies which HTTP method is used by the
99 to-be-authorized request. It can be set ``get``, ``post``,
100 ``delete`` or ``put``.
101 * The ``dicom-uid`` field gives the :ref:`DICOM identifier
102 <dicom-identifiers>` of the resource that will be accessed. If the
103 resource is a patient, this field contains the ``PatientID`` DICOM
104 tag. For a study, it contains its ``StudyInstanceUID``. For a
105 series, it contains its ``SeriesInstanceUID``. For an instance, it
106 contains its ``SOPInstanceUID``.
107 * The ``orthanc-id`` field gives the :ref:`Orthanc identifier
108 <orthanc-ids>` of the resource.
109
110 When the user accesses a lower-level resource in the DICOM hierarchy
111 (a study, a series or an instance), the authorization plugin will
112 issue one separate call to the Web service for each level of the
113 hierarchy. For instance, here are the 3 successive requests that are
114 issued when accessing some series::
115
116 {
117 "dicom-uid" : "123ABC",
118 "level" : "patient",
119 "method" : "get",
120 "orthanc-id" : "6eeded74-75005003-c3ae9738-d4a06a4f-6beedeb8"
121 }
122 {
123 "dicom-uid" : "1.3.51.0.1.1.192.168.29.133.1681753.1681732",
124 "level" : "study",
125 "method" : "get",
126 "orthanc-id" : "6e2c0ec2-5d99c8ca-c1c21cee-79a09605-68391d12"
127 }
128 {
129 "dicom-uid" : "1.3.12.2.1107.5.2.33.37097.2012041612474981424569674.0.0.0",
130 "level" : "series",
131 "method" : "get",
132 "orthanc-id" : "6ca4c9f3-5e895cb3-4d82c6da-09e060fe-9c59f228"
133 }
134
135 It the user is accessing a URI that is not directly related to an
136 individual DICOM resource, the JSON body will look as follows::
137
138 {
139 "level" : "system",
140 "method" : "get",
141 "uri" : "/changes"
142 }
143
144 In such a situation, the following fields are set:
145
146 * The ``level`` field is always set to ``system``.
147 * The ``method`` field is the same as above.
148 * The ``uri`` field provides the URI that was accessed by the user.
149
150 **Important note:** The plugin will transparently parse the URIs of
151 the core :ref:`REST API of Orthanc <rest>`, of the :ref:`Web viewer
152 plugin <webviewer>`, of the :ref:`DICOMweb plugin <dicomweb>`, and of
153 the :ref:`whole-slide imaging plugin <wsi>`. Unrecognized URIs (such
154 as those introduced by other plugins) will be handled as a ``system``
155 call. It is possible to introduce parsing support for more plugins by
156 modifying the ``DefaultAuthorizationParser`` C++ class in the source
157 code of the plugin.
158
159
160 Expected answer
161 ^^^^^^^^^^^^^^^
162
163 The Web service must answer by sending a JSON file that tells whether
164 the access is granted or not to the user. Here is a sample answer::
165
166 {
167 "granted": true,
168 "validity" : 5
169 }
170
171 Here is a description of these two fields:
172
173 * ``granted`` tells whether access to the resource is granted
174 (``true``) or not granted (``false``). In the case the user is
175 accessing a DICOM resource, the access to *all* the levels of
176 the hierarchy above this resource must be granted (conjunction).
177 * ``validity`` tells the authorization plugin for how many seconds the
178 result of the Web service must be cached. If set to ``0`` second,
179 the cache entry will never expire.
180
181 **Note:** The source code of the plugin contains a `basic example
182 <https://bitbucket.org/osimis/orthanc-authorization/src/default/Resources/TestService.js>`__
183 of such a Web service written in node.js.
184
185
186 Authentication tokens
187 ^^^^^^^^^^^^^^^^^^^^^
60 188
61 WIP 189 WIP
62 190
191 1.2.1
192
193 Cache
194
195
196 Full configuration
197 ------------------
198
199 WIP
200