Google Service Account Authentication

Introduction

This article provides detailed information about how Appian can connect to the Google Cloud APIs that leverage Google Service Account authentication. Designers can configure these integrations using an HTTP connected system.

Google Cloud Configuration

A service account is a special kind of Google account that represents a non-human user. Appian can use these service accounts to call Google APIs so that end users don't need to be directly involved.

There are several steps that must take place in order to generate the service account key

Creating and Managing Google Service Accounts

To use Google Service Account authentication, you will need a service account in Google.

To learn about creating and managing service accounts, see the Google IAM documentation on creating and managing service accounts.

Granting Roles to Service Accounts

In order to be authorized to access data in a specific Google API, your service account must have the proper roles.

To learn about granting roles to service accounts, see the Google IAM documentation on granting roles to service accounts.

Generating a Service Account Key

To use Google Service Account authentication, you will need a service account key for your service account. This file should be download in JSON format.

To learn about creating and managing service account keys, see the Google IAM documentation on creating and managing service account keys.

Performing G Suite Domain-Wide Delegation of Authority (Optional)

In some cases, you may want to take advantage of domain-wide delegation of authority. Google allows G Suite administrators to configure domain-wide delegation in order to grant Google Service Accounts permission to impersonate specific G Suite users. This can be used with a number of G Suite services such as Google Groups (the Admin SDK Directory API), Google Calendar, and Gmail.

images:g_suite_dwd.png

To learn more about configuring domain-wide delegation of authority for an API, you should view the documentation for that service.

Different services have slightly different documentation to explain domain-wide delegation of authority. For example, there are different pages for the Admin SDK Directory API, the Google Calendar API, the Google Drive API, and the Gmail API.

Appian Configuration

Once you have configured your service account in Google and exported your service account key, you are ready to set up your HTTP connected system.

Using your Service Account Key

When creating an HTTP connected system with Google Service Account authentication, Appian allows designers to upload a service account key JSON file rather than manually filling out each field.

images:gsa_image.png

This will populate the Project ID, Client ID, and Client Email fields.

images:gsa_image_filled.png

These field values will need to be manually specified using an import customization file when deploying to higher environments.

Setting the Scope

In order to successfully call an API, you will also need to set the required scopes for your connected system. Several scopes can be entered and separated by spaces. If left empty, the default scope is https://www.googleapis.com/auth/cloud-platform.

To find the required scopes for an API, you should view the documentation for that service. For example, when using Google Calendar refer to the documentation on authorizing requests to the Google Calendar API and the documentation for each API endpoint. In this case, to call the Calendars: update endpoint you will need to request a scope of https://www.googleapis.com/auth/calendar.

Impersonating a G Suite Domain User (Optional)

If you have configured domain-wide delegation, Appian supports the ability for your service account to impersonate a G Suite domain user. To do so, simply check Impersonate G Suite domain user on the HTTP connected system and provide the email address of the G Suite domain user to impersonate. All integrations leveraging your connected system will be executed as this user in accordance with the permissions they have been granted to your G Suite domain.

Parameters Set in the Connected System

The following properties are available for configuration when Google Service Account is selected as the authentication type:

Field Description
Service Account Key Optional. A JSON file containing service account information. This file is obtained from the Google Cloud Platform (GCP) Console.
Project ID Read-Only. The Project ID for the service account key. This field is read-only on the UI, but must be populated by an import customization file to deploy the connected system to a higher environment.
Client ID Read-Only. The Client ID for the service account key. This field is read-only on the UI, but must be populated by an import customization file to deploy the connected system to a higher environment.
Client Email Read-Only. The Client Email for the service account key. This field is read-only on the UI, but must be populated by an import customization file to deploy the connected system to a higher environment.
Private Key ID Hidden. The Private Key ID for the service account key. This field isn't exposed on the UI, but must be populated by an import customization file to deploy the connected system to a higher environment.
Private Key Hidden. The Private Key for the service account key. This field isn't exposed on the UI, but must be populated by an import customization file to deploy the connected system to a higher environment.

The Private Key starts with/includes the string -----BEGIN PRIVATE KEY-----\n and ends with/includes the string \n-----END PRIVATE KEY-----\n
Scope Optional. The permissions that will be requested from the protected resource. If left empty, the default scope is https://www.googleapis.com/auth/cloud-platform.
Impersonate G Suite domain user Optional. Checking this allows integrations to impersonate a specific G Suite domain user. Requires a service account with domain-wide delegation of authority.
G Suite Domain User Email Required (Conditionally). When using domain-wide delegation, this is the email for the G Suite Domain User that should be impersonated. This field is only exposed if Impersonate G Suite domain user is selected.
FEEDBACK