11 KiB
Complete Firebase Authentication Setup & Post-Implementation Guide
This comprehensive runbook details everything you need to do in the Firebase Console, Google Cloud Platform, and your Hosting Environment to take the authentication system live.
All code, cryptographic session handling, CSRF protections, UI modals, and fallback states are already fully implemented. Follow this checklist to complete the credentials and security setup.
📋 Executive Checklist
- Step 1: Create or select your Firebase Project.
- Step 2: Enable Sign-In Methods (Google & Email/Password).
- Step 3: Configure Google Cloud OAuth Consent Screen (Production Mode).
- Step 4: Whitelist Authorized Domains.
- Step 5: Retrieve Client SDK Config & Paste into
.env.local. - Step 6: Generate Admin Service Account Private Key & Paste into
.env.local. - Step 7: Customize Authentication Email Templates.
- Step 8: Enable Account Enumeration Protection (Anti-Scraping).
- Step 9: Restart & Perform End-to-End Verification.
- Step 10: Production Deployment Setup (Vercel, Railway, VPS, etc.).
1. Firebase Project Setup
- Navigate to the Firebase Console.
- Click Add project (or select your existing project).
- Name your project (e.g.,
cre-innovations-studio). - Google Analytics can be enabled or disabled based on your preference (if enabled, you'll receive a
NEXT_PUBLIC_FIREBASE_MEASUREMENT_ID). - Click Create project and wait for provisioning to complete.
2. Enable Authentication Providers
- In the left navigation menu, go to Build > Authentication.
- Click Get Started if Authentication is not yet activated.
- In the Sign-in method tab:
- Google:
- Click Google under Additional providers.
- Toggle Enable.
- Enter a Public-facing name for project (e.g.,
CRE Innovations Studio). - Select your Project support email from the dropdown.
- Click Save.
- Email/Password:
- Click Email/Password under Native providers.
- Toggle Email/Password to Enable.
- Leave Email link (passwordless sign-in) disabled unless explicitly required.
- Click Save.
- Google:
3. Configure Google Cloud OAuth Consent Screen (Critical)
Important
If this step is skipped, users outside your workspace or developer account will receive an "Access Blocked / Unverified App" error when attempting Google Sign-In.
- Open the Google Cloud Console with the same Google account.
- Select your Firebase project from the top project selector dropdown.
- In the navigation menu, go to APIs & Services > OAuth consent screen.
- If prompted, select User Type External and click Create.
- Fill in the required fields:
- App name:
CRE Innovations Studio - User support email: Your support or admin email.
- Developer contact information: Your contact email.
- (Optional) Upload your app logo and links to Privacy Policy / Terms of Service.
- App name:
- Click Save and Continue through the Scopes step (standard
openid,email,profileare pre-selected). - Under Publishing status:
- If it says Testing, only specific test users can sign in.
- Click Publish App to switch to In production so any user can authenticate with Google.
4. Whitelist Authorized Domains
Firebase blocks OAuth popups from unlisted origins to prevent phishing:
- In the Firebase Console, go to Authentication > Settings tab.
- Click Authorized domains.
- Verify that
localhostis listed (included by default). - Click Add domain and enter your production and staging domains:
- Your production domain (e.g.
creinnovations.comorstudio.creinnovations.com) - Your deployment host domain (e.g.
your-app.vercel.apporyour-app.up.railway.app)
- Your production domain (e.g.
5. Retrieve Client Web SDK Keys
- In the Firebase Console, click the Settings gear icon ⚙️ (top left) > Project settings.
- In the General tab, scroll down to the Your apps card.
- If no web app exists:
- Click the Web icon
</>. - Enter an App nickname (e.g.,
CRE Studio Web). - Do not check "Also set up Firebase Hosting" (since this Next.js app is hosted independently).
- Click Register app.
- Click the Web icon
- Under SDK setup and configuration, select Config.
- Copy the configuration values into your local
.env.localfile:
NEXT_PUBLIC_FIREBASE_API_KEY=AIzaSy...
NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN=cre-innovations-studio.firebaseapp.com
NEXT_PUBLIC_FIREBASE_PROJECT_ID=cre-innovations-studio
NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET=cre-innovations-studio.appspot.com
NEXT_PUBLIC_FIREBASE_MESSAGING_SENDER_ID=123456789012
NEXT_PUBLIC_FIREBASE_APP_ID=1:123456789012:web:abcdef123456
NEXT_PUBLIC_FIREBASE_MEASUREMENT_ID=G-XXXXXXXXXX
6. Generate Admin SDK Service Account Keys (Zero-Loophole Security)
The server requires service account credentials to verify ID tokens, set cryptographically signed httpOnly session cookies, and protect against XSS token theft:
- In Project settings, click the Service accounts tab.
- Confirm Firebase Admin SDK is selected (Node.js snippet displayed).
- Click Generate new private key and confirm the dialog.
- A JSON key file (e.g.,
cre-innovations-studio-firebase-adminsdk-xxxxx.json) will download to your machine. - Open the downloaded file in a text editor and extract the three fields into
.env.local:
FIREBASE_PROJECT_ID=cre-innovations-studio
FIREBASE_CLIENT_EMAIL=firebase-adminsdk-xxxxx@cre-innovations-studio.iam.gserviceaccount.com
FIREBASE_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\nMIIEvgIBADANBgkqhkiG9w0BAQEFAASCBKgwggSkAgEAAoIBAQC...\n-----END PRIVATE KEY-----\n"
Caution
- Never commit
.env.localor the downloaded JSON file to Git.- Ensure the
FIREBASE_PRIVATE_KEYis wrapped in double quotes and keeps the\ncharacters intact. Our code automatically handles replacing\nstrings with real line breaks.
7. Customize Authentication Email Templates
Make sure outbound emails reflect your brand:
- In Firebase Console, go to Authentication > Templates tab.
- Select Password reset:
- Click the pencil icon to edit.
- Customize the Sender name (e.g.
CRE Innovations Studio). - Set Reply-to address.
- Adjust message subject and body if desired.
- Select Email address verification:
- Customize sender name and reply-to address.
- (Optional / Recommended for Custom Domain Branding):
- Click the edit icon next to From address to configure your custom domain email (via Mailgun, SendGrid, or custom SMTP/DNS records) so emails don't come from
@firebaseapp.com.
- Click the edit icon next to From address to configure your custom domain email (via Mailgun, SendGrid, or custom SMTP/DNS records) so emails don't come from
8. Anti-Abuse & Account Enumeration Protection
- In Firebase Console, go to Authentication > Settings tab.
- Under User actions, verify that Email enumeration protection is Enabled.
- This prevents attackers from guessing whether an email is registered by returning identical response codes.
- Under Authorized domains, ensure unneeded domains are not present.
9. Local Verification Checklist
Once your .env.local file contains all keys:
- Restart your server:
cd /home/creserver/Desktop/WEBB npm run build && npm run start # or for development: # npm run dev - Open the browser at
http://localhost:3000. - Verify the UI:
- Click the Sign In button in the top navbar.
- Notice the amber "Firebase not configured" banner is now gone.
- You should see the sleek dark-glass Sign In modal with Google OAuth and Email/Password fields.
- Test Email/Password Flow:
- Switch to Create account tab.
- Enter a test email and password (minimum 8 characters with at least one number).
- Click Create Account.
- Verify that you are signed in, the modal closes, and the Navbar shows your user avatar dropdown.
- Inspect the Session Cookie:
- Open Chrome DevTools > Application tab > Cookies >
http://localhost:3000. - Confirm that
__sessionis present and markedHttpOnlyandSameSite: Lax.
- Open Chrome DevTools > Application tab > Cookies >
- Test Google Sign-In:
- Click your avatar > Sign Out.
- Click Sign In > Continue with Google.
- Select your Google account in the popup.
- Confirm you are logged in and your Google profile photo / name appears in the UserMenu.
- Verify in Firebase Console:
- Go to Authentication > Users tab.
- Confirm your registered test users appear with their correct Provider, Created, and Last Signed In timestamps.
10. Production Deployment Setup (Vercel, Railway, Docker, etc.)
When deploying to production:
-
Add Environment Variables: In your hosting dashboard (e.g., Vercel Project Settings > Environment Variables), add all keys:
NEXT_PUBLIC_FIREBASE_API_KEYNEXT_PUBLIC_FIREBASE_AUTH_DOMAINNEXT_PUBLIC_FIREBASE_PROJECT_IDNEXT_PUBLIC_FIREBASE_STORAGE_BUCKETNEXT_PUBLIC_FIREBASE_MESSAGING_SENDER_IDNEXT_PUBLIC_FIREBASE_APP_IDNEXT_PUBLIC_FIREBASE_MEASUREMENT_IDFIREBASE_PROJECT_IDFIREBASE_CLIENT_EMAILFIREBASE_PRIVATE_KEY
Vercel / Multi-line Variable Tip: When pasting
FIREBASE_PRIVATE_KEYin Vercel or cloud dashboards, you can paste the entire string including\nor the raw multiline PEM block. The app'sformatPrivateKeynormalizer automatically sanitizes either format. -
Add Production URL to Authorized Domains:
- In Firebase Console > Authentication > Settings > Authorized domains, add your final domain (
https://creinnovations.com).
- In Firebase Console > Authentication > Settings > Authorized domains, add your final domain (
-
Verify HTTPS:
- In production (
NODE_ENV === 'production'), the session cookie automatically sets theSecureflag. HTTPS is required for the session cookie to be stored by the browser.
- In production (
11. Common Troubleshooting
| Issue | Cause | Fix |
|---|---|---|
auth/unauthorized-domain |
Current domain not in whitelist | Add domain to Firebase Console > Authentication > Settings > Authorized domains. |
auth/popup-blocked |
Browser blocked Google OAuth popup | Allow popups for your domain or test in standard browser window. |
| "Access blocked: This app's request is invalid" | OAuth consent screen not configured | Complete Step 3 in Google Cloud Console > APIs & Services > OAuth consent screen. |
| "Admin token verification failed" | Malformed FIREBASE_PRIVATE_KEY |
Ensure FIREBASE_PRIVATE_KEY is wrapped in double quotes in .env.local with \n escapes intact. |
| Session cookie missing after refresh | HTTP used instead of HTTPS in production | Ensure your production host has SSL/HTTPS enabled; cookies enforce Secure in production. |