Google Service Account & Earth Engine for DHIS2

DHIS2 can connect to various Google service APIs. For instance, the DHIS2 GIS component can utilize the Google Earth Engine API to load map layers. In order to provide API access tokens you must set up a Google service account and create a private key.

--DHIS2 Documentation

Requirements:

  • Admin rights to organization’s Google Account
  • SSH Access to DHIS2 Server
  • Safe Place to store key pair in compliance with your organization

After installation, Restart the instance to access Earth Engine via the Import/Export app.

Step 1: Create a Google Services Account

Google Service Account handles API tokens that grant DHIS2 (or other applications/servers) access to google services like Earth Engine.

This section will not duplicate instructions for creating a Google Services Account because Google has already done the best job at doing so here: Create A Google Services Account

Some Screenshots of the process:

The link above takes you to the instructions for creating a service account - this page is not in the “Google Cloud Platform” but everything else is.

Step 2: Create Service Account Key

  1. In the Google cloud console Access API & Services
  2. Select Credentials from the left side of the screen and then click the ➕ Create Credentials button at the top.
  3. Select “Service Account” from the drop down.
  4. Fill out the info. Review the optional fields and only complete them if you absolutely know what they are and that you need them.
  5. Now click your new service account (will switch you from “API & Services” to “IAM & ADMIN” service in the Google Cloud Platform).
  6. By Default you’ll be on the “Details” tab for your Service Account.
  7. Click the “Keys” Tab.
  8. Click “Add Key”
  9. Select “Create new key” from the drop down.
  10. Select “JSON” for key type. Note: This automatically downloads the key to your computer. As the pop up says - store it safely.
  11. Immediately rename this file to: dhis-google-auth.json
  12. The JSON key file will look something like this (keys changed but made to look real):
    1. java { "type": "service_account", "project_id": "fake", "private_key_id": "c7f045-FAKE-e9d58d0de897787de9d58d0de8", "private_key": "-----BEGIN PRIVATE KEY-----\FAKE-ADANBgkqhkiG9w0BAQEFAASCBKkwggSlAgEAAoIBAQDOsZ1batFw+Y4S\n8AfaVqQOizNXKwzFPrO/TJpb5bhPgxP2CPYK8oeDt8 FAKE FAKE FAKE-----END PRIVATE KEY-----\n", "client_email": "demo-536@fake.iam.gserviceaccount.com", "client_id": "107415504076179189236", "auth_uri": "https://accounts.google.com/o/oauth2/auth", "token_uri": "https://oauth2.googleapis.com/token", "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs", "client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/fake-demo-fake%40fake.iam.gserviceaccount.com" }
  13. Save this file on the DHIS2 server in the same directory as dhis.conf. On BAO Systems instances this is typically the directory /opt/dhis2/
  14. Change the ownership and permissions on dhis-google-auth.json: java chown --reference=dhis.conf dhis-google-auth.json && chmod --reference=dhis.conf dhis-google-auth.json
  15. Restart Tomcat
  16. Verify success by going to https://<dhis2-server>/api/tokens/google
{
"access_token": "FAkec.Kp8BAQhma5IAsHAEQA-8ADOs7rspQY5vYHk1hHqA5zQcl_UvXHM243bvWJ1PrmDCgPtsZurCYrZLGzt2Ia8-fcm9SqKokgJTnJAQPvCnQL7q7Vxr4vhSMbo0Di45QKnVLQxy-fvAt2OYx*********************************",
"client_id": "109443714010905341469",
"expires_in": 3599
}

Regarding the Key/Pair - Upon creation - it is downloaded to the user’s computer. This is the only copy that exists with the two together. You can access your public key via the google services account but you must store the private key safely - Google DOES NOT store copies of private keys. At BAO, this means we would store it in our team’s shared password manager alongside other server credentials.

Step 3: Add Google Earth Engine

Again, Google has outlined this in the best way already but I will walk through the steps of Earth Engine Cloud Project Setup

Sign up for the Service

In order to use Earth Engine you must be registered. If you are not already registered, apply for Earth Engine by clicking the following link: Apply for Earth Engine

Enable the Earth Engine API

To enable the Earth Engine API for your project, click the following button to go to the Earth Engine API page: Enable the Earth Engine API

That should be enough.. comment below if you have trouble so we can make this document better.