GCP KeyJSON: The Complete Guide to Service Account Credentials (2025)

Industry review — a comprehensive analysis of Google Cloud Platform's service account key format, including security implications, best practices, and when to use (or avoid) them.

Key Takeaways

• GCP KeyJSON is the default file format for service account private keys in Google Cloud Platform — a JSON document containing a cryptographic private key used for programmatic authentication.
• KeyJSON files grant full access to the IAM permissions assigned to the service account. Anyone who obtains the file can impersonate that service account within the key's validity period.
• The 2025 GCP security update introduced mandatory key rotation and reduced default key lifetime to 1 year, significantly limiting the blast radius of leaked keys.
• For human-driven workflows, workload identity federation and Compute Engine metadata server authentication are preferred over raw KeyJSON files.
• Never commit KeyJSON files to source control. Use secret managers (Google Secret Manager, HashiCorp Vault) and environment-variable injection.

What Is GCP KeyJSON?

Definition and Structure

A GCP KeyJSON file (commonly called a service-account-key.json) is a machine-readable credential bundle exported from Google Cloud Platform's IAM service. It is the most widely used method for authenticating non-interactive workloads — CI/CD pipelines, automation scripts, background services, and third-party tooling.

The file follows a fixed schema:

How KeyJSON Authentication Works

When your application loads a KeyJSON file, the Google auth libraries (e.g., google-auth-library) perform the following flow:

1. Extract the private_key and client_email.
2. Construct a signed JWT (JSON Web Token) using HS256 or RS256, scoped to the requested OAuth audience.
3. Exchange the JWT for an access token at token_uri.
4. Attach the bearer token to subsequent API calls.

This is a non-interactive, server-to-server auth flow. No browser, no MFA prompt — purely cryptographic proof of identity.

Advantages of GCP KeyJSON

1. Universal Compatibility

KeyJSON is the default credential format across the entire GCP ecosystem. Any SDK, CLI tool, or Terraform provider accepts it without configuration. This universality is its greatest strength and the reason millions of engineers reach for it first.

2. Offline-First Operation

Unlike workload identity (which requires network access to the metadata server), KeyJSON enables fully offline authentication. Deployments in air-gapped environments, local development VMs, and on-premises systems all benefit from portable credentials.

3. Fine-Grained IAM Control

Each KeyJSON file maps to exactly one service account. By attaching minimal IAM roles (following least-privilege), you can restrict what the key can do. A storage viewer key cannot write to BigQuery; a Compute Engine key cannot manage IAM policies.

4. No Infrastructure Dependency

Workload identity federation requires a configured Workload Identity Pool, Trust Blueprint, and external provider. KeyJSON works anywhere — inside a Docker container, on a developer's laptop, or in a GitHub Actions runner.

5. Auditable and Revocable

Every KeyJSON has a unique private_key_id. You can rotate or delete individual keys without affecting other service accounts or credentials. The IAM audit logs record every key creation, rotation, and deletion event.

Drawbacks and Security Risks

1. Single Point of Failure

A leaked KeyJSON grants the attacker unrestricted access equivalent to the service account's IAM roles. Unlike short-lived tokens, a KeyJSON never expires until manually revoked (or until the 1-year default limit). This makes it a high-value target for attackers.

2. Temptation Toward Over-Provisioning

Engineers often export a KeyJSON from a owner or editor service account because it "just works." The resulting blast radius is catastrophic if leaked. Real-world incidents frequently involve a single leaked service account key leading to full project compromise.

3. Human Error in Distribution

KeyJSON files are routinely:

• Committed to GitHub repositories (even private ones)
• Shared over Slack, email, or unencrypted channels
• Stored in plaintext configuration files on shared drives
• Hardcoded into application source code

Security scanning tools detect millions of leaked GCP service account keys on public GitHub every year.

4. No Built-In Consent or MFA

KeyJSON authentication is purely cryptographic. There is no prompt for user consent, no MFA challenge, and no contextual risk assessment. If the key is stolen, the attacker faces zero friction.

5. Manual Rotation Burden

Before 2025, exported KeyJSON keys had no expiration. Engineers could (and did) use the same key for years without rotation. The current 1-year default mitigates this but adds operational overhead for teams managing hundreds of service accounts.

GCP KeyJSON vs. Alternatives: Comparison Table