Skip to main content
The Firebase provider lets your Archie backend accept the ID tokens that Firebase Authentication or Google Cloud Identity Platform issue to your users. Your app keeps signing users in with Firebase. Archie only checks the token. Archie validates every ID token locally. It checks the RS256 signature against Google’s public securetoken keys, then checks the project, issuer, expiry, and your restrictions. It’s the same ID token your app already sends to Google Cloud services, so you don’t need a second sign-in. To open it, navigate to App Services → Authentication Providers in the Backend Console and add a Firebase provider.

How requests work

Your app gets the ID token from the Firebase SDK and sends it on every request to your Archie backend. Archie reads the ID token only from the Authorization header, with the Bearer scheme. If the request has no Authorization header at all, Archie answers 401 with the message Missing required headers: x-project-id and/or authorization. That response has no extensions.code, because no token reached the provider.
Always ask the Firebase SDK for the token right before the request. ID tokens expire after one hour, and getIdToken() returns a fresh one when the current token is about to expire.

Before you start

Collect these values from Google.

Firebase Project ID

  1. Open the Firebase console and select your project.
  2. Click the gear icon, then Project settings.
  3. Copy the Project ID from the General tab.
The Project ID is not the project name and not the project number. It looks like my-app-1a2b3.

Identity Platform Tenant ID (only for multi-tenancy)

Skip this if you don’t use Identity Platform tenants.
  1. Open the Google Cloud console and select the same project.
  2. Navigate to Identity Platform → Tenants.
  3. Copy the Tenant ID of the tenant your users sign in to.

Issuer

You don’t enter the issuer. Archie derives it from the Project ID and shows it read-only:

Configure the provider

The form has four sections. Click Save when you’re done.

General

Restrictions

In this version, every token must carry an email address. Tokens without an email, such as phone sign-in and anonymous sign-in tokens, are rejected with token_policy_rejected, even when Allow Anonymous Users is on and Require Verified Email is off.

Revocation

By default, Archie accepts a valid token until it expires, even if you revoke the user’s sessions or disable the account in Firebase. Turn on revocation checks to close that gap. The key must be a JSON key of type service_account that belongs to the same project as the Firebase Project ID. After you save, the console shows the key masked. To keep the stored key when you edit the provider, leave the field empty. Check Revoked Tokens can’t be combined with Additional Project IDs. The service account can only check revocation in the main project, so a configuration with both is rejected when you save. If you need revocation checks, accept tokens from a single Firebase project. See Set up the service account for revocation.

Advanced

Claim fields take a simple, top-level claim name such as sub or roles: letters, digits, and underscores, up to 64 characters. Nested paths such as app.roles aren’t supported.
Roles from the token are only granted when runtime enforcement of token roles is enabled for your platform. That is a platform-side switch, off by default. Until it is enabled, the Roles Claim grants no role, even when the provider and Allowed Roles are configured correctly. Ask your Archie administrator whether it’s enabled in your environment before you rely on it.
The Roles Claim is off by default. Leave it off unless your backend controls the custom claims. Turning it on isn’t enough to grant roles: list the roles you want to accept in Allowed Roles. Roles still come from Role-Based Access.
Some operations aren’t available yet to credentials whose roles come from the token. CSV import (uploadCsv) is refused with 403 and the code CLAIMED_ROLES_OPERATION_UNSUPPORTED. Run imports with a credential whose roles are assigned in Archie. Archie checks Allowed Roles when you save the provider, and checks every role again on each request. A role that has since become administrative or privileged, been deactivated, or been deleted is no longer granted, even if it is still in Allowed Roles. If Archie can’t check the roles at that moment, the request is refused with 503 and a Retry-After header. It is never let through with unchecked roles.

Test a token before you save

Use Test token to check your configuration without saving it.
  1. Get a fresh ID token from your app, for example by logging the result of getIdToken() in a development build.
  2. Click Test token and paste the token.
  3. Read the result. If the token is rejected, compare the result with the error codes.
The test uses the values currently in the form, including unsaved changes. The token is never stored. You can run up to 10 tests per minute per project. Beyond that, the test is refused with the code rate_limited. Wait a minute and try again. rate_limited only comes from Test token; it is never the answer to a request from your app.

