<GoogleAuth>

The <GoogleAuth> block authenticates to Google Cloud with a service account key, an interactive Google sign-in, or an existing local gcloud configuration. Once authenticated, the credentials are available to subsequent Command and Check blocks.

By default, GoogleAuth looks for existing credentials in environment variables (GOOGLE_APPLICATION_CREDENTIALS, GOOGLE_CREDENTIALS, and others) and then in the Application Default Credentials file. If it finds any, it validates them and asks the user to confirm before using them. See Credential detection.

Basic usage

<GoogleAuth
  id="google-auth"
  title="Authenticate to Google Cloud"
  description="Choose your preferred authentication method"
  defaultRegion="us-central1"
/>

Authentication methods

The block has three tabs:

Tab	Description
Service Account Key	Paste (or load from disk) a service account JSON key
Google Sign-In	Interactive browser sign-in that produces user credentials, the same thing gcloud auth application-default login produces. Requires an OAuth client. See Google Sign-In
gcloud Config	Reuse a configuration and Application Default Credentials that already exist on the machine

All three tabs also offer an optional Default Region picker, which seeds the region environment variables for subsequent commands. It starts on defaultRegion; choosing No default region sets no region at all (on the gcloud Config tab, the configuration’s own compute/region then applies).

Service Account Key is the tab users land on. Set defaultTab to open on a different one:

<GoogleAuth id="gcp-auth" defaultTab="gcloud" />

The user can still switch tabs.

Note

Runbooks never shells out to the gcloud binary. Service account keys are validated by minting a real access token, sign-in uses a loopback OAuth redirect, and the gcloud tab reads gcloud’s own configuration files directly. You do not need the Google Cloud CLI installed for any of the three tabs. The gcloud Config tab needs the configuration files a previous gcloud run created.

Props

Prop	Type	Default	Description
id	string	required	Unique identifier for this component
title	string	"Google Cloud Authentication"	Display title shown in the UI (supports template expressions)
description	string	-	Description of the authentication purpose (supports template expressions)
autoCollapse	boolean	false	Folds the block down to its title once it’s signed in. See Folding done blocks
project	string	-	Pin a Google Cloud project. When set, project selection is skipped and this project is used (supports template expressions)
defaultRegion	string	-	Default compute region for subsequent commands. Sets GOOGLE_CLOUD_REGION, CLOUDSDK_COMPUTE_REGION, and GOOGLE_REGION
defaultZone	string	-	Default compute zone for subsequent commands. Sets CLOUDSDK_COMPUTE_ZONE and GOOGLE_ZONE
gcloudConfiguration	string	-	Pre-select a named gcloud configuration in the gcloud Config tab. It doesn’t change which configuration detection reads. See gcloud Config (supports template expressions)
defaultTab	'service_account', 'oauth', or 'gcloud'	'service_account'	Which authentication tab the block opens on. An unrecognized value falls back to 'service_account'
scopes	string[]	cloud-platform, userinfo.email, openid	OAuth scopes requested by Google Sign-In. When set, also required of any auto-detected or gcloud user ADC this block will accept (service account keys and impersonated service accounts are exempt)
oauthClientId	string	-	Client ID of a Google Cloud “Desktop app” OAuth client. Must be paired with oauthClientSecret. Mutually exclusive with oauthClientFile. See Using your own OAuth client
oauthClientSecret	string	-	Client secret issued alongside the Desktop OAuth client. Required whenever oauthClientId is set. Per RFC 8252 this value is not confidential. Google issues one with every Desktop client
oauthClientFile	string	-	Path to a Google Cloud Console Desktop-app client JSON download (client_secret_*.json with an installed object). ~ is expanded, and template expressions are resolved. Mutually exclusive with oauthClientId / oauthClientSecret. Read in the main process only
detectCredentials	false | GoogleCredentialSource[]	['env', 'adc']	Whether and how to detect existing credentials. See Credential detection
inputsId	string | string[]	-	Reference one or more Inputs blocks for template expressions in props

Caution

detectCredentials takes a JSX expression. Write detectCredentials={false}, or an array such as detectCredentials={['env']}. A string, such as detectCredentials="env", is not an array, so the block detects nothing.

Environment variables

When authentication succeeds, the following environment variables are set in the session environment for subsequent Command and Check blocks:

Variable	Value
GOOGLE_APPLICATION_CREDENTIALS	Absolute path to the credentials file backing this session
CLOUDSDK_AUTH_CREDENTIAL_FILE_OVERRIDE	The same path, in the property the gcloud CLI reads. See Bridging to the gcloud CLI
GOOGLE_CLOUD_PROJECT	The selected project ID
CLOUDSDK_CORE_PROJECT	The selected project ID (read by the gcloud CLI)
GOOGLE_PROJECT	The selected project ID (read by the OpenTofu/Terraform google provider)
CLOUDSDK_CORE_ACCOUNT	The authenticated principal, a service account or user email address

