Fix GCP Authentication Errors: ADC, Service Accounts, Cloud Run, GKE, and CI/CD

Simple explanation

Think of authentication like showing your passport at the airport. If the passport is expired or you left it at home, you cannot board. That is an authentication error: GCP cannot verify who is making the request. Credentials are missing, expired, or misconfigured, and no API call can succeed until this is fixed.

Authorisation is what happens next: the airline checks whether you have a valid ticket for that specific flight. A permission error (403) means GCP knows who you are but IAM says you are not allowed to do what you asked. If you are seeing 403 errors, authentication is already working and you need to fix permissions instead.

“Credentials” in GCP means proof of identity. That proof can come from a user login, a service account key file, a short-lived token from the metadata server, or a federated identity token from an external provider. Your code does not always know which one it is using, and that is often the root cause of the error.

Quick diagnosis: start here

Find the environment where your code runs. The recommended authentication method, the most common failure, and the first thing to check are different for each one.

Authentication vs authorisation

The HTTP status code tells you which problem you have:

Always fix authentication first. A 403 that appears after fixing a 401 is expected and has a completely different fix.

How GCP authentication works

GCP supports several credential types. Understanding which one your code is using is the fastest way to diagnose an authentication error.

• User credentials. Your Google account, obtained through gcloud auth login. Used by gcloud and the Console. Not used by application code unless you explicitly set up ADC with gcloud auth application-default login.

• Application Default Credentials (ADC). The automatic discovery mechanism that GCP client libraries use. ADC checks three places in order: (1) the GOOGLE_APPLICATION_CREDENTIALS environment variable, (2) the gcloud ADC file at ~/.config/gcloud/application_default_credentials.json, (3) the metadata server. It stops at the first one that exists.

• Attached service account / metadata server. On Compute Engine, Cloud Run, Cloud Functions, and GKE (without Workload Identity), the metadata server at 169.254.169.254 issues short-lived tokens for the service account attached to the resource. No key file needed.

• Workload Identity (GKE). Maps a Kubernetes service account to a GCP service account. Pods get tokens from the metadata server as if they were the GCP service account.

• Workload Identity Federation. Lets external identities (GitHub Actions, AWS, Azure, on-prem OIDC) exchange their native token for a short-lived GCP access token. No key file needed.

• Service account impersonation. Lets an authenticated identity generate short-lived credentials as a different service account. Useful for local development and admin tasks.

• Service account keys. Long-lived JSON key files. These are the legacy pattern. They work everywhere but create significant security risk. Avoid them unless no alternative exists.

Most common GCP authentication errors and what they usually mean

”Could not load the default credentials”

ADC found nothing at any of its three lookup steps. On a local machine, run gcloud auth application-default login. On a GCP service, check whether GOOGLE_APPLICATION_CREDENTIALS is set to a path that does not exist in the runtime environment.

”Credentials not found” or “unable to detect credentials”

Same root cause as above. The client library tried all ADC steps and none returned usable credentials. Check the environment variable, the ADC file, and (on GCP) the metadata server.

”Invalid token” or “token expired”

The credential exists but the token it produced is not valid. On a local machine, re-run gcloud auth application-default login. If using a service account key, confirm the key has not been deleted from the GCP Console. Client libraries refresh tokens automatically, so if you see this in application code, the underlying credential is likely broken.

”Error creating credential from JSON” or “wrong credential file type”

GOOGLE_APPLICATION_CREDENTIALS points to the wrong kind of JSON file. The most common mistake is pointing it to a gcloud user-credential file instead of a service account key file. The user-credential file lives at ~/.config/gcloud/application_default_credentials.json and has a “type”: “authorized_user” field. A service account key file has “type”: “service_account”. Make sure the variable points to the correct file.

gcloud works but application code fails

gcloud and your application use different credentials. gcloud uses the login from gcloud auth login. Your app uses ADC. If you have not run gcloud auth application-default login, ADC has no credentials even though gcloud does. Run it, or check whether GOOGLE_APPLICATION_CREDENTIALS is pointing somewhere unexpected.

