credentialsjson
```html
credentialsjson: The Ultimate Playbook for Managing Service Account Credentials Securely
A practical, checklist-driven guide to understanding, generating, securing, and rotating credentials.json files across Google Cloud, OAuth2 flows, and CI/CD pipelines.
Key Takeaways
- credentials.json is a service account key file — typically a JSON document issued by Google Cloud IAM that contains a private key, client ID, and token URI for programmatic authentication.
- Never commit credentials.json to source control; use environment variables, secret managers, or mount-only-injection patterns instead.
- Rotate service account keys at least every 90 days, and revoke unused keys immediately.
- Apply the principle of least privilege: scope every credentials.json file to the minimal IAM roles your workload actually needs.
- Use Workload Identity Federation in GCP (or equivalent OIDC-based patterns in AWS/Azure) to eliminate long-lived service account keys entirely.
What Is credentials.json?
A credentials.json file is a machine-readable JSON payload that grants programmatic access to cloud APIs. In the Google Cloud ecosystem, it is the standard output when you create a Service Account Key. The file typically contains the following fields:
Core Fields in a credentials.json File
| Field | Description | Example Value |
|---|---|---|
type |
Key type identifier | "service_account" |
project_id |
Google Cloud project owning the service account | "my-production-project" |
private_key_id |
Unique fingerprint of the private key | "a1b2c3d4e5f6..." |
private_key |
PKCS#1 private key (never share this) | "-----BEGIN RSA PRIVATE KEY-----..." |
client_email |
Email address of the service account | "svc-deploy@my-proj.iam.gserviceaccount.com" |
client_id |
Numeric client identifier | "112233445566778899" |
auth_uri |
OAuth2 authorization endpoint | "https://accounts.google.com/o/oauth2/auth" |
token_uri |
OAuth2 token issuance endpoint | "https://oauth2.googleapis.com/token" |
auth_provider_x509_cert_url |
Public key endpoint for JWT verification | "https://www.googleapis.com/oauth2/v1/certs" |
client_x509_cert_url |
Service account certificate URL | "https://www.googleapis.com/robot/v1/metadata/x509/..." |
Where You Will Encounter credentials.json
Understanding the delivery mechanism helps you design the right security controls around it.
Common Injection Points
- Google Cloud Functions / Cloud Run — set via
GOOGLE_APPLICATION_CREDENTIALSenvironment variable pointing to a mounted secret. - CI/CD Pipelines (GitHub Actions, GitLab CI, Cloud Build) — stored as repository or organization-level secrets, injected at runtime.
- Kubernetes Workloads — mounted as a Secret volume or injected via workload identity controllers.
- Local Development — placed in
~/.config/gcloud/or referenced via an explicit path during testing. - Third-Party OAuth2 Clients — uploaded manually in admin panels for tools that do not support native GCP auth flows.
Secure Creation Checklist
Follow this checklist every time you generate a new service account key pair. Skipping any step is a common root cause of credential leakage incidents.
Pre-Creation
- [ ] Define the minimal IAM roles required for the target workload (use Cloud IAM Conditionals where possible).
- [ ] Confirm whether Workload Identity Federation can replace the key entirely — prefer OIDC-based auth over static keys.
- [ ] Document the intended consumer (service name, team owner, retention period).
- [ ] Choose JSON key as the key type; avoid uploading PEM or other formats unless required.
- [ ] Set a key expiration date at creation time (recommended: 90 days for production).
Post-Creation
- [ ] Download the credentials.json file to a password-protected local store — never over unencrypted channels.
- [ ] Immediately revoke the console/browser session used to download it.
- [ ] Inject the credential into the target runtime via a secrets manager (Secret Manager, Vault, AWS SM, etc.) — never write it to disk unencrypted.
- [ ] Add the service account to your asset inventory with rotation due dates.
- [ ] Enable Cloud Audit Logs for the service account and set up alerting on unusual access patterns.
Secure Storage & Rotation
Static keys are a ticking clock. Rotation and storage discipline are your primary defenses.
Storage Options Comparison
| Method | Security Level | Best For | Weakness |
|---|---|---|---|
| Google Cloud Secret Manager | ★★★★★ | GCP-native workloads | Requires GCP project boundary |
| HashiCorp Vault | ★★★★★ | Multicloud / hybrid environments | Operational overhead to maintain |
| Kubernetes Secrets (encrypted at rest) | ★★★★☆ | K8s-first deployments | Etcd must be encrypted; RBAC critical |
Environment Variable ($GOOGLE_APPLICATION_CREDENTIALS) |
★★★☆☆ | Local dev / ephemeral containers | Visible to any process with env access |
| Files on shared storage (GCS, NFS) | ★☆☆☆☆ | Never recommended | Easy accidental exposure via ls, logs, backups |