These are set only when the corresponding value is known:

Variable	Source
GOOGLE_CLOUD_REGION, CLOUDSDK_COMPUTE_REGION, GOOGLE_REGION	defaultRegion, the Default Region picker, or else the gcloud configuration’s compute/region (or, for a credential detected in environment variables, their region)
CLOUDSDK_COMPUTE_ZONE, GOOGLE_ZONE	defaultZone, or else the gcloud configuration’s compute/zone (or the detected environment’s zone)
CLOUDSDK_ACTIVE_CONFIG_NAME	gcloud Config tab only. The name of the configuration you authenticated with

Google client libraries and the OpenTofu/Terraform google provider read GOOGLE_APPLICATION_CREDENTIALS. The gcloud CLI reads CLOUDSDK_AUTH_CREDENTIAL_FILE_OVERRIDE, which GoogleAuth also sets. See Bridging to the gcloud CLI.

Note

Runbooks does not write key material into an environment variable. GOOGLE_APPLICATION_CREDENTIALS points at a file: either a credentials file that already existed on your machine, or a 0600 file written to a private temporary directory that is deleted when the app quits. The exception is a credential that is only an access token (see Access token credentials).

Bridging to the gcloud CLI

Application Default Credentials (GOOGLE_APPLICATION_CREDENTIALS) and the gcloud CLI’s own login state (gcloud auth login, stored in a local credentials.db) are two separate credential stores. When the CLI has any account configured, it prefers that account over ADC and ignores GOOGLE_APPLICATION_CREDENTIALS. Without the bridge, a bare gcloud command in a <Command> block would use that CLI login, which may have expired, and fail with an error such as:

ERROR: (gcloud.organizations.list) UNAUTHENTICATED: Request had invalid authentication
credentials. Expected OAuth 2 access token, login cookie or other valid authentication
credential.

Whenever GoogleAuth writes or points at a credentials file, it also sets CLOUDSDK_AUTH_CREDENTIAL_FILE_OVERRIDE to the same path, so the CLI uses that file and ignores its own login state. Re-authenticating, including with a different credential type, updates it.

Caution

The bridge needs a credentials file, and an access-token-only credential has none. In that case, bare gcloud commands use whatever CLI login is already configured on the machine. Do not work around this by exporting a bearer token as CLOUDSDK_AUTH_ACCESS_TOKEN yourself. Some older Google APIs (for example Cloud Resource Manager v1’s Organizations.SearchOrganizations, which gcloud organizations list calls) reject a bearer presented that way with ACCESS_TOKEN_TYPE_UNSUPPORTED.

Block outputs

The block also publishes its result as block outputs, so a specific GoogleAuth block can be referenced by ID:

Output	Value
GOOGLE_APPLICATION_CREDENTIALS	Path to the credentials file for this block
CLOUDSDK_AUTH_CREDENTIAL_FILE_OVERRIDE	The same path, in the property the gcloud CLI reads. Blank for an access-token-only credential
GOOGLE_CLOUD_PROJECT, CLOUDSDK_CORE_PROJECT, GOOGLE_PROJECT	The selected project ID
CLOUDSDK_CORE_ACCOUNT	The authenticated principal
GOOGLE_CLOUD_REGION, CLOUDSDK_COMPUTE_REGION, GOOGLE_REGION	The region the block wrote to the session (see above), if any
CLOUDSDK_COMPUTE_ZONE, GOOGLE_ZONE	The zone the block wrote to the session, if any
GOOGLE_AUTH_TYPE	How the credential was obtained: service_account, authorized_user, external_account, impersonated_service_account, or access_token
__AUTHENTICATED	Always true once the block has authenticated

Using with Commands and Checks

Subsequent Command and Check blocks get the environment variables above, so they use the most recently authenticated GoogleAuth block. A later Google Cloud authentication becomes the new default and overwrites the variables its own credential sets. So does picking a project with Change project on a block’s success card. Variables it does not set can remain from an earlier block. See Multiple projects.

To bind a block to one specific GoogleAuth block, use the googleAuthId prop. The referenced block’s outputs are injected into that execution only, and the Run button stays disabled until that block has authenticated:

<GoogleAuth
  id="google-auth"
  title="Authenticate to Google Cloud"
  project="my-project-123456"
  defaultRegion="us-central1"
