Mercurial > hg > orthanc-book

comparison Sphinx/source/plugins/google-cloud-platform.rst @ 255:949a13b92195

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
google
author Sebastien Jodogne <s.jodogne@gmail.com>
date Wed, 26 Jun 2019 22:31:25 +0200
parents 63cc25161330
children 8a8d8a908c6c
comparison
equal deleted inserted replaced
254:63cc25161330 255:949a13b92195
4 Google Cloud Platform plugin 4 Google Cloud Platform plugin
5 ============================ 5 ============================
6 6
7 .. contents:: 7 .. contents::
8 8
9 Osimis provides a `dedicated plugin 9
10 <https://bitbucket.org/osimis/orthanc-gcp/src>`__ to interface Orthanc 10 Introduction
11 with Healthcare API of `Google Cloud Platform 11 ------------
12 <https://en.wikipedia.org/wiki/Google_Cloud_Platform>`__ using 12
13 :ref:`DICOMweb <dicomweb>`. This plugin notably enables the upload of 13 Osimis freely provides the `source code
14 DICOM images through STOW-RS, the querying of the cloud content 14 <https://bitbucket.org/osimis/orthanc-gcp/src>`__ of a dedicated
15 through QIDO-RS, and the retrieval of remote content through WADO-RS. 15 plugin to interface Orthanc with the Healthcare API of `Google Cloud
16 These operations can be scripted through the REST API of Orthanc. 16 Platform (GCP)
17 17 <https://en.wikipedia.org/wiki/Google_Cloud_Platform>`__ thanks to
18 18 `DICOMweb <https://www.dicomstandard.org/dicomweb/>`__.
19 TODO 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
107
108
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 }