230 lines
11 KiB
Markdown
230 lines
11 KiB
Markdown
# 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. |
|