Authentication Components

Classes
class	google::cloud::Credentials
	An opaque representation of the authentication configuration. More...
struct	google::cloud::UnifiedCredentialsOption
	A wrapper to store credentials into an options. More...
struct	google::cloud::DelegatesOption
	Configure the delegates for MakeImpersonateServiceAccountCredentials() More...
struct	google::cloud::ScopesOption
	Configure the scopes for MakeImpersonateServiceAccountCredentials() More...
struct	google::cloud::AccessTokenLifetimeOption
	Configure the access token lifetime. More...
struct	google::cloud::CARootsFilePathOption
	Configures a custom CA (Certificates Authority) certificates file. More...

Functions
std::shared_ptr< Credentials >	google::cloud::MakeInsecureCredentials (Options opts={})
	Create insecure (aka anonymous, aka unauthenticated) credentials. More...
std::shared_ptr< Credentials >	google::cloud::MakeGoogleDefaultCredentials (Options opts={})
	Creates the default credentials. More...
std::shared_ptr< Credentials >	google::cloud::MakeAccessTokenCredentials (std::string const &access_token, std::chrono::system_clock::time_point expiration, Options opts={})
	Creates credentials with a fixed access token. More...
std::shared_ptr< Credentials >	google::cloud::MakeImpersonateServiceAccountCredentials (std::shared_ptr< Credentials > base_credentials, std::string target_service_account, Options opts={})
	Creates credentials for service account impersonation. More...
std::shared_ptr< Credentials >	google::cloud::MakeServiceAccountCredentials (std::string json_object, Options opts={})
	Creates service account credentials from a service account key. More...
std::shared_ptr< Credentials >	google::cloud::MakeExternalAccountCredentials (std::string json_object, Options opts={})
	Creates credentials based on external accounts. More...

Detailed Description

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.

Development Workstations

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

1. 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.
2. 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.
3. 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.

Function Documentation

MakeAccessTokenCredentials()

std::shared_ptr< Credentials > google::cloud::MakeAccessTokenCredentials	(	std::string const &	access_token,
		std::chrono::system_clock::time_point	expiration,
		Options	opts = {}
	)

Creates credentials with a fixed access token.

These credentials are useful when using an out-of-band mechanism to fetch access tokens. Note that access tokens are time limited, you will need to manually refresh the tokens created by the

See also

https://cloud.google.com/docs/authentication for more information on authentication in GCP.

Parameters

access_token	the access token to be used by the client library.
expiration	the expiration time for the token.
opts	optional configuration values. Note that the effect of these parameters depends on the underlying transport. For example, TracingComponentsOption is ignored by gRPC-based services.

MakeExternalAccountCredentials()

std::shared_ptr< Credentials > google::cloud::MakeExternalAccountCredentials	(	std::string	json_object,
		Options	opts = {}
	)

Creates credentials based on external accounts.

Workload Identity Federation can grant on-premises or multi-cloud workloads access to Google Cloud resources, without using a service account key. You can use identity federation with Amazon Web Services (AWS), or with any identity provider that supports OpenID Connect (OIDC), such as Microsoft Azure, or SAML 2.0.

See also

https://cloud.google.com/docs/authentication for more information on authentication in GCP.

Parameters

json_object	the external account configuration as a JSON string. Typically applications read this from a file, or download the contents from something like Google's secret manager service. The configuration file can be created using the create-cred-config gcloud subcommand.
opts	optional configuration values. Note that the effect of these parameters depends on the underlying transport. For example, TracingComponentsOption is ignored by gRPC-based services.

MakeGoogleDefaultCredentials()

std::shared_ptr< Credentials > google::cloud::MakeGoogleDefaultCredentials

(

Options

opts = {}

)

Creates the default credentials.

These are the most commonly used credentials, and are expected to meet the needs of most applications. The Google Default Credentials conform to aip/4110. Consider using these credentials when:

• Your application is deployed to a GCP environment such as GCE, GKE, or Cloud Run. Each of these deployment environments provides a default service account to the application, and offers mechanisms to change the default credentials without any code changes to your application.
• You are testing or developing the application on a workstation (physical or virtual). These credentials will use your preferences as set with gcloud auth application-default. These preferences can be your own GCP user credentials, or some service account.
• Regardless of where your application is running, you can use the GOOGLE_APPLICATION_CREDENTIALS environment variable to override the defaults. This environment variable should point to a file containing a service account key file, or a JSON object describing your user credentials.