What Archie checks when you save

Besides validating each field, Archie runs these checks when you create a Firebase provider or save a change to its configuration (saving an unchanged configuration skips them):
  • Google’s signing keys. Archie downloads Google’s public securetoken keys. If the download fails, the provider is still saved and the console shows a warning.
  • The service account, with Check Revoked Tokens on. Archie asks Google to read the project’s users with the key. First Archie exchanges the key for an access token. If Google’s token endpoint rejects the key with any 4xx answer, including 429, the save is blocked: for example, the key was revoked or deleted. Any other failure of that exchange, such as a 5xx answer or Google being unreachable, saves the provider with a warning. Then Archie reads the project’s users. If that call answers 403, the save is blocked: the service account doesn’t have the Firebase Authentication Viewer role. A 429 or 5xx answer, or Google being unreachable, saves the provider with a warning. Any other answer that isn’t 200 blocks the save.
An ID token is a credential until it expires. Don’t paste real user tokens into tickets, chats, or logs.

Set up the service account for revocation

Archie needs a service account to ask Google about a user’s status. Give it the least access possible.
1

Create the service account

In the Google Cloud console, select the same project as your Firebase Project ID. Navigate to IAM & Admin → Service Accounts and click Create service account. Give it a name such as archie-token-revocation.
2

Grant the minimum role

Grant the role Firebase Authentication Viewer. Archie doesn’t need any other role.
3

Create a JSON key

Open the service account, go to the Keys tab, and click Add key → Create new key. Choose JSON and click Create. Your browser downloads the key file.
4

Paste the key into Archie

Turn on Check Revoked Tokens, paste the full content of the JSON file into Service Account Key, and click Save. Then delete the downloaded file from your computer.
The key file has this shape. Never commit a real key to source control.
If your organization blocks service account key creation, ask your Google Cloud administrator for an exception for this service account.

Rotate the key without downtime

  1. Create a new JSON key for the same service account.
  2. Paste the new key into Service Account Key and click Save.
  3. Check that requests still succeed.
  4. Delete the old key in the Google Cloud console.
The old key keeps working until you delete it, so requests never fail during the switch.

How long changes take

Archie caches some results to keep requests fast. These are the windows to plan for.
When you disable or edit the provider, Archie clears the cached results of that project. If that notification is lost, the cached results expire on their own within about 90 seconds.

Error codes

When Archie rejects a token, it answers HTTP 401 with this header and body:
Read extensions.code to find the cause. The message is always the same. When Check Revoked Tokens is on and Archie can’t reach Google, the request is refused, never accepted. The answer is 503 with a Retry-After header and the code AUTH_UNAVAILABLE, or 401 in some deployments. Retry after the indicated time.
token_policy_rejected doesn’t say which restriction failed, so attackers can’t probe your policy. To find the cause, review the Restrictions section one field at a time and use Test token after each change.

Not supported

  • Firebase custom tokens. Exchange them in your app with signInWithCustomToken() and send the resulting ID token.
  • Firebase session cookies.
  • App Check tokens.
  • The Firebase Auth Emulator in deployed environments. Emulator tokens aren’t signed by Google.

FAQ

No. Google Sign-In ID tokens are issued by Google accounts, not by your Firebase project, so they fail with token_invalid_issuer. Sign the user in to Firebase with the Google credential, then send the Firebase ID token.
No. Signatures are checked locally with Google’s public keys. Archie only calls Google for revocation status when Check Revoked Tokens is on, and it caches the answer for up to 5 minutes.
In this version, every token must include an email. Phone and anonymous sign-in tokens have none, so they’re rejected with token_policy_rejected.
Their tokens carry an Identity Platform tenant. If the provider has no Tenant ID, every token with a tenant is rejected; if it has one, only tokens from that tenant are accepted. Set Tenant ID to the tenant your users sign in to.
Yes. Add up to 10 other projects to Additional Project IDs. This can’t be combined with Check Revoked Tokens: revocation is only checked in the main project, so a configuration with both is rejected.
Yes. Authentication providers are scoped per environment and their secrets are never copied when you branch an environment. See Authentication Providers.