Mercurial > hg > orthanc-book
comparison Sphinx/source/plugins/authorization.rst @ 97:20b9ecb43eed
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 |