Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

[DOC] Improve documentation for service account impersonation

Open
#2,812 3 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
4/5
Estimated time
3-5 days
Newbie friendliness
35/100
Issue type
Documentation
Clarity
Mostly clear
Activity status
Stale
Tech stack
gcp, nodejs, typescript

Research direction

Start with the reported gcloud auth application-default login --impersonate-service-account flow and the application_default_credentials.json format, then compare it with the initializeApp, cert, and applicationDefault examples. Document a working local-development example for firebase-admin v13.0.1, including the required permission setup and what successful authentication looks like.

Written by the indexing model from the issue text.

Description

It seems like service account impersonation is the recommended way to authenticate for local development.

But it's not very clear how this is done in practice. Do I need to adapt my code for this?

I've run:
gcloud auth application-default login --impersonate-service-account SERVICE_ACCT_EMAIL
and I have a token in:
cat /Users/myuser/.config/gcloud/application_default_credentials.json

{
  "delegates": [],
  "service_account_impersonation_url": "https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/myserviceaccount@myproject.iam.gserviceaccount.com:generateAccessToken",
  "source_credentials": {
    "account": "",
    "client_id": "removed",
    "client_secret": "removed",
    "refresh_token": "removed",
    "type": "authorized_user",
    "universe_domain": "googleapis.com"
  },
  "type": "impersonated_service_account"
}

I have tried code like this (after having looked at #2800):

initializeApp({
    storageBucket: config.firebase.storageBucket,
    credential: cert(process.env['GOOGLE_APPLICATION_CREDENTIALS']),
    projectId: config.firebase.projectId,
  })

But then I got an error:

FirebaseAppError: Failed to parse service account json file: Error: Service account object must contain a string "project_id" property.

and this, I assumed this would pick up the ADC credentials file, notice its impersonation, and things would just work:

initializeApp({
    storageBucket: config.firebase.storageBucket,
    credential: applicationDefault(),
    projectId: config.firebase.projectId,
  })

But then I got this error:

"Getting metadata from plugin failed with error: Could not refresh access token: PERMISSION_DENIED: unable to impersonate: Permission 'iam.serviceAccounts.getAccessToken' denied on resource (or it may not exist).",

My local user has the Owner role in the GCP project. And has owner permissions on the service account. The service account has the Service Account Token Creator role.

Im using firebase-admin v13.0.1

Some working sample code for this would be very helpful.

Dominant language
TypeScript
Stars
1.7k
Forks
419
Avg merge
4d 20h
Merged PRs (30d)
16

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from firebase/firebase-admin-node

All issues in firebase/firebase-admin-node

Similar issues

More TypeScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.