|
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
|
|
|
16 (GCP) <https://en.wikipedia.org/wiki/Google_Cloud_Platform>`__ thanks
|
|
|
17 to `DICOMweb <https://www.dicomstandard.org/dicomweb/>`__.
|
|
255
|
18
|
|
|
19 This GCP plugin notably enables the upload of DICOM images through
|
|
|
20 STOW-RS, the querying of the cloud content through QIDO-RS, and the
|
|
|
21 retrieval of remote content through WADO-RS. These operations can be
|
|
|
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
|
|
|
27 automatically acquires and refreshes the `authentication tokens
|
|
|
28 <https://cloud.google.com/docs/authentication/>`__, transparently
|
|
|
29 updating the remote :ref:`DICOMweb servers <dicomweb-client-config>`
|
|
|
30 that are known to the DICOMweb plugin. The authentication tokens can
|
|
|
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
|
|
|
60 ``OrthancGoogleCloudPlatform`` that contains the DICOMweb
|
|
|
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
|
|
|
77 1.0).
|
|
|
78
|
|
|
79 Furthermore, as obtaining the authentication tokens for Google Cloud
|
|
|
80 Platform necessitates a sequence of HTTPS requests, the Orthanc
|
|
|
81 :ref:`configuration options <configuration>` must specify how the
|
|
|
82 authenticity of the Google servers is checked. You have two
|
|
|
83 possibilities to that end:
|
|
|
84
|
|
|
85 1. Disabling the verification of the remote servers (**not recommended
|
|
|
86 in production**). This is done by setting option ``HttpsVerifyPeers``
|
|
|
87 to ``false``.
|
|
|
88
|
|
|
89 2. Providing a list of `trusted Certificate Authorities (CA)
|
|
|
90 <https://curl.haxx.se/docs/sslcerts.html>`__ to the HTTPS client
|
|
|
91 that is internally used by Orthanc (namely, `cURL
|
|
|
92 <https://en.wikipedia.org/wiki/CURL>`__). This is done by properly
|
|
|
93 setting ``HttpsVerifyPeers`` option, so that it points to a file
|
|
|
94 containing a store of CA certificates. Depending on your operating
|
|
|
95 system, this file can be found as follows:
|
|
|
96
|
|
|
97 * On Debian-based system, the standard file
|
|
|
98 ``/etc/ssl/certs/ca-certificates.crt`` can be used.
|
|
|
99 * On other systems, the cURL project provides `CA certificates
|
|
|
100 <https://curl.haxx.se/docs/caextract.html>`__ that are extracted
|
|
|
101 from Mozilla.
|
|
|
102
|
|
|
103 Note that to debug HTTPS communications, you have the possibility
|
|
|
104 of setting the ``HttpVerbose`` configuration option of Orthanc to ``true``.
|
|
|
105
|
|
254
|
106
|
|
|
107
|
|
255
|
108 Service account
|
|
|
109 ^^^^^^^^^^^^^^^
|
|
|
110
|
|
|
111 As explained on the `Google documentation
|
|
|
112 <https://cloud.google.com/docs/authentication/#service_accounts>`__,
|
|
|
113 *"a service account is a Google account that represents an
|
|
|
114 application, as opposed to representing an end user"*. This is
|
|
|
115 presumably the most common situation in the case of Orthanc.
|
|
|
116
|
|
|
117 You first have to `create a service account
|
|
|
118 <https://cloud.google.com/docs/authentication/getting-started#creating_a_service_account>`__
|
|
|
119 for your application. This will produce a JSON file (say,
|
|
|
120 ``dicom-osimis.json``) that you have to store securely on the server
|
|
|
121 that will run Orthanc.
|
|
|
122
|
|
|
123 .. highlight:: json
|
|
|
124
|
|
|
125 Secondly, you have to modify the :ref:`Orthanc configuration
|
|
|
126 <configuration>` in order to provide the GCP plugin with your service
|
|
|
127 account file and with the parameters of your `DICOM store
|
|
|
128 <https://cloud.google.com/healthcare/docs/how-tos/dicom>`__. Here is a
|
|
256
|
129 sample, minimalist configuration of Orthanc::
|
|
255
|
130
|
|
|
131 {
|
|
|
132 "HttpsCACertificates": "/etc/ssl/certs/ca-certificates.crt",
|
|
|
133 "Plugins" : [ "." ],
|
|
|
134 "GoogleCloudPlatform" : {
|
|
|
135 "Accounts": {
|
|
|
136 "my-google" : {
|
|
|
137 "Project" : "osimis-test",
|
|
|
138 "Location" : "europe-west2",
|
|
|
139 "Dataset" : "test",
|
|
|
140 "DicomStore" : "dicom",
|
|
|
141 "ServiceAccountFile" : "dicom-osimis.json"
|
|
|
142 }
|
|
|
143 }
|
|
|
144 }
|
|
|
145 }
|
|
|
146
|
|
|
147
|
|
|
148 In this example, once the GCP plugin has succeeded to authenticate
|
|
|
149 using the service account, the DICOMweb plugin will provide access to
|
|
|
150 the cloud DICOM store at URI ``/dicom-web/servers/my-google/`` of the
|
|
|
151 REST API of Orthanc.
|
|
|
152
|
|
|
153
|
|
|
154 User account
|
|
|
155 ^^^^^^^^^^^^
|
|
|
156
|
|
|
157 User account is an alternative to service account, and can be used
|
|
|
158 *"when the application needs to access resources on behalf of an end
|
|
|
159 user"* (check out the `Google documentation
|
|
|
160 <https://cloud.google.com/docs/authentication/#user_accounts>`__).
|
|
|
161
|
|
|
162 .. highlight:: json
|
|
|
163
|
|
|
164 The easiest way of setting up a user account is through the `gcloud
|
|
|
165 command-line tool <https://cloud.google.com/sdk/gcloud/>`__.
|
|
256
|
166 `Google's quick-starts
|
|
255
|
167 <https://cloud.google.com/sdk/docs/quickstarts>`__ explain how to
|
|
|
168 initialize the environment depending on your operating system (check
|
|
|
169 out the "Initialize the SDK" sections, which essentially boil down to
|
|
|
170 calling ``gcloud init``).
|
|
|
171
|
|
|
172
|
|
|
173 .. highlight:: bash
|
|
|
174
|
|
|
175 Once the ``gcloud init`` command-line has been invoked, you can
|
|
|
176 extract credentials for Orthanc by typing the following command::
|
|
|
177
|
|
|
178 $ gcloud auth print-access-token --format json
|
|
|
179
|
|
|
180
|
|
|
181 .. highlight:: json
|
|
|
182
|
|
|
183 This command produces JSON file containing all the required
|
|
|
184 information, that can be written to a file (say,
|
|
256
|
185 ``dicom-user.json``). Given this file, here is a sample, minimalist
|
|
255
|
186 configuration of Orthanc::
|
|
|
187
|
|
|
188 {
|
|
|
189 "HttpsCACertificates": "/etc/ssl/certs/ca-certificates.crt",
|
|
|
190 "Plugins" : [ "." ],
|
|
|
191 "GoogleCloudPlatform" : {
|
|
|
192 "Accounts": {
|
|
|
193 "my-google" : {
|
|
|
194 "Project" : "osimis-test",
|
|
|
195 "Location" : "europe-west2",
|
|
|
196 "Dataset" : "test",
|
|
|
197 "DicomStore" : "dicom",
|
|
|
198 "AuthorizedUserFile" : "dicom-osimis.json"
|
|
|
199 }
|
|
|
200 }
|
|
|
201 }
|
|
|
202 }
|
|
|
203
|
|
|
204 In this example, once the GCP plugin has succeeded to authenticate
|
|
|
205 using the user account, the DICOMweb plugin will provide access to the
|
|
|
206 cloud DICOM store at URI ``/dicom-web/servers/my-google/`` of the REST
|
|
|
207 API of Orthanc.
|
|
|
208
|
|
|
209
|
|
|
210 .. highlight:: bash
|
|
|
211
|
|
|
212 Note that only 3 fields in the JSON file produced by the ``gcloud auth
|
|
|
213 print-access-token`` are required: ``client_id``, ``client_secret``,
|
|
|
214 and ``refresh_token``. Instead of using the full JSON file, you can
|
|
|
215 extract only these fields, e.g. using the `jq
|
|
|
216 <https://stedolan.github.io/jq/>`__ command-line tool::
|
|
|
217
|
|
|
218 $ gcloud auth print-access-token --format json | jq '{ AuthorizedUserClientId: .client_id, AuthorizedUserClientSecret:.client_secret, AuthorizedUserRefreshToken:.refresh_token }'
|
|
|
219 {
|
|
|
220 "AuthorizedUserClientId": "XXXXXXXXXX.apps.googleusercontent.com",
|
|
|
221 "AuthorizedUserClientSecret": "ZmssLNXXXXXX",
|
|
|
222 "AuthorizedUserRefreshToken": "1/e2ngXXXXXX"
|
|
|
223 }
|
|
|
224
|
|
|
225
|
|
|
226 .. highlight:: json
|
|
|
227
|
|
|
228 You can use this information as follows in order to create a
|
|
|
229 configuration for Orthanc that is equivalent to the one using the full
|
|
|
230 JSON::
|
|
|
231
|
|
|
232 {
|
|
|
233 "HttpsCACertificates": "/etc/ssl/certs/ca-certificates.crt",
|
|
|
234 "Plugins" : [ "." ],
|
|
|
235 "GoogleCloudPlatform" : {
|
|
|
236 "Accounts": {
|
|
|
237 "my-google" : {
|
|
|
238 "Project" : "osimis-test",
|
|
|
239 "Location" : "europe-west2",
|
|
|
240 "Dataset" : "test",
|
|
|
241 "DicomStore" : "dicom",
|
|
|
242 "AuthorizedUserClientId": "XXXXXXXXXX.apps.googleusercontent.com",
|
|
|
243 "AuthorizedUserClientSecret": "ZmssLNXXXXXX",
|
|
|
244 "AuthorizedUserRefreshToken": "1/e2ngXXXXXX"
|
|
|
245 }
|
|
|
246 }
|
|
|
247 }
|
|
|
248 }
|