/>

<Check
  id="verify-identity"
  title="Verify Google Cloud Identity"
  command="gcloud auth list --filter=status:ACTIVE --format='value(account)'"
  googleAuthId="google-auth"
  successMessage="Successfully authenticated!"
/>

<Command
  id="list-buckets"
  title="List Storage Buckets"
  command="gcloud storage ls"
  googleAuthId="google-auth"
  successMessage="Buckets listed!"
/>

Tip

Without googleAuthId, subsequent blocks still have Google Cloud access through the session environment variables.

Multiple projects

You can include multiple GoogleAuth blocks in a single runbook to authenticate against different projects, or with different principals:

<GoogleAuth
  id="source-project"
  title="Source Project (Development)"
  project="acme-dev-123456"
  defaultRegion="us-central1"
/>

<Command
  id="export-data"
  title="Export Data from Source"
  command="gcloud storage cp gs://acme-dev-data/export.json /tmp/export.json"
  googleAuthId="source-project"
/>

<GoogleAuth
  id="target-project"
  title="Target Project (Production)"
  project="acme-prod-987654"
  defaultRegion="europe-west1"
/>

<Command
  id="import-data"
  title="Import Data to Target"
  command="gcloud storage cp /tmp/export.json gs://acme-prod-data/import.json"
  googleAuthId="target-project"
/>

Caution

With multiple GoogleAuth blocks, the block that most recently authenticated or changed project is the session default. Becoming the default switches only the session variables that block’s own credential sets:

• Its credentials file and CLOUDSDK_AUTH_CREDENTIAL_FILE_OVERRIDE. For an access-token-only credential, its access token is set and the override is cleared.
• Its account, and its project if it has one.
• The region and zone it authenticated with.
• CLOUDSDK_ACTIVE_CONFIG_NAME, if it used a gcloud configuration.

Variables that block does not set stay from whichever block set them last:

• GOOGLE_OAUTH_ACCESS_TOKEN and CLOUDSDK_AUTH_ACCESS_TOKEN from an access-token block. The OpenTofu/Terraform google provider prefers that token over GOOGLE_APPLICATION_CREDENTIALS.
• CLOUDSDK_ACTIVE_CONFIG_NAME from a block that used a gcloud configuration.
• GOOGLE_CLOUD_PROJECT, CLOUDSDK_CORE_PROJECT and GOOGLE_PROJECT, when the block authenticated with no project (for example, Google Sign-In with no project prop and no project the account can list).
• A region or zone the block did not set.
• For an access-token block, the GOOGLE_APPLICATION_CREDENTIALS of the last file-backed credential (another block’s, or its own before it switched to a token), which Google client libraries read.

So with several GoogleAuth blocks, use googleAuthId on every command. It injects the referenced block’s credentials file, CLOUDSDK_AUTH_CREDENTIAL_FILE_OVERRIDE, account, and any project, region or zone it set into that command. It does not unset the variables listed above, so a runbook that mixes an access-token credential with file-backed ones can still hand a googleAuthId command another block’s credential. Each block keeps its own credentials file, so the two never collide.

Service Account Key

The Service Account Key tab accepts the full JSON key file that Google Cloud produces for a service account. It also accepts the other Google credential documents, such as user credentials (authorized_user), and validates them as Application Default Credentials. It takes them two ways:

• Paste it into the field, which is masked with a reveal toggle.
• Choose key file… opens a native file picker. Only the path is recorded. The app’s main process reads and validates the key, and the interface never loads it.

The two are alternatives: choosing a file clears a pasted key, and typing into the field clears a chosen file.

Two optional fields refine the result:

• Project ID overrides the project. It starts out showing the project prop, if set. Leave it blank to use the key’s own project_id.
• Default Region sets the region environment variables.

The key is validated by exchanging it for a real access token, so an expired, revoked, disabled, or malformed key fails immediately with the reason shown inline. On success, GOOGLE_APPLICATION_CREDENTIALS points at the key: a file you chose is used where it already lives, and a pasted key is written to a private 0600 file that is deleted when Runbooks quits.

Caution

A service account key is long-lived key material. Prefer Google Sign-In or the gcloud Config tab for interactive use, and reserve key files for automation contexts where nothing else is available.

Google Sign-In

Caution

This tab requires a Google Cloud “Desktop app” OAuth client, and Runbooks builds include none. Until you supply one through props, a client JSON file, operator environment variables, or the in-session file picker, the tab is labeled (needs OAuth client) and sign-in cannot start. See Using your own OAuth client. The Service Account Key and gcloud Config tabs need no client.

The Google Sign-In tab performs the same loopback OAuth flow as gcloud auth application-default login:

