# 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 1. Navigate to the [Firebase Console](https://console.firebase.google.com/). 2. Click **Add project** (or select your existing project). 3. Name your project (e.g., `cre-innovations-studio`). 4. Google Analytics can be enabled or disabled based on your preference (if enabled, you'll receive a `NEXT_PUBLIC_FIREBASE_MEASUREMENT_ID`). 5. Click **Create project** and wait for provisioning to complete. --- ## 2. Enable Authentication Providers 1. In the left navigation menu, go to **Build** > **Authentication**. 2. Click **Get Started** if Authentication is not yet activated. 3. In the **Sign-in method** tab: - **Google**: 1. Click **Google** under Additional providers. 2. Toggle **Enable**. 3. Enter a **Public-facing name for project** (e.g., `CRE Innovations Studio`). 4. Select your **Project support email** from the dropdown. 5. Click **Save**. - **Email/Password**: 1. Click **Email/Password** under Native providers. 2. Toggle **Email/Password** to **Enable**. 3. Leave *Email link (passwordless sign-in)* disabled unless explicitly required. 4. Click **Save**. --- ## 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. 1. Open the [Google Cloud Console](https://console.cloud.google.com/) with the same Google account. 2. Select your Firebase project from the top project selector dropdown. 3. In the navigation menu, go to **APIs & Services** > **OAuth consent screen**. 4. If prompted, select User Type **External** and click **Create**. 5. 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. 6. Click **Save and Continue** through the Scopes step (standard `openid`, `email`, `profile` are pre-selected). 7. 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: 1. In the Firebase Console, go to **Authentication** > **Settings** tab. 2. Click **Authorized domains**. 3. Verify that `localhost` is listed (included by default). 4. Click **Add domain** and enter your production and staging domains: - Your production domain (e.g. `creinnovations.com` or `studio.creinnovations.com`) - Your deployment host domain (e.g. `your-app.vercel.app` or `your-app.up.railway.app`) --- ## 5. Retrieve Client Web SDK Keys 1. In the Firebase Console, click the **Settings gear icon ⚙️** (top left) > **Project settings**. 2. In the **General** tab, scroll down to the **Your apps** card. 3. 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**. 4. Under **SDK setup and configuration**, select **Config**. 5. Copy the configuration values into your local `.env.local` file: ```env 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: 1. In **Project settings**, click the **Service accounts** tab. 2. Confirm **Firebase Admin SDK** is selected (Node.js snippet displayed). 3. Click **Generate new private key** and confirm the dialog. 4. A JSON key file (e.g., `cre-innovations-studio-firebase-adminsdk-xxxxx.json`) will download to your machine. 5. Open the downloaded file in a text editor and extract the three fields into `.env.local`: ```env 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.local` or the downloaded JSON file to Git. > - Ensure the `FIREBASE_PRIVATE_KEY` is wrapped in double quotes and keeps the `\n` characters intact. Our code automatically handles replacing `\n` strings with real line breaks. --- ## 7. Customize Authentication Email Templates Make sure outbound emails reflect your brand: 1. In Firebase Console, go to **Authentication** > **Templates** tab. 2. 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. 3. Select **Email address verification**: - Customize sender name and reply-to address. 4. *(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`. --- ## 8. Anti-Abuse & Account Enumeration Protection 1. In Firebase Console, go to **Authentication** > **Settings** tab. 2. 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. 3. Under **Authorized domains**, ensure unneeded domains are not present. --- ## 9. Local Verification Checklist Once your `.env.local` file contains all keys: 1. **Restart your server**: ```bash cd /home/creserver/Desktop/WEBB npm run build && npm run start # or for development: # npm run dev ``` 2. **Open the browser** at `http://localhost:3000`. 3. **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. 4. **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. 5. **Inspect the Session Cookie**: - Open Chrome DevTools > **Application** tab > **Cookies** > `http://localhost:3000`. - Confirm that `__session` is present and marked `HttpOnly` and `SameSite: Lax`. 6. **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. 7. **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: 1. **Add Environment Variables**: In your hosting dashboard (e.g., Vercel Project Settings > Environment Variables), add all keys: - `NEXT_PUBLIC_FIREBASE_API_KEY` - `NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN` - `NEXT_PUBLIC_FIREBASE_PROJECT_ID` - `NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET` - `NEXT_PUBLIC_FIREBASE_MESSAGING_SENDER_ID` - `NEXT_PUBLIC_FIREBASE_APP_ID` - `NEXT_PUBLIC_FIREBASE_MEASUREMENT_ID` - `FIREBASE_PROJECT_ID` - `FIREBASE_CLIENT_EMAIL` - `FIREBASE_PRIVATE_KEY` > **Vercel / Multi-line Variable Tip**: When pasting `FIREBASE_PRIVATE_KEY` in Vercel or cloud dashboards, you can paste the entire string including `\n` or the raw multiline PEM block. The app's `formatPrivateKey` normalizer automatically sanitizes either format. 2. **Add Production URL to Authorized Domains**: - In Firebase Console > **Authentication** > **Settings** > **Authorized domains**, add your final domain (`https://creinnovations.com`). 3. **Verify HTTPS**: - In production (`NODE_ENV === 'production'`), the session cookie automatically sets the `Secure` flag. HTTPS is required for the session cookie to be stored by the browser. --- ## 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. |