Google Cloud Authentication Architecture

While the Google Cloud Setup Guide covers the step-by-step instructions for extracting your API credentials, this document outlines the architectural decisions, pitfalls, and lessons learned when authenticating from CyberChef's client-side environment to Google Cloud APIs.

The CyberChef Context

CyberChef operates entirely within the browser. There is no middle-tier backend server acting as a proxy. This means that any REST request to a Cloud API originates directly from the user's browser via fetch() from a Web Worker.

This architecture has three major implications for authentication:

1. Browser-Side Secret Exposure

Any secret embedded in a CyberChef recipe URL or baked into an operation is visible to the browser, the network layer, and anyone who receives the recipe link.

API Keys: An API Key is a static secret. If you use one, you must apply HTTP Referrer restrictions in the Google Cloud Console (as detailed in the Setup Guide) to ensure it can only be used from your specific CyberChef domain (e.g., http://localhost:8080/).
OAuth Tokens: A temporary OAuth Token (from gcloud auth print-access-token) is generally preferred because it automatically expires (usually in 1 hour), mitigating the risk of credential leakage.

2. The Application Default Credentials (ADC) Quota Project Pitfall

When you use a short-lived OAuth token generated by an End User account (e.g., via gcloud auth login), the token identifies you, but Google occasionally needs to know which project to bill for the specific API usage.

If you attempt to call certain APIs (like translate.googleapis.com) using an End User OAuth Token, Google Cloud will throw a 403 error:

"Your application is authenticating by using local Application Default Credentials. The translate.googleapis.com API requires a quota project, which is not set by default."

The Solution:

CyberChef cloud operations that accept an OAuth Token must implement an optional Quota Project input argument. Under the hood, this argument must be injected into the fetch() request as the x-goog-user-project HTTP header:

headers.set("Authorization", `Bearer ${authString}`);
if (quotaProject) {
    headers.set("x-goog-user-project", quotaProject); // Injects the billing bound project
}

Note: You configure your local gcloud environment's default quota project using gcloud auth application-default set-quota-project <YOUR_PROJECT_ID>.

3. UI Argument Masking (The `toggleString` Pitfall)

To prevent your API Key or Token from being displayed in plain text within CyberChef's UI, Cloud operations should use the toggleString data type for the authentication argument. This renders the input cleanly and masks the text.

The Pitfall:

When converting a CyberChef argument from a standard string to a toggleString, the underlying payload structure changes. The Web Worker will no longer receive a raw string; it will receive an object:

// A normal string returns: "AIzaSy..."
// A toggleString returns: { "string": "AIzaSy...", "option": "UTF8" }

If an operation's run() function expects a string and does not explicitly unpack authStringObj.string, the network request will silently fail, or the Web Worker will hang when attempting to serialize the object into an HTTP Header.

Always ensure the runtime safely parses masked keys:

const authString = typeof authStringObj === "string" ? authStringObj : (authStringObj.string || "");

Supported Methods Comparison

Authentication Method	Security Profile	Setup Complexity	Best For
API Key (Restricted)	Moderate (Long-lived secret, but restricted by referrer)	Low	Permanent embedded recipes, public web hosting, and sharing recipes internally.
OAuth Bearer Token	High (Expires in 1 hr)	Medium (Requires `gcloud` CLI)	Local development, automated E2E testing, and one-off secure executions.

4.0 KiB Raw Blame History