1. Runbooks opens a listener bound to 127.0.0.1 on an ephemeral port and opens your browser at Google’s consent screen (PKCE, S256).
2. You approve the requested scopes in the browser.
3. Google redirects back to the loopback listener, Runbooks exchanges the code for a refresh token, writes a user-credentials file, and closes the listener.

The requested scopes default to:

• https://www.googleapis.com/auth/cloud-platform
• https://www.googleapis.com/auth/userinfo.email
• openid

Override them with the scopes prop. The tab’s What permissions does this grant? disclosure lists what will be requested.

When scopes is set, existing credentials must grant them too. Auto-detected env/ADC credentials and the gcloud Config tab refuse a user credential whose tokeninfo grant is missing any listed scope. The block shows the missing scopes and offers Sign in with required scopes, or a copyable gcloud auth application-default login --client-id-file="$GOOGLE_OAUTH_CLIENT_CREDENTIALS" --scopes=... command when Sign-In has no Desktop client. The default scopes apply to Sign-In requests only and are not enforced on existing ADC.

<GoogleAuth
  id="google-auth"
  title="Sign in to Google Cloud"
  scopes={[
    'https://www.googleapis.com/auth/cloud-platform',
    'https://www.googleapis.com/auth/admin.directory.rolemanagement',
    'https://www.googleapis.com/auth/userinfo.email',
    'openid',
  ]}
/>

The flow returns a refresh token, so the credential does not expire mid-runbook. The refresh token is written to a 0600 file and is not sent to the UI.

Using your own OAuth client

Sign-in requires a registered Google Cloud Desktop app OAuth client. The main process looks for one in this order:

1. Author props oauthClientId + oauthClientSecret
2. Author prop oauthClientFile (path to the Console download JSON)
3. Operator env GOOGLE_OAUTH_CLIENT_CREDENTIALS (path to the same JSON)
4. Operator env GOOGLE_OAUTH_CLIENT_ID + GOOGLE_OAUTH_CLIENT_SECRET
5. A client compiled into the build. Runbooks builds include none.

To pass the ID and secret as props:

<GoogleAuth
  id="google-auth"
  oauthClientId="123456789012-abcdefghijklmnop.apps.googleusercontent.com"
  oauthClientSecret="GOCSPX-example-not-a-real-secret"
/>

Both props are required together. oauthClientId on its own is refused with an error. Google issues a client secret with every Desktop client, and a user-credentials file written without it cannot be refreshed, so every later gcloud, client-library, and OpenTofu call would fail at the first token refresh.

To pass the client JSON file, the Desktop-app download from Google Cloud Console ({ "installed": { "client_id", "client_secret", ... } }):

<GoogleAuth
  id="google-auth"
  oauthClientFile="~/.config/gcloud/client_secret_example.json"
/>

oauthClientFile is mutually exclusive with oauthClientId / oauthClientSecret. The main process reads the file (~ is expanded), and the secret is not sent to the UI. Web-client downloads ({ "web": ... }) are rejected because Sign-In uses a loopback redirect registered for Desktop clients.

The operator can set a client in the environment of the machine, with no change to the runbook:

Variable	Value
GOOGLE_OAUTH_CLIENT_CREDENTIALS	Absolute or ~/... path to a Desktop-app client_secret_*.json
GOOGLE_OAUTH_CLIENT_ID	Desktop-app client ID (must be paired with the secret)
GOOGLE_OAUTH_CLIENT_SECRET	Desktop-app client secret

These are separate from GOOGLE_APPLICATION_CREDENTIALS, which points at the user or service-account credentials produced by authentication.

When no client is configured, the Google Sign-In tab stays selectable and is labeled (needs OAuth client). Its panel offers Choose Desktop OAuth client JSON, which takes the same Console download as oauthClientFile and GOOGLE_OAUTH_CLIENT_CREDENTIALS. The interface keeps only the path. The main process reads installed.client_id and installed.client_secret when sign-in starts.

gcloud Config

The gcloud Config tab lists the configurations found in your gcloud configuration directory:

Platform	Location
macOS / Linux	~/.config/gcloud
Windows	%APPDATA%\gcloud
Any	$CLOUDSDK_CONFIG, when set

Each row shows the configuration’s account, project, and a badge describing what it can authenticate with:

Badge	Meaning
User ADC	Application Default Credentials from gcloud auth application-default login
Service Account ADC	Application Default Credentials backed by a service account key
Federated ADC	Workforce-pool sign-in or an impersonated service account. Workload identity federation that sources its subject token from a file, a URL, or an executable (credential_source) is listed but rejected on use. See Federated credential limits
No ADC	A configuration exists, but there are no Application Default Credentials to use. Not selectable
Unsupported	Nothing usable could be read from this configuration

