English Version: Google APIs - Introduction, Authentication Methods & Service Account Impersonation

This article covers 3 topics related to Google APIs

Introduction to Google APIs
Authentication methods
Service Account Impersonation

This blog article focuses on a Node.js implementation, which means some links will direct you to the corresponding Node.js documentation. Nevertheless the main part will be generic and applies to all programming languages.

Introduction: Which Google APIs are we talking about?

When reading through the official Google documentation it seems that the term “Google APIs” is used for the complete set of APIs, and “Google Cloud APIs” or just “Cloud APIs” is used for the sub set of APIs related to the Google Cloud Platform. This blog article series will address all Google APIs. Just to name a few: Campaign Manager 360 API, Google Analytics Reporting API, BigQuery API etc.

There are two options to get a list of these APIs, but it seems that these options do not list the same/complete set of APIs (Google Cloud Marketplace: 314 APIs vs. API Library: 414 APIs). I would recommend using the dedicated API Library page, but wanted to show an alternative for non GCP users.

API List - Google Cloud Marketplace

One way to get a collection of Google Cloud APIs is via the Google Cloud Marketplace.

This marketplace is a collection of software products and services available on GCP. The link above in addition contains a filter which reduces the results to only display Google products. You do not need to have a GCP account or be logged in to be able to see this API overview. Clicking on one of the displayed Google Cloud APIs will reveal important links e.g. to the documentation, API explorer etc. and inform about pricing (if applicable).

Screenshot of the Google Cloud Marketplace, Source: e-dialog

Just as a side note: There is no separate entry for most Google Cloud Platform service APIs. An example to make it clear: you will not find an entry for “BigQuery API” only the GCP service “BigQuery” can be found, which then references BigQuery API documentation.

Google Cloud Marketplace search result for ‚BigQuery‘, Source: e-dialog

API List - API Library

The second method to get a list of the Google APIs is via the Google Cloud Platform console and the menu item: GCP > APIs and services > Library.

How to find the GCP API Library, Source: e-dialog

Ways to access Google API

All these Google APIs can only be accessed via the Google Cloud Platform. When you want to use one of them, the corresponding API needs to be enabled first within: GCP > APIs & Services > Enabled APIs and services > + Enable APIs and Services. All enabled Google APIs for the selected project will be listed up on the same page.

Enable APIs and services in GCP, Source: e-dialog

1 Google APIs Explorer

Many Google APIs can be accessed via the Google APIs explorer, which offers a great way to interact with API methods without writing code. It can be used for debugging and learning purposes. To use this tool, the activation of the corresponding API as explained above is not required.

2 Directly

Google recommends using their Client Libraries to interact with their APIs. If the rare situation occurs that these libraries do not meet your specific needs, you can write your own code to access those APIs directly.

3 Via Client Libraries

While there are dedicated mobile Firebase client libraries available, this article tries to focus on a Node.js implementation, which offers two different client libraries.

3.1 Google Cloud Client Libraries

The recommended and newer library is called “Google Cloud Client Libraries”. These libraries support REST and gRPC, handle authentication and provide an intuitive and consistent style across all APIs and languages. Currently the following list shows 116 APIs which can be accessed via the Node.js client.

In the background these clients use the dependency “Google Auth Library” for handling authentication, which offers the following authentication methods:

Application Default Credentials
OAuth 2
JSON Web Tokens (JWT)
Google Compute
Workload Identity Federation
Workforce Identity Federation
Impersonated Credentials Client
Downscoped Client

3.2 Google API Client Libraries

The second and older library is called “Google API Client Libraries”. Google recommends only using these libraries if the “Google Cloud Client Library” does not support the desired language. These libraries support REST (not gRPC) and handle authentication. The following page offers documentation for 228 APIs accessible via Node.js.

Documentation: Google API Client Libraries
Languages: Supported languages
npm: googleapis

These libraries support the following ways to authenticate to Google APIs:

Application Default Credentials
OAuth 2
JSON Web Tokens (JWT)
Google Compute
API Key
Service Account Credentials (Key File)

API Quotas and Usage

Each Google API has different quotas, which means API usage will be capped based on defined thresholds. Quotas and usage can be viewed via GCP > IAM and admin > Quotas or via GCP > APIs and services > select an API > QUOTAS tab. It is possible to reduce your own quota limits (e.g. to save costs) or request an increase via a form.

Review API quota in GCP, Source: e-dialog

Authentication Methods

There are multiple methods available for the authentication of Google APIs. This blog article will focus on the most important authentication methods and explain how they work and when to use which one.

API Keys

If an API key needs to be used, is defined by the Google API itself and can not be decided by the calling application. There are specific Google APIs which require the usage of an API key such as: Google Maps JavaScript API, Google Geocoding API and Google Picker API.