# Verify gcloud credentials (used by gcloud CLI)
gcloud auth list

# Verify ADC credentials (used by your application code)
gcloud auth application-default print-access-token

ADC problems

Application Default Credentials is the most common source of authentication errors because developers do not always know which step of the lookup chain their code is hitting.

The ADC lookup order

1. Step 1: GOOGLE_APPLICATION_CREDENTIALS environment variable → reads the file at that path
2. Step 2: gcloud ADC file at ~/.config/gcloud/application_default_credentials.json
3. Step 3: metadata server (only available on GCP infrastructure)

The lookup stops at the first step that matches. If step 1 is set but the file is missing, ADC fails immediately. It does not fall through to step 2 or 3.

If ADC is not working

• Check whether GOOGLE_APPLICATION_CREDENTIALS is set: echo $GOOGLE_APPLICATION_CREDENTIALS
• If it is set, confirm the file exists at that path and contains valid JSON
• If it is not set, check whether the gcloud ADC file exists: ls ~/.config/gcloud/application_default_credentials.json
• If neither exists and you are on GCP, verify the metadata server is reachable

# Set up ADC for local development
gcloud auth application-default login

# Confirm ADC is working
gcloud auth application-default print-access-token

# Check the environment variable
echo $GOOGLE_APPLICATION_CREDENTIALS

# Unset it if it is causing problems
unset GOOGLE_APPLICATION_CREDENTIALS

Service account key file problems

If your application authenticates with a service account key file, these are the most common failure modes:

• File not found: GOOGLE_APPLICATION_CREDENTIALS points to a path that does not exist in the current environment (common when deploying to a container that does not include the key file)
• Invalid JSON: the file is corrupted, truncated, or is not a service account key file at all
• Key deleted server-side: the key was deleted in the GCP Console, but the local file still exists. The file looks valid but the key ID no longer works.
• Service account disabled or deleted: the service account that owns the key no longer exists or has been disabled
• Wrong JSON file type: the file is a user-credential JSON (“type”: “authorized_user”) instead of a service account key (“type”: “service_account”)

# List active keys for a service account
gcloud iam service-accounts keys list \
  --iam-account=my-sa@my-project.iam.gserviceaccount.com

# Check if the service account is disabled
gcloud iam service-accounts describe \
  my-sa@my-project.iam.gserviceaccount.com \
  --format="value(disabled)"

# Re-enable a disabled service account
gcloud iam service-accounts enable \
  my-sa@my-project.iam.gserviceaccount.com

Metadata server issues on Google Cloud

On Compute Engine, Cloud Run, Cloud Functions, and GKE, the metadata server at 169.254.169.254 provides credentials automatically. GCP client libraries use it as step 3 of the ADC lookup. When it works, you do not need any key files or environment variables.

Why setting GOOGLE_APPLICATION_CREDENTIALS on managed runtimes causes failures

Think of the metadata server as a concierge desk built into every GCP building. If you are inside the building, just walk up and ask for credentials. But if you tape a sign on the front door saying “go to a different address,” you will never reach the concierge.

If the metadata server is not responding

• Confirm you are running on GCP infrastructure (the metadata server is not available on local machines or external clouds)
• Check that the service account attached to the resource is not disabled or deleted
• On Compute Engine, verify the instance was created with a service account (the default service account may have been removed)

# Test metadata server access from a VM or container
curl -s -H "Metadata-Flavor: Google" \
  "http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/email"

# Get a token from the metadata server directly
curl -s -H "Metadata-Flavor: Google" \
  "http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/token"

GKE Workload Identity authentication failures

Workload Identity lets GKE pods authenticate as a GCP service account without key files. It requires configuration on both sides: the Kubernetes service account and the GCP service account. Missing either side causes authentication to fail silently.

Step-by-step diagnosis

1. Is Workload Identity enabled on the cluster?

gcloud container clusters describe CLUSTER_NAME \
  --zone=ZONE \
  --format="value(workloadIdentityConfig.workloadPool)"
# Must return PROJECT_ID.svc.id.goog

2. Does the Kubernetes service account have the annotation?

