Authentication Components (2.34.0-rc)

Authentication Components

Overview and Motivation

Most services in Google Cloud Platform require the client to authenticate the requests. Notable exceptions include public buckets in GCS and public data sets in BigQuery. The C++ client libraries are automatically configured to use Application Default Credentials, but some applications may need to override this default. The functions and classes related to changing the authentication configuration are documented here.

This document is not a general introduction to authentication for Google Cloud Platform. For readers seeking such an introduction we recommend Authentication at Google as a good starting point. Covering authorization in any detail is also out of scope. We recommend reading the IAM overview if that is of interest.

The most common motivation to change authentication is to use a different principal, that is, to make the request(s) on behalf of a different user or robot account. In many cases the default principal can be changed without having to change any code. The Application Default Credentials can be configured via environment variables, or via the gcloud CLI. If your application is running in GCE, Cloud Run, GKE or a similar environment you or the system administrator may change the service account associated with this deployment environment. Consider using these mechanisms instead of changing the code, as that may give your DevOps, SRE, or system administration team more flexibility.

General Concepts

While a complete overview of authentication and authorization for Google Cloud is outside the scope of this document, a brief introduction may help.

As we mentioned in passing, authentication supports both user accounts and service accounts. These are referred as "principals". User accounts represent a developer, administrator, or any other person who interacts with GCP services. In contrast, service accounts are accounts that do not represent a person. They typically represent an application, or another service.

Google Cloud Platform largely uses OAuth2 access tokens for authentication. There are multiple ways to create such tokens. For example, when running on GCE the VM has access to a metadata server that can create these tokens for any application running on the VM. As another example, you can download a service account keyfile and the C++ client libraries will create access tokens using the contents of this file.

Access tokens are bearer tokens. Having the token authenticates the principal, they can be used in separate connections, or from different computers than the one used to create them. If these tokens are exposed to third-parties the token can be used to make calls on behalf of the principal identified by the token. To reduce exposure, access tokens are always time limited. They automatically expire after a period of time (usually one hour).

The client libraries automatically refresh access tokens, that is, create new tokens before they expire. The only exception is MakeAccessTokenCredentials(), where the application provides the access token.

The client libraries also support authentication without a principal via API keys. Note that while the client libraries support sending the API key, not all Google Cloud Platform services support this method of authentication.

Development Workstations

We find that developers typically use Application Default Credentials to test their applications. The developer would either:

Use gcloud auth application-default to authenticate using the developer's account. Keep in mind that this persists a "refresh token" in your workstation's filesystem. This refresh token is long-lived and can be used to create access tokens with full access to all GCP services.
Set the GOOGLE_APPLICATION_CREDENTIALS environment variable to load a service account key. The value of this environment variable is the full path of a file that contains the service account key. Keep in mind the security implications of keeping such a file as plain text in your filesystem.
If you are using a GCE instance as your development environment, simply use the service account of the GCE machine to access GCP services.

Limitations

The C++ authentication components do not allow applications to create their own credential types. It is not possible to extend the C++ libraries without changing internal components. If you need additional functionality please file a feature request on GitHub. Likewise, creating the components that implement (as opposed to describing) authentication flows are also considered implementation details. If you would like to use them in your own libraries please file a feature request. We cannot promise that we will be able to satisfy these requests, but we will give them full consideration.