comparison Sphinx/source/plugins/google-cloud-platform.rst @ 259:c2c436ce92d6

cont
author Sebastien Jodogne <s.jodogne@gmail.com>
date Thu, 27 Jun 2019 07:57:23 +0200
parents a073419272c7
children f9e7036d81d0
comparison
equal deleted inserted replaced
258:a073419272c7 259:c2c436ce92d6
11 ------------ 11 ------------
12 12
13 Osimis freely provides the `source code 13 Osimis freely provides the `source code
14 <https://bitbucket.org/osimis/orthanc-gcp/src>`__ of a plugin to 14 <https://bitbucket.org/osimis/orthanc-gcp/src>`__ of a plugin to
15 interface Orthanc with the Healthcare API of `Google Cloud Platform 15 interface Orthanc with the Healthcare API of `Google Cloud Platform
16 (GCP) <https://en.wikipedia.org/wiki/Google_Cloud_Platform>`__ thanks 16 (GCP) <https://en.wikipedia.org/wiki/Google_Cloud_Platform>`__ through
17 to `DICOMweb <https://www.dicomstandard.org/dicomweb/>`__. 17 `DICOMweb <https://www.dicomstandard.org/dicomweb/>`__.
18 18
19 This GCP plugin notably enables the upload of DICOM images through 19 This GCP plugin notably enables the upload of DICOM images using
20 STOW-RS, the querying of the cloud content through QIDO-RS, and the 20 STOW-RS, the querying of the cloud content using QIDO-RS, and the
21 retrieval of remote content through WADO-RS. These operations can be 21 retrieval of remote content using WADO-RS. These operations can be
22 possibly scripted thanks to the REST API of Orthanc. 22 possibly scripted thanks to the REST API of Orthanc.
23 23
24 Concretely, the GCP plugin manages the credentials to Google Cloud 24 Concretely, the GCP plugin manages the credentials to Google Cloud
25 Platform. It requires the official :ref:`DICOMweb plugin <dicomweb>` 25 Platform. It requires the official :ref:`DICOMweb plugin <dicomweb>`
26 to be installed. As soon as Orthanc is started, the GCP plugin 26 to be installed. As soon as Orthanc is started, the GCP plugin
27 automatically acquires and refreshes the `authentication tokens 27 automatically acquires and refreshes the `access tokens
28 <https://cloud.google.com/docs/authentication/>`__, transparently 28 <https://cloud.google.com/docs/authentication/>`__, transparently
29 updating the remote :ref:`DICOMweb servers <dicomweb-client-config>` 29 updating the remote :ref:`DICOMweb servers <dicomweb-client-config>`
30 that are known to the DICOMweb plugin. The authentication tokens can 30 that are known to the DICOMweb plugin. The access tokens can
31 be derived either from service accounts, or from user accounts. 31 be derived either from service accounts, or from user accounts.
32 32
33 This page makes the assumption that you have created a Google Cloud 33 This page makes the assumption that you have created a Google Cloud
34 Platform project, in which you have enabled the `Healthcare API 34 Platform project, in which you have enabled the `Healthcare API
35 <https://cloud.google.com/healthcare/>`__, and in which you have 35 <https://cloud.google.com/healthcare/>`__, and in which you have
55 $ cd Build 55 $ cd Build
56 $ cmake .. -DSTATIC_BUILD=ON -DCMAKE_BUILD_TYPE=Release 56 $ cmake .. -DSTATIC_BUILD=ON -DCMAKE_BUILD_TYPE=Release
57 $ make 57 $ make
58 58
59 The compilation produces a shared library 59 The compilation produces a shared library
60 ``OrthancGoogleCloudPlatform`` that contains the DICOMweb 60 ``OrthancGoogleCloudPlatform`` that contains the GCP
61 plugin. Pre-compiled binaries for Microsoft Windows `are available 61 plugin. Pre-compiled binaries for Microsoft Windows `are available
62 <http://www.orthanc-server.com/browse.php?path=/plugin-google-cloud>`__, 62 <http://www.orthanc-server.com/browse.php?path=/plugin-google-cloud>`__,
63 and are included in the `Windows installers 63 and are included in the `Windows installers
64 <https://www.orthanc-server.com/download-windows.php>`__. 64 <https://www.orthanc-server.com/download-windows.php>`__.
65 65
72 Common parameters 72 Common parameters
73 ^^^^^^^^^^^^^^^^^ 73 ^^^^^^^^^^^^^^^^^
74 74
75 As explained above, the GCP plugin requires the :ref:`official 75 As explained above, the GCP plugin requires the :ref:`official
76 DICOMweb plugin <dicomweb>` to be installed (with version above 76 DICOMweb plugin <dicomweb>` to be installed (with version above
77 1.0). 77 1.0). All the communications with Google Cloud Platform are done using
78 78 the DICOMweb plugin, and the responsibility of the GCP plugin is to
79 Furthermore, as obtaining the authentication tokens for Google Cloud 79 aquire and periodically refresh the access tokens whose lifetime is
80 Platform necessitates a sequence of HTTPS requests, the Orthanc 80 limited.
81
82 Obtaining the access tokens for Google Cloud Platform necessitates a
83 sequence of HTTPS requests. As a consequence, the Orthanc
81 :ref:`configuration options <configuration>` must specify how the 84 :ref:`configuration options <configuration>` must specify how the
82 authenticity of the Google servers is checked. You have two 85 authenticity of the Google servers is verified. You have two
83 possibilities to that end: 86 possibilities to that end:
84 87
85 1. Disabling the verification of the remote servers (**not recommended 88 1. Disabling the verification of the remote servers (**not recommended
86 in production**). This is done by setting option ``HttpsVerifyPeers`` 89 in production**). This is done by setting option ``HttpsVerifyPeers``
87 to ``false``. 90 to ``false``.
98 ``/etc/ssl/certs/ca-certificates.crt`` can be used. 101 ``/etc/ssl/certs/ca-certificates.crt`` can be used.
99 * On other systems, the cURL project provides `CA certificates 102 * On other systems, the cURL project provides `CA certificates
100 <https://curl.haxx.se/docs/caextract.html>`__ that are extracted 103 <https://curl.haxx.se/docs/caextract.html>`__ that are extracted
101 from Mozilla. 104 from Mozilla.
102 105
103 Note that to debug HTTPS communications, you have the possibility 106 Note that to debug HTTPS communications, you have the possibility of
104 of setting the ``HttpVerbose`` configuration option of Orthanc to ``true``. 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>`).
105 110
106 111
107 112
108 Service account 113 Service account
109 ^^^^^^^^^^^^^^^ 114 ^^^^^^^^^^^^^^^
171 176
172 177
173 .. highlight:: bash 178 .. highlight:: bash
174 179
175 Once the ``gcloud init`` command-line has been invoked, you can 180 Once the ``gcloud init`` command-line has been invoked, you can
176 extract credentials for Orthanc by typing the following command:: 181 extract credentials to be used by Orthanc by typing the following
182 command::
177 183
178 $ gcloud auth print-access-token --format json 184 $ gcloud auth print-access-token --format json
179 185
180 186
181 .. highlight:: json 187 .. highlight:: json
208 214
209 215
210 .. highlight:: bash 216 .. highlight:: bash
211 217
212 Note that only 3 fields in the JSON file produced by the ``gcloud auth 218 Note that only 3 fields in the JSON file produced by the ``gcloud auth
213 print-access-token`` are required: ``client_id``, ``client_secret``, 219 print-access-token`` command are required: ``client_id``,
214 and ``refresh_token``. Instead of using the full JSON file, you can 220 ``client_secret``, and ``refresh_token``. Instead of using the full
215 extract only these fields, e.g. using the `jq 221 JSON file, you can extract only these fields, e.g. using the `jq
216 <https://stedolan.github.io/jq/>`__ command-line tool:: 222 <https://stedolan.github.io/jq/>`__ command-line tool::
217 223
218 $ gcloud auth print-access-token --format json | jq '{ AuthorizedUserClientId: .client_id, AuthorizedUserClientSecret:.client_secret, AuthorizedUserRefreshToken:.refresh_token }' 224 $ gcloud auth print-access-token --format json | jq '{ AuthorizedUserClientId: .client_id, AuthorizedUserClientSecret:.client_secret, AuthorizedUserRefreshToken:.refresh_token }'
219 { 225 {
220 "AuthorizedUserClientId": "XXXXXXXXXX.apps.googleusercontent.com", 226 "AuthorizedUserClientId": "XXXXXXXXXX.apps.googleusercontent.com",
223 } 229 }
224 230
225 231
226 .. highlight:: json 232 .. highlight:: json
227 233
228 You can copy/paste these fields as follows in order to create a 234 These fields can then be copied/pasted as follows in order to create a
229 configuration for Orthanc that is equivalent to the one using the full 235 configuration for Orthanc that is equivalent to the one using the
230 JSON:: 236 separate JSON file::
231 237
232 { 238 {
233 "HttpsCACertificates": "/etc/ssl/certs/ca-certificates.crt", 239 "HttpsCACertificates": "/etc/ssl/certs/ca-certificates.crt",
234 "Plugins" : [ "." ], 240 "Plugins" : [ "." ],
235 "GoogleCloudPlatform" : { 241 "GoogleCloudPlatform" : {
244 "AuthorizedUserRefreshToken": "1/e2ngXXXXXX" 250 "AuthorizedUserRefreshToken": "1/e2ngXXXXXX"
245 } 251 }
246 } 252 }
247 } 253 }
248 } 254 }
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 }