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