kubectl describe serviceaccount KSA_NAME -n NAMESPACE
# Look for: iam.gke.io/gcp-service-account: GSA_EMAIL

3. Does the GCP service account have the IAM binding?

gcloud iam service-accounts get-iam-policy GSA_EMAIL --format="yaml"
# Must include:
#   members:
#     - serviceAccount:PROJECT_ID.svc.id.goog[NAMESPACE/KSA_NAME]
#   role: roles/iam.workloadIdentityUser

4. Is the pod actually using the correct Kubernetes service account?

kubectl get pod POD_NAME -n NAMESPACE -o jsonpath='{.spec.serviceAccountName}'

External workloads and CI/CD authentication

Workloads running outside of GCP (GitHub Actions, Terraform Cloud, Jenkins, GitLab CI, or applications on AWS and Azure) need to authenticate to GCP without a metadata server. The recommended approach is Workload Identity Federation, which exchanges the runner’s native identity token for a short-lived GCP access token.

GitHub Actions

Use the google-github-actions/auth action with workload_identity_provider instead of a service account key. This eliminates the need to store a key as a GitHub secret.

# .github/workflows/deploy.yml (simplified)
- id: auth
  uses: google-github-actions/auth@v2
  with:
    workload_identity_provider: projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL/providers/PROVIDER
    service_account: deploy-sa@PROJECT_ID.iam.gserviceaccount.com

Common failures: wrong workload_identity_provider value, missing attribute mapping in the provider configuration, or the service account not granting roles/iam.workloadIdentityUser to the federated principal.

Terraform

Terraform can authenticate through Workload Identity Federation, a service account key file, or ADC. For CI/CD pipelines, federation is preferred. For local runs, use ADC with service account impersonation so you test with the same permissions as your deployment service account.

# Terraform provider with impersonation (local development)
provider "google" {
  project = "my-project"
  region  = "us-central1"
  impersonate_service_account = "terraform-sa@my-project.iam.gserviceaccount.com"
}

Workloads on AWS or Azure

Use Workload Identity Federation with the cloud provider’s identity system as the OIDC or SAML provider. For example, an AWS Lambda function can exchange its IAM role credentials for a GCP token through a configured federation pool. No GCP key file needs to exist on the external cloud.

When to use service account impersonation instead

Service account impersonation is the better pattern for local development, admin tasks, and testing. It lets your user account generate short-lived credentials as a service account without downloading a key file. It also creates a clear audit trail in Cloud Audit Logs showing who impersonated which service account and when.

When to use each authentication method

• Local development: ADC with user credentials (gcloud auth application-default login), or service account impersonation for production-like permissions
• Google Cloud runtime (Compute Engine, Cloud Run, Cloud Functions): attached service account via the metadata server. Do not set GOOGLE_APPLICATION_CREDENTIALS.
• GKE: Workload Identity. Map Kubernetes service accounts to GCP service accounts.
• External CI/CD (GitHub Actions, GitLab, Jenkins): Workload Identity Federation
• External cloud (AWS, Azure): Workload Identity Federation with the native identity provider
• Admin and testing: service account impersonation
• Service account keys: avoid unless there is a strong technical reason and no alternative exists. Understand the risks first.

ADC vs attached service account vs Workload Identity Federation vs service account keys

Verifying credentials in code

# Python: check which credentials ADC resolves to
import google.auth
import google.auth.transport.requests

credentials, project = google.auth.default()
print(f"Credential type: {type(credentials).__name__}")
print(f"Project: {project}")

# Request a fresh token to verify the credentials work
request = google.auth.transport.requests.Request()
credentials.refresh(request)
print(f"Token obtained: {credentials.token[:20]}...")

# Verify credentials work with a curl test (any language)
TOKEN=$(gcloud auth print-access-token)
curl -s -o /dev/null -w "%{http_code}" \
  -H "Authorization: Bearer $TOKEN" \
  "https://cloudresourcemanager.googleapis.com/v1/projects/PROJECT_ID"
# 200 = auth works; 401 = credentials invalid; 403 = auth works but IAM blocks