# HG changeset patch
# User Sebastien Jodogne <s.jodogne@gmail.com>
# Date 1561581085 -7200
# Node ID 949a13b92195fc842b1318513f4aef8a757fed4b
# Parent  63cc25161330c711a250373cfddcdbf498465da9
google

diff -r 63cc25161330 -r 949a13b92195 Sphinx/source/plugins/dicomweb.rst
--- a/Sphinx/source/plugins/dicomweb.rst	Wed Jun 26 19:41:58 2019 +0200
+++ b/Sphinx/source/plugins/dicomweb.rst	Wed Jun 26 22:31:25 2019 +0200
@@ -25,7 +25,7 @@
 
 .. highlight:: text
 
-The procedure to compile these plugins is similar of that for the
+The procedure to compile this plugin is similar of that for the
 :ref:`core of Orthanc <compiling>`. The following commands should work
 for every UNIX-like distribution (including GNU/Linux)::
 
@@ -37,8 +37,10 @@
 The compilation will produce a shared library ``OrthancDicomWeb`` that
 contains the DICOMweb plugin. Pre-compiled binaries for Microsoft
 Windows `are also available
-<http://www.orthanc-server.com/browse.php?path=/plugin-dicom-web>`__.
-A package for `Apple's Mac OS X
+<http://www.orthanc-server.com/browse.php?path=/plugin-dicom-web>`__,
+and are included in the `Windows installers
+<https://www.orthanc-server.com/download-windows.php>`__.  A package
+for `Apple's Mac OS X
 <http://localhost/~jodogne/orthanc/static.php?page=download-mac>`__ is
 available courtesy of `Osimis <http://osimis.io/>`__.
 
@@ -126,6 +128,8 @@
 
 
 
+.. _dicomweb-client-config:
+
 Client-related options
 ^^^^^^^^^^^^^^^^^^^^^^
 
diff -r 63cc25161330 -r 949a13b92195 Sphinx/source/plugins/google-cloud-platform.rst
--- a/Sphinx/source/plugins/google-cloud-platform.rst	Wed Jun 26 19:41:58 2019 +0200
+++ b/Sphinx/source/plugins/google-cloud-platform.rst	Wed Jun 26 22:31:25 2019 +0200
@@ -6,14 +6,244 @@
 
 .. contents::
 
