|
254
|
1 .. _google:
|
|
|
2
|
|
|
3
|
|
|
4 Google Cloud Platform plugin
|
|
|
5 ============================
|
|
|
6
|
|
|
7 .. contents::
|
|
|
8
|
|
255
|
9
|
|
|
10 Introduction
|
|
|
11 ------------
|
|
|
12
|
|
|
13 Osimis freely provides the `source code
|
|
257
|
14 <https://bitbucket.org/osimis/orthanc-gcp/src>`__ of a plugin to
|
|
|
15 interface Orthanc with the Healthcare API of `Google Cloud Platform
|
|
259
|
16 (GCP) <https://en.wikipedia.org/wiki/Google_Cloud_Platform>`__ through
|
|
|
17 `DICOMweb <https://www.dicomstandard.org/dicomweb/>`__.
|
|
255
|
18
|
|
259
|
19 This GCP plugin notably enables the upload of DICOM images using
|
|
|
20 STOW-RS, the querying of the cloud content using QIDO-RS, and the
|
|
|
21 retrieval of remote content using WADO-RS. These operations can be
|
|
255
|
22 possibly scripted thanks to the REST API of Orthanc.
|
|
|
23
|
|
|
24 Concretely, the GCP plugin manages the credentials to Google Cloud
|
|
|
25 Platform. It requires the official :ref:`DICOMweb plugin <dicomweb>`
|
|
|
26 to be installed. As soon as Orthanc is started, the GCP plugin
|
|
259
|
27 automatically acquires and refreshes the `access tokens
|
|
255
|
28 <https://cloud.google.com/docs/authentication/>`__, transparently
|
|
|
29 updating the remote :ref:`DICOMweb servers <dicomweb-client-config>`
|
|
259
|
30 that are known to the DICOMweb plugin. The access tokens can
|
|
255
|
31 be derived either from service accounts, or from user accounts.
|
|
|
32
|
|
|
33 This page makes the assumption that you have created a Google Cloud
|
|
|
34 Platform project, in which you have enabled the `Healthcare API
|
|
|
35 <https://cloud.google.com/healthcare/>`__, and in which you have
|
|
|
36 created a `DICOM store
|
|
|
37 <https://cloud.google.com/healthcare/docs/how-tos/dicom>`__.
|
|
|
38
|
|
|
39 Under the hood, the GCP plugin is built on the top of the official
|
|
|
40 `Google Cloud Platform C++ Client Libraries
|
|
|
41 <https://github.com/googleapis/google-cloud-cpp>`__.
|
|
|
42
|
|
|
43
|
|
|
44
|
|
|
45 Compilation
|
|
|
46 -----------
|
|
|
47
|
|
|
48 .. highlight:: text
|
|
|
49
|
|
|
50 The procedure to compile the GCP plugin is similar of that for the
|
|
|
51 :ref:`core of Orthanc <compiling>`. The following commands should work
|
|
|
52 on any recent UNIX-like distribution (including GNU/Linux)::
|
|
|
53
|
|
|
54 $ mkdir Build
|
|
|
55 $ cd Build
|
|
|
56 $ cmake .. -DSTATIC_BUILD=ON -DCMAKE_BUILD_TYPE=Release
|
|
|
57 $ make
|
|
|
58
|
|
|
59 The compilation produces a shared library
|
|
259
|
60 ``OrthancGoogleCloudPlatform`` that contains the GCP
|
|
255
|
61 plugin. Pre-compiled binaries for Microsoft Windows `are available
|
|
|
62 <http://www.orthanc-server.com/browse.php?path=/plugin-google-cloud>`__,
|
|
|
63 and are included in the `Windows installers
|
|
|
64 <https://www.orthanc-server.com/download-windows.php>`__.
|
|
|
65
|
|
|
66
|
|
|
67
|
|
|
68 Configuration
|
|
|
69 -------------
|
|
|
70
|
|
|
71
|
|
|
72 Common parameters
|
|
|
73 ^^^^^^^^^^^^^^^^^
|
|
|
74
|
|
|
75 As explained above, the GCP plugin requires the :ref:`official
|
|
|
76 DICOMweb plugin <dicomweb>` to be installed (with version above
|
|
259
|
77 1.0). All the communications with Google Cloud Platform are done using
|
|
|
78 the DICOMweb plugin, and the responsibility of the GCP plugin is to
|
|
|
79 aquire and periodically refresh the access tokens whose lifetime is
|
|
|
80 limited.
|
|
255
|
81
|
|
259
|
82 Obtaining the access tokens for Google Cloud Platform necessitates a
|
|
|
83 sequence of HTTPS requests. As a consequence, the Orthanc
|
|
255
|
84 :ref:`configuration options <configuration>` must specify how the
|
|
259
|
85 authenticity of the Google servers is verified. You have two
|
|
255
|
86 possibilities to that end:
|
|
|
87
|
|
|
88 1. Disabling the verification of the remote servers (**not recommended
|
|
|
89 in production**). This is done by setting option ``HttpsVerifyPeers``
|
|
|
90 to ``false``.
|
|
|
91
|
|
|
92 2. Providing a list of `trusted Certificate Authorities (CA)
|
|
|
93 <https://curl.haxx.se/docs/sslcerts.html>`__ to the HTTPS client
|
|
|
94 that is internally used by Orthanc (namely, `cURL
|
|
|
95 <https://en.wikipedia.org/wiki/CURL>`__). This is done by properly
|
|
|
96 setting ``HttpsVerifyPeers`` option, so that it points to a file
|
|
|
97 containing a store of CA certificates. Depending on your operating
|
|
|
98 system, this file can be found as follows:
|
|
|
99
|
|
|
100 * On Debian-based system, the standard file
|
|
|
101 ``/etc/ssl/certs/ca-certificates.crt`` can be used.
|
|
|
102 * On other systems, the cURL project provides `CA certificates
|
|
|
103 <https://curl.haxx.se/docs/caextract.html>`__ that are extracted
|
|
|
104 from Mozilla.
|
|
|
105
|
|
259
|
106 Note that to debug HTTPS communications, you have the possibility of
|
|
|
107 setting the ``HttpVerbose`` configuration option of Orthanc to
|
|
|
108 ``true``. It is also useful to run Orthanc in ``--verbose`` mode
|
|
|
109 (check out :ref:`this page <log>`).
|
|
255
|
110
|
|
254
|
111
|
|
|
112
|
|
255
|
113 Service account
|
|
|
114 ^^^^^^^^^^^^^^^
|
|
|
115
|
|
|
116 As explained on the `Google documentation
|
|
|
117 <https://cloud.google.com/docs/authentication/#service_accounts>`__,
|
|
|
118 *"a service account is a Google account that represents an
|
|
|
119 application, as opposed to representing an end user"*. This is
|
|
|
120 presumably the most common situation in the case of Orthanc.
|
|
|
121
|
|
|
122 You first have to `create a service account
|
|
|
123 <https://cloud.google.com/docs/authentication/getting-started#creating_a_service_account>`__
|
|
|
124 for your application. This will produce a JSON file (say,
|
|
|
125 ``dicom-osimis.json``) that you have to store securely on the server
|
|
|
126 that will run Orthanc.
|
|
|
127
|
|
|
128 .. highlight:: json
|
|
|
129
|
|
|
130 Secondly, you have to modify the :ref:`Orthanc configuration
|
|
|
131 <configuration>` in order to provide the GCP plugin with your service
|
|
|
132 account file and with the parameters of your `DICOM store
|
|
|
133 <https://cloud.google.com/healthcare/docs/how-tos/dicom>`__. Here is a
|
|
256
|
134 sample, minimalist configuration of Orthanc::
|
|
255
|
135
|
|
|
136 {
|
|
|
137 "HttpsCACertificates": "/etc/ssl/certs/ca-certificates.crt",
|
|
|
138 "Plugins" : [ "." ],
|
|
|
139 "GoogleCloudPlatform" : {
|
|
|
140 "Accounts": {
|
|
|
141 "my-google" : {
|
|
|
142 "Project" : "osimis-test",
|
|
|
143 "Location" : "europe-west2",
|
|
|
144 "Dataset" : "test",
|
|
|
145 "DicomStore" : "dicom",
|
|
|
146 "ServiceAccountFile" : "dicom-osimis.json"
|
|
|
147 }
|
|
|
148 }
|
|
|
149 }
|
|
|
150 }
|
|
|
151
|
|
|
152
|
|
|
153 In this example, once the GCP plugin has succeeded to authenticate
|
|
|
154 using the service account, the DICOMweb plugin will provide access to
|
|
|
155 the cloud DICOM store at URI ``/dicom-web/servers/my-google/`` of the
|
|
|
156 REST API of Orthanc.
|
|
|
157
|
|
|
158
|
|
|
159 User account
|
|
|
160 ^^^^^^^^^^^^
|
|
|
161
|
|
|
162 User account is an alternative to service account, and can be used
|
|
|
163 *"when the application needs to access resources on behalf of an end
|
|
|
164 user"* (check out the `Google documentation
|
|
|
165 <https://cloud.google.com/docs/authentication/#user_accounts>`__).
|
|
|
166
|
|
|
167 .. highlight:: json
|
|
|
168
|
|
|
169 The easiest way of setting up a user account is through the `gcloud
|
|
|
170 command-line tool <https://cloud.google.com/sdk/gcloud/>`__.
|
|
256
|
171 `Google's quick-starts
|
|
255
|
172 <https://cloud.google.com/sdk/docs/quickstarts>`__ explain how to
|
|
|
173 initialize the environment depending on your operating system (check
|
|
|
174 out the "Initialize the SDK" sections, which essentially boil down to
|
|
|
175 calling ``gcloud init``).
|
|
|
176
|
|
|
177
|
|
|
178 .. highlight:: bash
|
|
|
179
|
|
|
180 Once the ``gcloud init`` command-line has been invoked, you can
|
|
259
|
181 extract credentials to be used by Orthanc by typing the following
|
|
|
182 command::
|
|
255
|
183
|
|
|
184 $ gcloud auth print-access-token --format json
|
|
|
185
|
|
|
186
|
|
|
187 .. highlight:: json
|
|
|
188
|
|
|
189 This command produces JSON file containing all the required
|
|
|
190 information, that can be written to a file (say,
|
|
256
|
191 ``dicom-user.json``). Given this file, here is a sample, minimalist
|
|
255
|
192 configuration of Orthanc::
|
|
|
193
|
|
|
194 {
|
|
|
195 "HttpsCACertificates": "/etc/ssl/certs/ca-certificates.crt",
|
|
|
196 "Plugins" : [ "." ],
|
|
|
197 "GoogleCloudPlatform" : {
|
|
|
198 "Accounts": {
|
|
|
199 "my-google" : {
|
|
|
200 "Project" : "osimis-test",
|
|
|
201 "Location" : "europe-west2",
|
|
|
202 "Dataset" : "test",
|
|
|
203 "DicomStore" : "dicom",
|
|
|
204 "AuthorizedUserFile" : "dicom-osimis.json"
|
|
|
205 }
|
|
|
206 }
|
|
|
207 }
|
|
|
208 }
|
|
|
209
|
|
|
210 In this example, once the GCP plugin has succeeded to authenticate
|
|
|
211 using the user account, the DICOMweb plugin will provide access to the
|
|
|
212 cloud DICOM store at URI ``/dicom-web/servers/my-google/`` of the REST
|
|
|
213 API of Orthanc.
|
|
|
214
|
|
|
215
|
|
|
216 .. highlight:: bash
|
|
|
217
|
|
|
218 Note that only 3 fields in the JSON file produced by the ``gcloud auth
|
|
259
|
219 print-access-token`` command are required: ``client_id``,
|
|
|
220 ``client_secret``, and ``refresh_token``. Instead of using the full
|
|
|
221 JSON file, you can extract only these fields, e.g. using the `jq
|
|
255
|
222 <https://stedolan.github.io/jq/>`__ command-line tool::
|
|
|
223
|
|
|
224 $ gcloud auth print-access-token --format json | jq '{ AuthorizedUserClientId: .client_id, AuthorizedUserClientSecret:.client_secret, AuthorizedUserRefreshToken:.refresh_token }'
|
|
|
225 {
|
|
|
226 "AuthorizedUserClientId": "XXXXXXXXXX.apps.googleusercontent.com",
|
|
|
227 "AuthorizedUserClientSecret": "ZmssLNXXXXXX",
|
|
|
228 "AuthorizedUserRefreshToken": "1/e2ngXXXXXX"
|
|
|
229 }
|
|
|
230
|
|
|
231
|
|
|
232 .. highlight:: json
|
|
|
233
|
|
259
|
234 These fields can then be copied/pasted as follows in order to create a
|
|
|
235 configuration for Orthanc that is equivalent to the one using the
|
|
|
236 separate JSON file::
|
|
255
|
237
|
|
|
238 {
|
|
|
239 "HttpsCACertificates": "/etc/ssl/certs/ca-certificates.crt",
|
|
|
240 "Plugins" : [ "." ],
|
|
|
241 "GoogleCloudPlatform" : {
|
|
|
242 "Accounts": {
|
|
|
243 "my-google" : {
|
|
|
244 "Project" : "osimis-test",
|
|
|
245 "Location" : "europe-west2",
|
|
|
246 "Dataset" : "test",
|
|
|
247 "DicomStore" : "dicom",
|
|
|
248 "AuthorizedUserClientId": "XXXXXXXXXX.apps.googleusercontent.com",
|
|
|
249 "AuthorizedUserClientSecret": "ZmssLNXXXXXX",
|
|
|
250 "AuthorizedUserRefreshToken": "1/e2ngXXXXXX"
|
|
|
251 }
|
|
|
252 }
|
|
|
253 }
|
|
|
254 }
|
|
259
|
255
|
|
|
256
|
|
|
257 Advanced options
|
|
|
258 ^^^^^^^^^^^^^^^^
|
|
|
259
|
|
|
260 .. highlight:: json
|
|
|
261
|
|
|
262 Some advanced configuration options are available as well, as
|
|
|
263 summarized in this excerpt::
|
|
|
264
|
|
|
265 {
|
|
|
266 ...
|
|
|
267 // In seconds, must be large enough to send/receive your largest studies
|
|
|
268 // using WADO or STOW, depending on the speed of your Internet connection
|
|
|
269 "HttpTimeout" : 600,
|
|
|
270
|
|
|
271 "GoogleCloudPlatform" : {
|
|
|
272 ...
|
|
|
273 // Path to the URL of the GCP services
|
|
|
274 "BaseUrl" : "https://healthcare.googleapis.com/v1beta1/"
|
|
|
275 }
|
|
|
276 }
|
