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.
> 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.
The server requires service account credentials to verify ID tokens, set cryptographically signed `httpOnly` session cookies, and protect against XSS token theft:
> - 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.
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.
- 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. |