-Osimis provides a `dedicated plugin
-<https://bitbucket.org/osimis/orthanc-gcp/src>`__ to interface Orthanc
-with Healthcare API of `Google Cloud Platform
-<https://en.wikipedia.org/wiki/Google_Cloud_Platform>`__ using
-:ref:`DICOMweb <dicomweb>`. This plugin notably enables the upload of
-DICOM images through STOW-RS, the querying of the cloud content
-through QIDO-RS, and the retrieval of remote content through WADO-RS.
-These operations can be scripted through the REST API of Orthanc.
+   
+Introduction
+------------
+
+Osimis freely provides the `source code
+<https://bitbucket.org/osimis/orthanc-gcp/src>`__ of a dedicated
+plugin to interface Orthanc with the Healthcare API of `Google Cloud
+Platform (GCP)
+<https://en.wikipedia.org/wiki/Google_Cloud_Platform>`__ thanks to
+`DICOMweb <https://www.dicomstandard.org/dicomweb/>`__.
+
+This GCP plugin notably enables the upload of DICOM images through
+STOW-RS, the querying of the cloud content through QIDO-RS, and the
+retrieval of remote content through WADO-RS. These operations can be
+possibly scripted thanks to the REST API of Orthanc.
+
+Concretely, the GCP plugin manages the credentials to Google Cloud
+Platform. It requires the official :ref:`DICOMweb plugin <dicomweb>`
+to be installed. As soon as Orthanc is started, the GCP plugin
+automatically acquires and refreshes the `authentication tokens
+<https://cloud.google.com/docs/authentication/>`__, transparently
+updating the remote :ref:`DICOMweb servers <dicomweb-client-config>`
+that are known to the DICOMweb plugin. The authentication tokens can
+be derived either from service accounts, or from user accounts.
+
+This page makes the assumption that you have created a Google Cloud
+Platform project, in which you have enabled the `Healthcare API
+<https://cloud.google.com/healthcare/>`__, and in which you have
+created a `DICOM store
+<https://cloud.google.com/healthcare/docs/how-tos/dicom>`__.
+
+Under the hood, the GCP plugin is built on the top of the official
+`Google Cloud Platform C++ Client Libraries
+<https://github.com/googleapis/google-cloud-cpp>`__.
+
+
+
+Compilation
+-----------
+
+.. highlight:: text
+
+The procedure to compile the GCP plugin is similar of that for the
+:ref:`core of Orthanc <compiling>`. The following commands should work
+on any recent UNIX-like distribution (including GNU/Linux)::
+
+  $ mkdir Build
+  $ cd Build
+  $ cmake .. -DSTATIC_BUILD=ON -DCMAKE_BUILD_TYPE=Release
+  $ make
+
+The compilation produces a shared library
+``OrthancGoogleCloudPlatform`` that contains the DICOMweb
+plugin. Pre-compiled binaries for Microsoft Windows `are available
+<http://www.orthanc-server.com/browse.php?path=/plugin-google-cloud>`__,
+and are included in the `Windows installers
+<https://www.orthanc-server.com/download-windows.php>`__.
+
+
+
+Configuration
+-------------
+
+
+Common parameters
+^^^^^^^^^^^^^^^^^
+
+As explained above, the GCP plugin requires the :ref:`official
+DICOMweb plugin <dicomweb>` to be installed (with version above
+1.0).
+
+Furthermore, as obtaining the authentication tokens for Google Cloud
+Platform necessitates a sequence of HTTPS requests, the Orthanc
+:ref:`configuration options <configuration>` must specify how the
+authenticity of the Google servers is checked. You have two
+possibilities to that end:
+
+1. Disabling the verification of the remote servers (**not recommended
+   in production**). This is done by setting option ``HttpsVerifyPeers``
+   to ``false``.
+
+2. Providing a list of `trusted Certificate Authorities (CA)
+   <https://curl.haxx.se/docs/sslcerts.html>`__ to the HTTPS client
+   that is internally used by Orthanc (namely, `cURL
+   <https://en.wikipedia.org/wiki/CURL>`__). This is done by properly
+   setting ``HttpsVerifyPeers`` option, so that it points to a file
+   containing a store of CA certificates. Depending on your operating
+   system, this file can be found as follows:
+
+   * On Debian-based system, the standard file
+     ``/etc/ssl/certs/ca-certificates.crt`` can be used.
+   * On other systems, the cURL project provides `CA certificates
+     <https://curl.haxx.se/docs/caextract.html>`__ that are extracted
+     from Mozilla. 
+
+Note that to debug HTTPS communications, you have the possibility
+of setting the ``HttpVerbose`` configuration option of Orthanc to ``true``.
+
 
 
-TODO
+Service account
+^^^^^^^^^^^^^^^
+
+As explained on the `Google documentation
+<https://cloud.google.com/docs/authentication/#service_accounts>`__,
+*"a service account is a Google account that represents an
+application, as opposed to representing an end user"*. This is
+presumably the most common situation in the case of Orthanc.
+
+You first have to `create a service account
+<https://cloud.google.com/docs/authentication/getting-started#creating_a_service_account>`__
+for your application. This will produce a JSON file (say,
+``dicom-osimis.json``) that you have to store securely on the server
+that will run Orthanc.
+
+.. highlight:: json
+
+Secondly, you have to modify the :ref:`Orthanc configuration
+<configuration>` in order to provide the GCP plugin with your service
+account file and with the parameters of your `DICOM store
+<https://cloud.google.com/healthcare/docs/how-tos/dicom>`__. Here is a
+sample, minimalistic configuration of Orthanc::
+
+  {
+    "HttpsCACertificates": "/etc/ssl/certs/ca-certificates.crt",
+    "Plugins" : [ "." ],
+    "GoogleCloudPlatform" : {
+      "Accounts": {
+        "my-google" : {
+          "Project" : "osimis-test",
+          "Location" : "europe-west2",
+          "Dataset" : "test",
+          "DicomStore" : "dicom",
+          "ServiceAccountFile" : "dicom-osimis.json"
+        }
+      }
+    }
+  }
+
+
+In this example, once the GCP plugin has succeeded to authenticate
+using the service account, the DICOMweb plugin will provide access to
+the cloud DICOM store at URI ``/dicom-web/servers/my-google/`` of the
+REST API of Orthanc.
+
+
+User account
+^^^^^^^^^^^^
+
+User account is an alternative to service account, and can be used
+*"when the application needs to access resources on behalf of an end
+user"* (check out the `Google documentation
+<https://cloud.google.com/docs/authentication/#user_accounts>`__).
+
+.. highlight:: json
+
+The easiest way of setting up a user account is through the `gcloud
+command-line tool <https://cloud.google.com/sdk/gcloud/>`__.
+`Google's quickstarts
+<https://cloud.google.com/sdk/docs/quickstarts>`__ explain how to
+initialize the environment depending on your operating system (check
+out the "Initialize the SDK" sections, which essentially boil down to
+calling ``gcloud init``).
+
+
+.. highlight:: bash
+
+Once the ``gcloud init`` command-line has been invoked, you can
+extract credentials for Orthanc by typing the following command::
+
+  $ gcloud auth print-access-token --format json
+
+
+.. highlight:: json
+
+This command produces JSON file containing all the required
+information, that can be written to a file (say,
+``dicom-user.json``). Given this file, here is a sample, minimalistic
+configuration of Orthanc::
+
+  {
+    "HttpsCACertificates": "/etc/ssl/certs/ca-certificates.crt",
+    "Plugins" : [ "." ],
+    "GoogleCloudPlatform" : {
+      "Accounts": {
+        "my-google" : {
+          "Project" : "osimis-test",
+          "Location" : "europe-west2",
+          "Dataset" : "test",
+          "DicomStore" : "dicom",
+          "AuthorizedUserFile" : "dicom-osimis.json"
+        }
+      }
+    }
+  }
+
+In this example, once the GCP plugin has succeeded to authenticate
+using the user account, the DICOMweb plugin will provide access to the
+cloud DICOM store at URI ``/dicom-web/servers/my-google/`` of the REST
+API of Orthanc.
+
+
+.. highlight:: bash
+
+Note that only 3 fields in the JSON file produced by the ``gcloud auth
+print-access-token`` are required: ``client_id``, ``client_secret``,
+and ``refresh_token``. Instead of using the full JSON file, you can
+extract only these fields, e.g. using the `jq
+<https://stedolan.github.io/jq/>`__ command-line tool::
+
+  $ gcloud auth print-access-token --format json | jq '{ AuthorizedUserClientId: .client_id, AuthorizedUserClientSecret:.client_secret, AuthorizedUserRefreshToken:.refresh_token }'
+  {
+    "AuthorizedUserClientId": "XXXXXXXXXX.apps.googleusercontent.com",
+    "AuthorizedUserClientSecret": "ZmssLNXXXXXX",
+    "AuthorizedUserRefreshToken": "1/e2ngXXXXXX"
+  }
+
+
+.. highlight:: json
+
+You can use this information as follows in order to create a
+configuration for Orthanc that is equivalent to the one using the full
+JSON::
+  
+  {
+    "HttpsCACertificates": "/etc/ssl/certs/ca-certificates.crt",
+    "Plugins" : [ "." ],
+    "GoogleCloudPlatform" : {
+      "Accounts": {
+        "my-google" : {
+          "Project" : "osimis-test",
+          "Location" : "europe-west2",
+          "Dataset" : "test",
+          "DicomStore" : "dicom",
+          "AuthorizedUserClientId": "XXXXXXXXXX.apps.googleusercontent.com",
+          "AuthorizedUserClientSecret": "ZmssLNXXXXXX",
+          "AuthorizedUserRefreshToken": "1/e2ngXXXXXX"
+        }
+      }
+    }
+  }