A gcloud configuration records which account and project to use. The credential itself is in application_default_credentials.json. Rows marked No ADC are listed but not selectable, with a hint to run:

gcloud auth application-default login

Authenticating from this tab copies nothing. GOOGLE_APPLICATION_CREDENTIALS points at your existing credentials file, and CLOUDSDK_ACTIVE_CONFIG_NAME records the configuration name.

To pre-select a configuration on this tab, set the gcloudConfiguration prop. Set defaultTab="gcloud" too, so the block opens on the tab:

<GoogleAuth
  id="google-auth"
  title="Use your local gcloud setup"
  defaultTab="gcloud"
  gcloudConfiguration="production"
/>

The user can still pick another configuration. gcloudConfiguration doesn’t affect credential detection: the 'gcloud' source always reads the active configuration.

Note

Only application_default_credentials.json is read. The gcloud CLI keeps its own login state in a credentials.db SQLite database, which Runbooks does not open, so being logged in with gcloud auth login alone is not enough. Run gcloud auth application-default login as well.

Project selection

The project decides what your commands operate on.

• If the project prop is set, that project is pinned and no picker is shown.
• Otherwise, on the Service Account Key tab the key’s own project_id is used when present.
• Otherwise, if the credential can see exactly one project, it is selected automatically.
• Otherwise, a searchable project picker is shown before the block reports success.

Once authenticated, the success card offers Change project to switch to another project the same credential can see, and Re-authenticate to start over.

Picking a project makes the block the session default again. The session variables its own credential sets switch together: its credentials file and CLOUDSDK_AUTH_CREDENTIAL_FILE_OVERRIDE (or its access token), its account, and the new project. The block keeps the region and zone it authenticated with. Variables it does not set can remain from another GoogleAuth block. See Multiple projects.

Cancel in a picker opened by Change project returns to the success card and keeps the current project. If the project list cannot be loaded, the picker shows why (“Could not list projects: …”).

Note

Listing projects requires the resourcemanager.projects.list permission on some resource the credential can see. A service account without it authenticates but shows an empty picker. In that case, set the project prop or type the project ID on the Service Account Key tab.

Credential detection

By default GoogleAuth checks for credentials that already exist on the machine, then asks the user to confirm them. Detection is read-only. Nothing is written to the session, and no outputs are published, until the user clicks Use These Credentials.

The confirmation card shows the project, the principal, the credential type, the quota project when known, and where the credential came from (the environment variable name, the credentials file path, or the gcloud configuration name).

Note

GitAuth uses detected credentials without asking. GoogleAuth always asks for confirmation, so the user sees which project they are about to operate in.

Credential sources

detectCredentials accepts an array of sources, tried in the order written until one succeeds:

Source	Reads
'env'	Environment variables (see below)
{ env: { prefix: 'PREFIX_' } }	The same variables with a prefix, e.g. PREFIX_GOOGLE_APPLICATION_CREDENTIALS
'adc'	The well-known application_default_credentials.json under the gcloud configuration directory
'gcloud'	The active gcloud configuration: its account, project, and compute defaults, with that same credentials file
{ block: 'block-id' }	Credentials published by an earlier Command block. Only one block source is allowed per GoogleAuth block

The 'env' source reads, in precedence order:

Purpose	Variables
Credential	GOOGLE_APPLICATION_CREDENTIALS (a path), then GOOGLE_CREDENTIALS (inline JSON), then GOOGLE_OAUTH_ACCESS_TOKEN, then CLOUDSDK_AUTH_ACCESS_TOKEN
Project	CLOUDSDK_CORE_PROJECT, GOOGLE_CLOUD_PROJECT, GOOGLE_PROJECT, GCLOUD_PROJECT
Region	CLOUDSDK_COMPUTE_REGION, GOOGLE_CLOUD_REGION
Zone	CLOUDSDK_COMPUTE_ZONE

A project ID on its own is not a credential. Detection reports a find only when one of the credential variables is set. A credentials file may hold either a service account key or user credentials. The file’s type field decides which.

Default behavior

With no configuration, GoogleAuth checks environment variables and then Application Default Credentials:

{/* Same as detectCredentials={['env', 'adc']} */}
<GoogleAuth id="google-auth" />

Disable auto-detection

Force manual authentication only:

<GoogleAuth
  id="google-auth"
  detectCredentials={false}
/>

Include the active gcloud configuration

