Namespace google::cloud::storage::oauth2 (2.17.0)

Authentication components for Google Cloud Storage.

Classes

AnonymousCredentials

A Credentials type representing "anonymous" Google OAuth2.0 credentials.

AuthorizedUserCredentials<HttpRequestBuilderType, ClockType>

Wrapper class for Google OAuth 2.0 user account credentials.

ComputeEngineCredentials<HttpRequestBuilderType, ClockType>

Wrapper class for Google OAuth 2.0 GCE instance service account credentials.

Credentials

Interface for OAuth 2.0 credentials used to access Google Cloud services.

RefreshingCredentialsWrapper

Wrapper for refreshable parts of a Credentials object.

ServiceAccountCredentials<HttpRequestBuilderType, ClockType>

Wrapper class for Google OAuth 2.0 service account credentials.

Structs

AuthorizedUserCredentialsInfo

Object to hold information used to instantiate an AuthorizedUserCredentials.

ServiceAccountCredentialsInfo

Object to hold information used to instantiate an ServiceAccountCredentials.

ServiceAccountMetadata

A helper struct that contains service account metadata.

Enums

JwtSigningAlgorithms

Supported signing algorithms used in JWT auth flows.

Functions

CreateAnonymousCredentials()

Returns
Type Description
std::shared_ptr< Credentials >

CreateAuthorizedUserCredentialsFromJsonFilePath(std::string const &)

Creates an AuthorizedUserCredentials from a JSON file at the specified path.

Parameter
Name Description
path
Returns
Type Description
StatusOr< std::shared_ptr< Credentials > >

CreateAuthorizedUserCredentialsFromJsonContents(std::string const &, ChannelOptions const &)

Creates an AuthorizedUserCredentials from a JSON string.

Parameters
Name Description
contents
options
Returns
Type Description
StatusOr< std::shared_ptr< Credentials > >

CreateServiceAccountCredentialsFromFilePath(std::string const &)

Creates a ServiceAccountCredentials from a file at the specified path.

These credentials use the cloud-platform OAuth 2.0 scope, defined by GoogleOAuthScopeCloudPlatform(). To specify alternate scopes, use the overloaded version of this function.
Parameter
Name Description
path
Returns
Type Description
StatusOr< std::shared_ptr< Credentials > >

CreateServiceAccountCredentialsFromFilePath(std::string const &, absl::optional< std::set< std::string > >, absl::optional< std::string >)

Creates a ServiceAccountCredentials from a file at the specified path.

See Also

https://developers.google.com/identity/protocols/googlescopes for a list of OAuth 2.0 scopes used with Google APIs.

See Also

https://developers.google.com/identity/protocols/OAuth2ServiceAccount for more information about domain-wide delegation.

Parameters
Name Description
path

the path to the file containing service account JSON credentials.

scopes

the scopes to request during the authorization grant. If omitted, the cloud-platform scope, defined by GoogleOAuthScopeCloudPlatform(), is used as a default.

subject

for domain-wide delegation; the email address of the user for which to request delegated access. If omitted, no "subject" attribute is included in the authorization grant.

Returns
Type Description
StatusOr< std::shared_ptr< Credentials > >

CreateServiceAccountCredentialsFromJsonFilePath(std::string const &)

Creates a ServiceAccountCredentials from a JSON file at the specified path.

These credentials use the cloud-platform OAuth 2.0 scope, defined by GoogleOAuthScopeCloudPlatform(). To specify alternate scopes, use the overloaded version of this function.

Parameter
Name Description
path
Returns
Type Description
StatusOr< std::shared_ptr< Credentials > >

CreateServiceAccountCredentialsFromJsonFilePath(std::string const &, absl::optional< std::set< std::string > >, absl::optional< std::string >, ChannelOptions const &)

Creates a ServiceAccountCredentials from a JSON file at the specified path.

See Also

https://developers.google.com/identity/protocols/googlescopes for a list of OAuth 2.0 scopes used with Google APIs.

See Also

https://developers.google.com/identity/protocols/OAuth2ServiceAccount for more information about domain-wide delegation.

Parameters
Name Description
path

the path to the file containing service account JSON credentials.