See also

https://cloud.google.com/docs/authentication for more information on authentication in GCP.

Parameters

opts	optional configuration values. Note that the effect of these parameters depends on the underlying transport. For example, TracingComponentsOption is ignored by gRPC-based services.

MakeImpersonateServiceAccountCredentials()

std::shared_ptr< Credentials > google::cloud::MakeImpersonateServiceAccountCredentials	(	std::shared_ptr< Credentials >	base_credentials,
		std::string	target_service_account,
		Options	opts = {}
	)

Creates credentials for service account impersonation.

Service account impersonation allows one account (user or service account) to act as a second account. This can be useful in multi-tenant services, where the service may perform some actions with an specific account associated with a tenant. The tenant can grant or restrict permissions to this tenant account.

When using service account impersonation is important to distinguish between the credentials used to obtain the target account credentials (the base_credentials) parameter, and the credentials representing the target_service_account.

Use AccessTokenLifetimeOption to configure the maximum lifetime of the obtained credentials. The default is 1h (3600s), see IAM quotas for the limits set by the platform and how to override them.

Use DelegatesOption to configure a sequence of intermediate service account, each of which has permissions to impersonate the next and the last one has permissions to impersonate target_service_account.

Use ScopesOption to restrict the authentication scope for the obtained credentials. See below for possible values.

See also

https://cloud.google.com/docs/authentication for more information on authentication in GCP.

https://cloud.google.com/iam/docs/impersonating-service-accounts for information on managing service account impersonation.

https://developers.google.com/identity/protocols/oauth2/scopes for authentication scopes in Google Cloud Platform.

Parameters

base_credentials	the credentials used to contact the IAM Credentials services.
target_service_account	the email address of the service account to impersonate.
opts	optional configuration values. Note that the effect of these parameters depends on the underlying transport. For example, TracingComponentsOption is ignored by gRPC-based services.

MakeInsecureCredentials()

std::shared_ptr< Credentials > google::cloud::MakeInsecureCredentials

(

Options

opts = {}

)

Create insecure (aka anonymous, aka unauthenticated) credentials.

These credentials are mostly intended for testing. Integration tests running against an emulator do not need to authenticate. In fact, it may be impossible to connect to an emulator using SSL/TLS because the emulators typically run without secure communication.

In addition, unit tests may benefit from using these credentials: loading the default credentials unnecessarily slows down the unit tests, and in some CI environments the credentials may fail to load, creating confusing warnings and sometimes even errors.

Parameters

opts	optional configuration values. Note that the effect of these parameters depends on the underlying transport. For example, TracingComponentsOption is ignored by gRPC-based services.

MakeServiceAccountCredentials()

std::shared_ptr< Credentials > google::cloud::MakeServiceAccountCredentials	(	std::string	json_object,
		Options	opts = {}
	)

Creates service account credentials from a service account key.

A service account is an account for an application or compute workload instead of an individual end user. The recommended practice is to use Google Default Credentials, which relies on the configuration of the Google Cloud system hosting your application (GCE, GKE, Cloud Run) to authenticate your workload or application. But sometimes you may need to create and download a service account key, for example, to use a service account when running your application on a system that is not part of Google Cloud.

Service account credentials are used in this latter case.

You can create multiple service account keys for a single service account. When you create a service account key, the key is returned as string, in the format described by aip/4112. This string contains an id for the service account, as well as the cryptographical materials (a RSA private key) required to authenticate the caller.

Therefore, services account keys should be treated as any other secret with security implications. Think of them as unencrypted passwords. Do not store them where unauthorized persons or programs may read them.

As stated above, most applications should probably use default credentials, maybe pointing them to a file with these contents. Using this function may be useful when the service account key is obtained from Cloud Secret Manager or a similar service.

Parameters

json_object	the service account configuration as a JSON string. Typically applications read this from a file, or download the contents from something like Google's secret manager service.
opts	optional configuration values. Note that the effect of these parameters depends on the underlying transport. For example, TracingComponentsOption is ignored by gRPC-based services.