<GoogleAuth
  id="google-auth"
  detectCredentials={['env', 'gcloud', 'adc']}
/>

Custom detection with a prefix

Check the standard variables with a custom prefix. The example below looks for PROD_GOOGLE_APPLICATION_CREDENTIALS, PROD_GOOGLE_CREDENTIALS, PROD_CLOUDSDK_CORE_PROJECT, and so on:

<GoogleAuth
  id="prod-auth"
  detectCredentials={[{ env: { prefix: 'PROD_' } }]}
/>

Prefixes must follow these rules:

• Uppercase letters, numbers, and underscores only
• Must start with a letter
• Must end with a trailing underscore (e.g. PROD_, MY_APP_)

An invalid prefix is rejected and reported inline. The block does not fall back to the unprefixed variables.

Test prefix

To use a different prefix for automated tests, set env_prefix on the test step in runbook_test.yml:

runbook_test.yml

version: 1
tests:
  - name: happy-path
    steps:
      - block: google-auth
        env_prefix: CI_  # Checks CI_GOOGLE_APPLICATION_CREDENTIALS, CI_GOOGLE_CLOUD_PROJECT, etc.
        expect: success

Unlike the block, the test runner falls back to the unprefixed variables when it finds no prefixed credential. See Testing GoogleAuth blocks.

From Command output

Use credentials produced by a previous Command block, for example a script that impersonates a service account or exchanges a workload identity token:

<Command
  id="impersonate-sa"
  path="scripts/impersonate-sa.sh"
  title="Impersonate Deployment Service Account"
/>

<GoogleAuth
  id="impersonated-auth"
  title="Deployment Service Account"
  detectCredentials={[{ block: 'impersonate-sa' }]}
/>

<Command
  id="deploy"
  command="gcloud run deploy api --source ."
  googleAuthId="impersonated-auth"
/>

The script writes credentials to the runbook output file:

#!/usr/bin/env bash
set -euo pipefail

gcloud iam service-accounts keys create /tmp/deploy-key.json \
  --iam-account "deployer@my-project-123456.iam.gserviceaccount.com"

echo "GOOGLE_APPLICATION_CREDENTIALS=/tmp/deploy-key.json" >> "$RUNBOOK_OUTPUT"
echo "GOOGLE_CLOUD_PROJECT=my-project-123456" >> "$RUNBOOK_OUTPUT"

Accepted output keys are GOOGLE_APPLICATION_CREDENTIALS (a path), GOOGLE_CREDENTIALS (inline JSON), or GOOGLE_OAUTH_ACCESS_TOKEN / CLOUDSDK_AUTH_ACCESS_TOKEN. The project is the project prop when it is set. Otherwise it is the first of CLOUDSDK_CORE_PROJECT, GOOGLE_CLOUD_PROJECT and GOOGLE_PROJECT that the outputs set.

When a script writes the credential itself, rather than a path to it, mark it sensitive, as in echo "sensitive:GOOGLE_OAUTH_ACCESS_TOKEN=$TOKEN" >> "$RUNBOOK_OUTPUT". The Command’s View Outputs then masks it, and GoogleAuth still reads it by its plain name. See Sensitive outputs.

If the referenced block has not run yet, GoogleAuth shows Waiting for impersonate-sa to run…, with a link to that block, and pauses detection there. It does not skip to a later source.

Caution

Only one { block: 'id' } entry is allowed per GoogleAuth block. More than one is a configuration error, and the block renders an error card in place of the authentication UI.

Access token credentials

If the only credential found is an access token (GOOGLE_OAUTH_ACCESS_TOKEN or CLOUDSDK_AUTH_ACCESS_TOKEN), confirming it re-exports that same value under both canonical names and writes no GOOGLE_APPLICATION_CREDENTIALS. Runbooks does not mint a bearer token of its own, because access tokens expire after about an hour, which would break a long runbook halfway through.

Google says when an access token expires. Five minutes before then, the block turns red, says when it expires, and offers Sign in again. Once it has expired, the block says so. It stays signed in until you sign in again. The other credential types renew their own tokens, so the block never warns about them.

With no credentials file, GoogleAuth cannot bridge to the gcloud CLI. CLOUDSDK_AUTH_CREDENTIAL_FILE_OVERRIDE is left unset, and a bare gcloud command uses whatever CLI login is already configured on the machine. Client libraries, OpenTofu/Terraform, and any script that reads GOOGLE_OAUTH_ACCESS_TOKEN directly are unaffected.

When users reject detected credentials

Detected credentials are not registered as this block’s credentials until the user confirms them. When a user clicks Use Different Credentials:

1. The manual authentication tabs are shown
2. The user must authenticate manually before the block reports success, publishes outputs, or satisfies a googleAuthId dependency

A line above the sign-in tabs says what the user can do, followed by a Check again button that re-runs detection. It reads No existing credentials found when detection found nothing, asks the user to fix the credentials when the ones it found didn’t validate, and says to sign in with different credentials after the user turned detected credentials down or clicked Re-authenticate. With detectCredentials={false} the line and the button are hidden.

If a credential is found but does not validate, the block shows “Invalid credentials detected: Application Default Credentials are invalid or expired”, followed by the underlying reason in parentheses (for example, a file that does not exist), and falls through to manual authentication.

Instruction mode

In instruction mode, GoogleAuth captures nothing. It renders a single instruction, “Log into Google Cloud”, or “Log into Google Cloud in the my-project-123456 project” when project is set. The configured project, region, gcloud configuration, and scopes are listed as notes, along with the equivalent command to run by hand. The command reads the Desktop OAuth client from GOOGLE_OAUTH_CLIENT_CREDENTIALS, so the user sets that variable to the path of a Desktop-app client JSON first. See Using your own OAuth client. When the author sets scopes, the command includes --scopes=...:

gcloud auth application-default login --client-id-file="$GOOGLE_OAUTH_CLIENT_CREDENTIALS" --scopes=https://www.googleapis.com/auth/cloud-platform,https://www.googleapis.com/auth/userinfo.email,openid

No detection runs, no browser opens, and no credentials are read or written.

Security

Credential handling

• Credentials stay local. All authentication happens between your machine and Google. Nothing is transmitted to Gruntwork.
• Key material never reaches the UI. Service account keys, refresh tokens, and access tokens are handled entirely in the app’s main process. Every result the interface receives is metadata: a principal, a project, a credential type, and a file path.
• Credentials are files. GOOGLE_APPLICATION_CREDENTIALS points at either a file you already had, or a 0600 file in a private temporary directory. Those temporary files are deleted when Runbooks quits, and re-authenticating a block replaces that block’s previous file. Files are tracked per block, so one GoogleAuth block never releases a file another block is still publishing.
• Validation before use. Every credential is exchanged for a real access token before it is registered, so an expired or revoked credential fails at authentication.
• Federated credentials are checked before they are used. A service account key and a user credential are inert data, but an external_account or impersonated_service_account document names the endpoints Google’s auth library must call and the local file it must read. Runbooks rejects any such document that points anywhere other than *.googleapis.com over HTTPS, and rejects credential_source entirely, so a credentials file from an untrusted source cannot make the block send a request or read a file on someone else’s behalf. Workforce pool sign-in (gcloud auth application-default login) and impersonation chains are unaffected. File-, URL-, and executable-sourced workload identity federation is not accepted.
• Errors are redacted. Error messages that could echo key material are scrubbed before they are displayed.

Confirmation, and what it does not do

Confirmation controls what this block registers and publishes. No session variables are written and no outputs are produced until the user confirms.

Caution

It does not remove Google Cloud variables that your shell already exported. If you launch Runbooks from a terminal where GOOGLE_APPLICATION_CREDENTIALS is set, scripts inherit that value like any other environment variable, whether or not you confirm anything. To guarantee a command runs with the credentials a specific block produced, reference it with googleAuthId.

Within a Runbooks session, GoogleAuth updates CLOUDSDK_AUTH_CREDENTIAL_FILE_OVERRIDE every time it authenticates, including when it switches between a file-backed credential and an access token, so re-authenticating leaves no value from an earlier credential the block set. The same caveat applies to this variable. A value already present in the shell Runbooks was launched from stays in the session until a GoogleAuth block in this runbook authenticates and overwrites or clears it.

Federated credential limits

external_account, external_account_authorized_user and impersonated_service_account documents are instructions. The document names the URL the auth library must call, the headers it must send, and, through credential_source, the local file it must read or the program it must run. The library performs no validation of its own, so Runbooks validates them before they are used:

• Every absolute URL anywhere in the document must be https: and must resolve to a host under googleapis.com (accounts.google.com is also permitted, since every issued service account key carries it as auth_uri).
• universe_domain must be googleapis.com, at every level of a source_credentials chain.
• credential_source is rejected outright.

Workload identity federation that sources its subject token from a file, a URL, or an executable will not authenticate here. Accepting it would let a pasted document read an arbitrary local file and send it to a host of its choosing. Workforce-pool sign-in (gcloud auth application-default login against a workforce pool) has a refresh token and no credential_source, so it works, as does an impersonation chain over a service account key.

If a federated configuration you rely on is refused, authenticate with a service account key or gcloud auth application-default login instead.