scopes

the scopes to request during the authorization grant. If omitted, the cloud-platform scope, defined by GoogleOAuthScopeCloudPlatform(), is used as a default.

subject

for domain-wide delegation; the email address of the user for which to request delegated access. If omitted, no "subject" attribute is included in the authorization grant.

options

any configuration needed for the transport channel to Google's authentication servers.

Returns
Type Description
StatusOr< std::shared_ptr< Credentials > >

CreateServiceAccountCredentialsFromP12FilePath(std::string const &)

Creates a ServiceAccountCredentials from a P12 file at the specified path.

These credentials use the cloud-platform OAuth 2.0 scope, defined by GoogleOAuthScopeCloudPlatform(). To specify alternate scopes, use the overloaded version of this function.

Parameter
Name Description
path
Returns
Type Description
StatusOr< std::shared_ptr< Credentials > >

CreateServiceAccountCredentialsFromP12FilePath(std::string const &, absl::optional< std::set< std::string > >, absl::optional< std::string >, ChannelOptions const &)

Creates a ServiceAccountCredentials from a P12 file at the specified path.

See Also

https://developers.google.com/identity/protocols/googlescopes for a list of OAuth 2.0 scopes used with Google APIs.

See Also

https://developers.google.com/identity/protocols/OAuth2ServiceAccount for more information about domain-wide delegation.

Parameters
Name Description
path

the path to the file containing service account JSON credentials.

scopes

the scopes to request during the authorization grant. If omitted, the cloud-platform scope, defined by GoogleOAuthScopeCloudPlatform(), is used as a default.

subject

for domain-wide delegation; the email address of the user for which to request delegated access. If omitted, no "subject" attribute is included in the authorization grant.

options

any configuration needed for the transport channel to Google's authentication servers.

Returns
Type Description
StatusOr< std::shared_ptr< Credentials > >

ParseAuthorizedUserRefreshResponse(storage::internal::HttpResponse const &, std::chrono::system_clock::time_point)

Parses a refresh response JSON string into an authorization header.

The header and the current time (for the expiration) form a TemporaryToken.

Parameters
Name Description
response
now
Returns
Type Description
StatusOr< RefreshingCredentialsWrapper::TemporaryToken >

ParseAuthorizedUserCredentials(std::string const &, std::string const &, std::string const &)

Parses a user credentials JSON string into an AuthorizedUserCredentialsInfo.

Parameters
Name Description
content
source
default_token_uri
Returns
Type Description
StatusOr< AuthorizedUserCredentialsInfo >

ParseMetadataServerResponse(storage::internal::HttpResponse const &)

Parses a metadata server response JSON string into a ServiceAccountMetadata.

Parameter
Name Description
response
Returns
Type Description
StatusOr< ServiceAccountMetadata >

ParseComputeEngineRefreshResponse(storage::internal::HttpResponse const &, std::chrono::system_clock::time_point)

Parses a refresh response JSON string into an authorization header.

The header and the current time (for the expiration) form a TemporaryToken.

Parameters
Name Description
response
now
Returns
Type Description
StatusOr< RefreshingCredentialsWrapper::TemporaryToken >

GoogleOAuthAccessTokenLifetime()

The max lifetime in seconds of an access token.

Returns
Type Description
constexpr std::chrono::seconds

GoogleOAuthAccessTokenExpirationSlack()

Returns the slack to consider when checking if an access token is expired.

This time should be subtracted from a token's expiration time when checking if it is expired. This prevents race conditions where, for example, one might check expiration time one second before the expiration, see that the token is still valid, then attempt to use it two seconds later and receive an error.

Returns
Type Description
constexpr std::chrono::seconds

GoogleOAuthRefreshEndpoint()

The endpoint to fetch an OAuth 2.0 access token from.

Returns
Type Description
char const *

GoogleOAuthScopeCloudPlatform()

String representing the "cloud-platform" OAuth 2.0 scope.

Returns
Type Description
char const *

GoogleAdcEnvVar()

Returns the Application Default Credentials environment variable name.

This environment variable should be checked for a valid file path when attempting to load Google Application Default Credentials.

Returns
Type Description
char const *