API keys can be created within the Google Cloud Platform console. Their purpose is just to identify the application or project which is calling the API. Thus Google can enforce API quotas and costs based on API usage.

API keys are generally not considered secure, because often API keys are used on the client side. The above mentioned Google Maps JavaScript API is implemented on the frontend and thus the API key is visible to everyone.

To increase security for API keys, Google offers the possibility to restrict them to specific websites, IP addresses, Android applications or iOS applications. In addition API keys can be restricted to only be able to call specific APIs.

Application Default Credentials (ADC)

ADC is a procedure used by the Google authentication libraries (e.g. Google Auth Library: Node.js Client) to automatically find credentials based on the application environment. Due to ADC the code does not need to be changed between development and production environments.

ADC searches for credentials in the following order/locations:

GOOGLE_APPLICATION_CREDENTIALS environment variable
User credentials via gcloud
Service account attached to GCP resources

GOOGLE_APPLICATION_CREDENTIALS environment variable: The first location, the environment variable, can point to a location where a credential JSON file is stored. It is not recommended to download and use service account keys for this scenario. The main use case is the usage of a credential configuration file for workload identity federation, which is out of scope of this article.

User credentials via gcloud: When working locally, usually user credentials are provided via the command gcloud auth login. Nevertheless, ADC will not use these credentials, instead it will only use credentials provided via gcloud auth application-default login. Both commands open the same authentication flow as can be seen within the screenshot below.

3. Service account attached to GCP resources: Many GCP resources like Cloud Run and Cloud Functions require to attach a service account when created, which will then be used within the code to access Google APIs.

OAuth2

OAuth2 and JWTs (next chapter) are both used for authentication and authorization and have a couple of similarities:

Secure token-based authentication: Both OAuth and JWT provide a secure mechanism for token-based authentication, where tokens are used to authenticate and authorize users and services.
JSON-based format: Both OAuth and JWT use JSON to encode the token data.
Open standards: Both OAuth and JWT are open standards and have wide industry adoption.
Transport security: Both OAuth and JWT rely on secure transport protocols, such as HTTPS, to prevent interception and tampering of tokens.

OAuth is primarily used for granting third-party access to resources on behalf of a user. This technology is often used for social logins (allow users to sign in to a website or application using their social media accounts) and third party API access (see example below).

When OAuth is used in combination with a service account, the above shown login popup (or a similar one) is not displayed.

Usually three parties are involved to make an OAuth flow happen.

Resource owner: The resource owner is the user who owns the resource that needs to be accessed by a third-party application. For example, a resource owner could be a user who has multiple Campaign Manager 360 accounts.
Client application: The client application is the third-party application that wants to access the resource on behalf of the resource owner. For example, a client application could be a Nodejs application which wants to upload offline conversions via the Campaign Manager 360 API.
Authorization server: The authorization server is the server that authenticates the user and issues access tokens that can be used by the client application to access the resource on behalf of the user. For example, an authorization server could be the server of Google.

In the OAuth flow, the client application first requests authorization from the resource owner to access the resource. Once the resource owner grants authorization, the client application sends a request to the authorization server to obtain an access token. The authorization server verifies the client’s identity and the resource owner’s authorization and issues an access token. The client application can then use the access token to access the resource on behalf of the resource owner.

In some cases, there may also be a fourth party involved: the resource server. The resource server is the server that hosts the resource that the client application wants to access. In this case, the client application uses the access token obtained from the authorization server to request the resource from the resource server. The resource server verifies the access token and, if valid, serves the requested resource to the client application.

This standard typically uses a combination of access tokens and refresh tokens. Access tokens are short-lived tokens (expire after one hour or less) and are periodically swapped by new access tokens. To get a new access token from the authorization server, the long-lived access token (expires after days or weeks) is used by the client application. So OAuth tokens are typically verified by the authorization server.

Depending where the OAuth flow should happen, different libraries are available (e.g. for server-side web apps, for JavaScript web apps, for service accounts).

JSON Web Tokens (JWT)

JWT is primarily used for authentication and authorization of users and services within an application or system. Thus it is especially useful for server to server and server to API communication.

Additional differences to OAuth are:

JWT uses a JSON web token as a bearer token
JWT tokens can have a longer lifespan or an expiration date
JWT tokens can be verified locally by the application that issued them

In the field of Online Marketing, especially when exporting Google data (third party API access), OAuth is widely used as the authentication method. Nevertheless, from time to time also JWT is used. The corresponding Node.js code might look similar to this one:

				
					const { google } = require("googleapis");