Troubleshooting

Symptom	Cause and fix
Google Sign-In tab labeled (needs OAuth client)	No OAuth client is configured yet (build default, author props/file, or GOOGLE_OAUTH_CLIENT_* env). Choose a Desktop client JSON in the panel, set env, or use the Service Account Key / gcloud Config tab
“oauthClientId was supplied without oauthClientSecret”	A custom Desktop client needs both. Google issues a secret with every Desktop client; without it the credential cannot be refreshed
“Supply either oauthClientId/oauthClientSecret or oauthClientFile”	Those props are mutually exclusive. Pick one
“OAuth client credentials file is a Web client”	Download a Desktop app client JSON from Google Cloud Console (installed), not a Web client (web)
No gcloud configurations found	There is no gcloud configuration directory at the reported path. Run gcloud init, or set CLOUDSDK_CONFIG to the directory you use
A configuration shows No ADC and cannot be selected	The configuration has no Application Default Credentials. Run gcloud auth application-default login
Not a service account key (expected type: service_account)	The JSON has no type field, as in an OAuth client file, or it is a service account key that is missing a field such as private_key. Use the file that Google Cloud produced from IAM & Admin > Service Accounts > Keys
…which Runbooks does not accept / …is not a Google API endpoint	The credentials document is a workload identity federation config that fetches its subject token from a file, a URL, or a command, or that points at a host outside *.googleapis.com. Runbooks does not run those instructions. Use a service account key, Google Sign-In, or gcloud auth application-default login
Invalid credentials detected: … are invalid or expired (…)	The detected credential does not authenticate; the text in parentheses says why. For a missing or unreadable file, fix the path the variable points at. For an expired or revoked credential, refresh it (gcloud auth application-default login). Or authenticate manually
Credentials missing required scopes	The block’s scopes prop lists scopes the detected user ADC does not grant (for example Admin SDK scopes). Use Sign in with required scopes, or run the shown gcloud auth application-default login --client-id-file="$GOOGLE_OAUTH_CLIENT_CREDENTIALS" --scopes=... command and click Check again
gcloud Config / confirm fails with missing required OAuth scopes	Same check as detection: the selected ADC is too narrow for this block. Re-authenticate with the required scopes via Sign-In or gcloud auth application-default login --client-id-file=... --scopes=...
The project picker is empty	The credential cannot list projects. Grant resourcemanager.projects.list, or set the project prop / type the project ID directly
Could not list projects: …	Google refused or failed the project listing (for example, the Cloud Resource Manager API is disabled). The current authentication is untouched: Cancel returns to the success card. Fix the cause shown, or set the project prop
Project … is not accessible with these credentials	Advisory warning: the credential authenticated, but Google definitively refused (404/permission denied) on that project. Check the project ID and the principal’s IAM roles. An inconclusive answer, such as a disabled Cloud Resource Manager API or a network error, produces no warning, because it says nothing about whether your commands will work
Authenticated, but no Google Cloud project is set	The credential is valid but nothing named a project: no project prop, no core/project in the gcloud configuration, and no project the principal can enumerate. Commands that need one will fail with “The project property must be set”, unless an earlier GoogleAuth block set a project: then they use that block’s project, even with googleAuthId (see Multiple projects). Set the project prop, run gcloud config set project, or use Change project
Authenticated, but the credential could not be saved to the session	The credential is valid but the session write failed. Re-run the block; blocks that consume it may not see the credentials until you do
A Command’s Run button stays disabled	It has a googleAuthId pointing at a GoogleAuth block that has not authenticated yet, or at an ID that does not exist. Check the spelling
Commands use the wrong project	The session’s project variables come from the GoogleAuth block that most recently authenticated with a project or changed project. A block that authenticated with none leaves the previous block’s project in place, and a googleAuthId command that references it gets that project too, because a blank project is not injected. Add googleAuthId to every command that must use a specific block, and make sure that block has a project: set its project prop or use Change project
gcloud commands ignore the selected project	Some scripts pass --project explicitly. Runbooks sets CLOUDSDK_CORE_PROJECT, which only applies when the flag is absent
Bare gcloud commands fail with “UNAUTHENTICATED” or use the wrong account	The machine has a pre-existing gcloud auth login session that the CLI prefers over ADC. GoogleAuth sets CLOUDSDK_AUTH_CREDENTIAL_FILE_OVERRIDE to prevent this. See Bridging to the gcloud CLI. This can still happen for an access-token-only credential, which has no file to bridge with

Detailed example

See the google-auth feature demo for a complete walkthrough of the GoogleAuth block.