GoogleAdcFilePathFromEnvVarOrEmpty()

Returns the path to the Application Default Credentials file, if set.

If the Application Default Credentials environment variable is set, we check the path specified by its value for a file containing ADCs. Returns an empty string if no such path exists or the environment variable is not set.

Returns
Type Description
std::string

GoogleAdcFilePathFromWellKnownPathOrEmpty()

Returns the path to the Application Default Credentials file, if set.

If the gcloud utility has configured an Application Default Credentials file, the path to that file is returned. Returns an empty string if no such file exists at the well known path.

Returns
Type Description
std::string

GoogleGcloudAdcFileEnvVar()

Returns the environment variable to override the gcloud ADC path.

This environment variable is used for testing to override the path that should be searched for the gcloud Application Default Credentials file.

Returns
Type Description
char const *

GoogleAdcHomeEnvVar()

Returns the environment variable used to construct the well known ADC path.

The directory containing a user's application configuration data, indicated by this environment variable, varies across environments. That directory is used when constructing the well known path of the Application Default Credentials file.

Returns
Type Description
char const *

GoogleDefaultCredentials(ChannelOptions const &)

Produces a Credentials type based on the runtime environment.

If the GOOGLE_APPLICATION_CREDENTIALS environment variable is set, the JSON file it points to will be loaded and used to create a credential of the specified type. Otherwise, if running on a Google-hosted environment (e.g. Compute Engine), credentials for the environment's default service account will be used.

See Also

https://cloud.google.com/docs/authentication/production for details about Application Default Credentials.

Parameter
Name Description
options
Returns
Type Description
StatusOr< std::shared_ptr< Credentials > >

CreateServiceAccountCredentialsFromDefaultPaths(ChannelOptions const &)

Produces a ServiceAccountCredentials type by trying to load the standard Application Default Credentials paths.

If the GOOGLE_APPLICATION_CREDENTIALS environment variable is set, the JSON or P12 file it points to will be loaded. Otherwise, if the gcloud utility has configured an Application Default Credentials file, that file is loaded. The loaded file is used to create a ServiceAccountCredentials.

See Also

https://cloud.google.com/docs/authentication/production for details about Application Default Credentials.

Parameter
Name Description
options

any configuration needed for the transport channel to Google's authentication servers.

Returns
Type Description
StatusOr< std::shared_ptr< Credentials > >

CreateServiceAccountCredentialsFromDefaultPaths(absl::optional< std::set< std::string > >, absl::optional< std::string >, ChannelOptions const &)

Produces a ServiceAccountCredentials type by trying to load the standard Application Default Credentials paths.

If the GOOGLE_APPLICATION_CREDENTIALS environment variable is set, the JSON or P12 file it points to will be loaded. Otherwise, if the gcloud utility has configured an Application Default Credentials file, that file is loaded. The loaded file is used to create a ServiceAccountCredentials.

See Also

https://developers.google.com/identity/protocols/googlescopes for a list of OAuth 2.0 scopes used with Google APIs.

See Also

https://cloud.google.com/docs/authentication/production for details about Application Default Credentials.

Parameters
Name Description
scopes

the scopes to request during the authorization grant. If omitted, the cloud-platform scope, defined by GoogleOAuthScopeCloudPlatform(), is used as a default.

subject

for domain-wide delegation; the email address of the user for which to request delegated access. If omitted, no "subject" attribute is included in the authorization grant.

options

any configuration needed for the transport channel to Google's authentication servers.

Returns
Type Description
StatusOr< std::shared_ptr< Credentials > >

CreateServiceAccountCredentialsFromJsonContents(std::string const &, ChannelOptions const &)

Creates a ServiceAccountCredentials from a JSON string.

These credentials use the cloud-platform OAuth 2.0 scope, defined by GoogleOAuthScopeCloudPlatform(). To specify an alternate set of scopes, use the overloaded version of this function.

Parameters
Name Description
contents
options
Returns
Type Description
StatusOr< std::shared_ptr< Credentials > >

CreateServiceAccountCredentialsFromJsonContents(std::string const &, absl::optional< std::set< std::string > >, absl::optional< std::string >, ChannelOptions const &)