const jwt = new google.auth.JWT(
        process.env.CLIENT_EMAIL,
        null,
        process.env.PRIVATE_KEY,
        scopes
    );

This approach is only possible if a service account and a service account key file (not recommended) is used. In addition the corresponding API needs to support this JWT approach. You can read more about it here.

Service Account Credentials (Key File)

You can create service accounts within GCP which can then be used to make requests to Google APIs. These accounts come in handy to make the application independent of specific user accounts (imagine a colleague leaving the company) and is the recommended approach.

When calling GCP APIs (e.g. BigQuery) the service account needs the appropriate IAM roles, whereas when calling non-GCP APIs (e.g. Google Analytics) the service account needs to be added to the corresponding account.

Often these service accounts are used in combination with OAuth2, nevertheless there is another possibility: key files. You should avoid using this option if you can avoid doing so due to the following risks: credential leakage (bad actor gains access to resources), privilege escalation (bad actor uses the service account to escalate their own privileges) and identity masking (bad actor conceals their identity through the service account).

Below is a sample Node.js code for using a key file:

				
					const {google} = require('googleapis');

const auth = new google.auth.GoogleAuth({
  keyFile: '/path/to/your-secret-key.json',
  scopes: ['https://www.googleapis.com/auth/cloud-platform'],
});

Service Account Impersonation

Service account impersonation in Google Cloud Platform (GCP) is a powerful tool for managing permissions effectively. It allows users to temporarily assume the permissions of a service account, streamlining access control and reducing security risks associated with long-lived keys.

Bird's eye perspective

A service account in Google Cloud Platform (GCP) is a special user account that is used by applications, servers, or automated processes, rather than a real person. This service account has specific permissions to do certain tasks in GCP. Such service accounts come in handy to be independent from user accounts (think about employee turnover).

Let’s imagine a specific service account has the role “BigQuery Admin” granted on project level to perform a daily data upload. The developer’s user account only has the role “BigQuery Data Viewer” granted.

Now, service account impersonation is like letting someone wear a „mask“ of this service account to do a job. In our case, the developer will act as the service account (impersonate it) to be able to use its more privileged permissions. This would allow the developer to perform tasks which are allowed by the “BigQuery Admin” role, e.g. create new tables.

One thing needs to be mentioned, the developer can only perform this impersonation if the developer’s user account has the necessary permissions to do so. One role which allows service account impersonation is “Service Account Token Creator“ (see Google documentation ).

Purpose of this method

Now it is time to describe why and when you should consider using this authentication method. The biggest advantages of this method are:

Temporary access

Let’s imagine a Service Account having a complex set of roles granted on different access levels (project-level, BigQuery dataset-level, BigQuery table-level etc.). Instead of granting the same set of roles to a user account, you could just grant the “Service Account Token Creator“ role and remove it when it is not needed anymore (or add a time based IAM condition to automatically remove the access on a specific point in time).

Reduce permission management

Impersonation centralizes permission management to a smaller number of service accounts, simplifying oversight and reducing potential misconfigurations.

Minimizing exposure window

In case of a security incident, it’s easier to revoke impersonation rights or change the permissions of the impersonated service account without affecting the user’s base permissions.

Cross project and/or organization

Direct role assignments across projects and/or organizations can be more complex to manage and may lead to broader access than necessary.

Service account keys

Service account impersonation eliminates the need to use and manage service account keys, which significantly enhances security. By avoiding the distribution of service account keys, the risk of key compromise is reduced.

Impersonation in action

The already mentioned role “Service Account Token Creator“ can be granted on different levels:

Organization level
Project level
Folder level
Service Account level

To check who has granted this role on Service Account level visit: GCP > IAM & Admin > Service Accounts > click on one SA > PERMISSIONS

One popular way to impersonate a Service Account is via gcloud CLI. You can use impersonation for a specific command via using the —impersonate-service-account flag:

				
					gcloud storage buckets list --impersonate-service-account=<<SA_EMAIL>>

To use impersonation for all commands you can use the following configuration:

				
					gcloud config set auth/impersonate_service_account <<SA_EMAIL>>

To stop the impersonation use this command:

				
					gcloud config unset auth/impersonate_service_account <<SA_EMAIL>>

Conclusion

To wrap things up, service account impersonation is key when it comes to keeping your Google Cloud Platform permissions both secure and manageable.

It cuts down on the risks tied to long-term service account keys, makes it easier to control who has access to what, and keeps things tidy with clear logs of who did what.

Whenever it makes sense, use service account impersonation instead of handing out direct roles.

If you are interested in this topic and/or you are looking for support from industry-leading experts, we would be really happy to advise you according to your specific needs! You can reach us via email: kontakt@e-dialog.group