Prerequisites
- A Firebase project with Authentication enabled
- At least one sign-in method configured in Firebase
- Access to the Char dashboard
Quick Links
Firebase Console
Open the Firebase Console
Firebase Auth Docs
Firebase Authentication documentation
ID Token Verification
Token verification guide
Web SDK Reference
Firebase Auth Web SDK
SDK References
Configuration Steps
1
Set Up Firebase Authentication
- Go to the Firebase Console
- Select your project (or create a new one)
- Navigate to Build → Authentication
- Click Get started if not already enabled
- Enable your desired sign-in methods (Email/Password, Google, etc.)
2
Note Your Project ID
From the Firebase Console:
- Click the gear icon → Project settings
- Find your Project ID in the General tab

Find your Project ID in Firebase settings
Your Project ID is used to construct the issuer URL. It’s different from the Web API Key.
3
Get Your Firebase Config
In Project settings → General:
- Scroll to Your apps
- If no web app exists, click Add app → Web
- Note the configuration values, especially
projectId
4
Configure Char
In the Char Dashboard:
- Navigate to Settings → Integration
- Under SSO Configuration, select Custom OIDC as the provider
- Enter your configuration:
| Field | Value |
|---|---|
| Client ID | Your Firebase Project ID |
| Issuer URL | https://securetoken.google.com/{project-id} |
- Click Test Connection to verify
- Click Save Changes
Configuration Reference
| Char Field | Firebase Value | Example |
|---|---|---|
| Provider Type | Custom OIDC | custom_oidc |
| Client ID | Firebase Project ID | my-app-12345 |
| Issuer URL | Secure Token issuer | https://securetoken.google.com/my-app-12345 |
Firebase ID tokens use
https://securetoken.google.com/{project-id} as the issuer, and the audience (aud) is your Project ID. This is different from Google OAuth tokens.Token Requirements
Char validates Firebase tokens with these requirements:| Claim | Requirement |
|---|---|
iss | Must be https://securetoken.google.com/{project-id} |
aud | Must be your Firebase Project ID |
sub | Required - Firebase user UID |
exp | Must not be expired |
auth_time | Must be in the past |
Standard Firebase ID Token Claims
| Claim | Description |
|---|---|
sub | Firebase user UID (unique identifier) |
email | User’s email address |
email_verified | Whether email is verified |
name | User’s display name |
picture | User’s photo URL |
firebase.sign_in_provider | Authentication provider used |
firebase.identities | Linked identity providers |
Example: Obtaining and Passing the Token
- Firebase Web SDK (v9+)
- React (Firebase + Context)
- Next.js (with firebase-admin)
- Firebase Web SDK (v8/compat)
Token Refresh
Firebase ID tokens expire after 1 hour. Handle token refresh:Custom Claims
Add custom claims using Firebase Admin SDK:Custom claims are included in the ID token. Changes take effect on the next token refresh (force refresh with
getIdToken(user, true)).Multiple Authentication Providers
Firebase supports linking multiple authentication providers:Troubleshooting
INVALID_ISSUER error
INVALID_ISSUER error
The issuer URL format is incorrect:
- Use the correct format:
https://securetoken.google.com/{project-id} - Verify Project ID: Found in Firebase Console → Project settings
- No trailing slash: The URL should not end with
/ - Case sensitivity: Project IDs are lowercase
INVALID_AUDIENCE error
INVALID_AUDIENCE error
The token’s audience doesn’t match:
- The audience must be your Firebase Project ID (not API key)
- Verify you’re using
getIdToken(), notgetAccessToken() - Check the Project ID in the Char configuration matches exactly
JWKS_FETCH_FAILED error
JWKS_FETCH_FAILED error
Char couldn’t reach Google’s JWKS endpoint:
- Firebase uses Google’s public keys at
https://www.googleapis.com/service_accounts/v1/jwk/[email protected] - This should always be accessible; if not, check your network configuration
Token expired
Token expired
Firebase tokens expire after 1 hour:
- Implement automatic token refresh (see “Token Refresh” section)
- Use
getIdToken(user, true)to force a fresh token - Consider checking
expclaim before making requests
Custom claims not appearing
Custom claims not appearing
If custom claims aren’t in the token:
- Custom claims require a token refresh to take effect
- Call
getIdToken(user, true)after setting claims - Check claims were set correctly using Admin SDK
- Custom claim keys cannot start with reserved prefixes (
firebase:,google:)
Firebase vs Google OAuth
Security Best Practices
- Enable email verification for email/password authentication
- Configure authorized domains in Firebase Console → Authentication → Settings
- Use security rules for Firestore/Realtime Database access control
- Enable App Check to protect against abuse
- Monitor usage in Firebase Console for unusual patterns
- Set session duration appropriately in Firebase Console
- Implement proper sign-out to invalidate sessions