Creates a ServiceAccountCredentials from a JSON string.

See Also

https://developers.google.com/identity/protocols/googlescopes for a list of OAuth 2.0 scopes used with Google APIs.

See Also

https://developers.google.com/identity/protocols/OAuth2ServiceAccount for more information about domain-wide delegation.

Parameters
Name Description
contents

the string containing the JSON contents of a service account credentials file.

scopes

the scopes to request during the authorization grant. If omitted, the cloud-platform scope, defined by GoogleOAuthScopeCloudPlatform(), is used as a default.

subject

for domain-wide delegation; the email address of the user for which to request delegated access. If omitted, no "subject" attribute is included in the authorization grant.

options

any configuration needed for the transport channel to Google's authentication servers.

Returns
Type Description
StatusOr< std::shared_ptr< Credentials > >

CreateComputeEngineCredentials()

Creates a ComputeEngineCredentials for the VM's default service account.

Returns
Type Description
std::shared_ptr< Credentials >

CreateComputeEngineCredentials(std::string const &)

Creates a ComputeEngineCredentials for the VM's specified service account.

Parameter
Name Description
service_account_email
Returns
Type Description
std::shared_ptr< Credentials >

ParseServiceAccountCredentials(std::string const &, std::string const &, std::string const &)

Parses the contents of a JSON keyfile into a ServiceAccountCredentialsInfo.

Parameters
Name Description
content
source
default_token_uri
Returns
Type Description
StatusOr< ServiceAccountCredentialsInfo >

ParseServiceAccountP12File(std::string const &, std::string const &)

Parses the contents of a P12 keyfile into a ServiceAccountCredentialsInfo.

Parameters
Name Description
source
default_token_uri
Returns
Type Description
StatusOr< ServiceAccountCredentialsInfo >

ParseServiceAccountRefreshResponse(storage::internal::HttpResponse const &, std::chrono::system_clock::time_point)

Parses a refresh response JSON string and uses the current time to create a TemporaryToken.

Parameters
Name Description
response
now
Returns
Type Description
StatusOr< RefreshingCredentialsWrapper::TemporaryToken >

AssertionComponentsFromInfo(ServiceAccountCredentialsInfo const &, std::chrono::system_clock::time_point)

Splits a ServiceAccountCredentialsInfo into header and payload components and uses the current time to make a JWT assertion.

Parameters
Name Description
info
now
Returns
Type Description
std::pair< std::string, std::string >

MakeJWTAssertion(std::string const &, std::string const &, std::string const &)

Given a key and a JSON header and payload, creates a JWT assertion string.

See Also

https://tools.ietf.org/html/rfc7519

Parameters
Name Description
header
payload
pem_contents
Returns
Type Description
std::string

CreateServiceAccountRefreshPayload(ServiceAccountCredentialsInfo const &, std::string const &, std::chrono::system_clock::time_point)

Uses a ServiceAccountCredentialsInfo and the current time to construct a JWT assertion.

The assertion combined with the grant type is used to create the refresh payload.

Parameters
Name Description
info
grant_type
now
Returns
Type Description
std::string

MakeSelfSignedJWT(ServiceAccountCredentialsInfo const &, std::chrono::system_clock::time_point)

Make a self-signed JWT from the service account.

Self-signed JWTs bypass the intermediate step of exchanging client assertions for OAuth tokens. The advantages of self-signed JTWs include:

  • They are more efficient, as they require more or less the same amount of local work, and save a round-trip to the token endpoint, typically https://oauth2.googleapis.com/token.
  • While this service is extremely reliable, removing external dependencies in the critical path almost always improves reliability.
  • They work better in VPC-SC environments and other environments with limited Internet access.
Parameters
Name Description
info

the parsed service account information, see ParseServiceAccountCredentials()

tp

the current time

Returns
Type Description
StatusOr< std::string >

a bearer token for authentication. Include this value in the Authorization header with the "Bearer" type.

ServiceAccountUseOAuth(ServiceAccountCredentialsInfo const &)

Return true if we need to use the OAuth path to create tokens.

Parameter
Name Description
info
Returns
Type Description
bool