docs: enrich Firebase setup guide with complete post-implementation steps, OAuth consent, and deployment checklist
This commit is contained in:
+185
-39
@@ -1,53 +1,106 @@
|
||||
# Complete Firebase Authentication Setup Guide
|
||||
# Complete Firebase Authentication Setup & Post-Implementation Guide
|
||||
|
||||
This document describes how to activate live authentication for the CRE Innovations Studio application using the Firebase Console. All client and server code, security headers, CSRF protections, and session cookies are already fully implemented and waiting for your credentials.
|
||||
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. Open the [Firebase Console](https://console.firebase.google.com/).
|
||||
2. Select your existing project or click **Add project** (e.g. `cre-innovations-studio`).
|
||||
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 Firebase Console left sidebar, navigate to **Build** > **Authentication**.
|
||||
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**:
|
||||
- Click **Google**, toggle **Enable**.
|
||||
- Choose your Project support email from the dropdown.
|
||||
- Click **Save**.
|
||||
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**:
|
||||
- Click **Email/Password**, toggle **Enable** (keep Email link disabled unless needed).
|
||||
- Click **Save**.
|
||||
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. Whitelist Authorized Domains
|
||||
## 3. Configure Google Cloud OAuth Consent Screen (Critical)
|
||||
|
||||
1. Under **Authentication** > **Settings** tab > **Authorized domains**:
|
||||
- Verify `localhost` is listed (present by default for local development).
|
||||
- Click **Add domain** and enter your production domain (e.g. `your-domain.com`, `creinnovations.com`, or your deployment domain).
|
||||
> [!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. Get Client Web SDK Keys
|
||||
## 4. Whitelist Authorized Domains
|
||||
|
||||
1. Go to **Project Settings** (gear icon in the top left) > **General** tab.
|
||||
2. Scroll down to the **Your apps** card:
|
||||
- If you haven't created a Web app yet, click the Web icon `</>`.
|
||||
- Register app with name (e.g. `CRE Studio Web`).
|
||||
3. Under **SDK setup and configuration**, select **Config**.
|
||||
4. Copy the values into your `.env.local` file:
|
||||
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=your-project-id.firebaseapp.com
|
||||
NEXT_PUBLIC_FIREBASE_PROJECT_ID=your-project-id
|
||||
NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET=your-project-id.appspot.com
|
||||
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
|
||||
@@ -55,29 +108,122 @@ NEXT_PUBLIC_FIREBASE_MEASUREMENT_ID=G-XXXXXXXXXX
|
||||
|
||||
---
|
||||
|
||||
## 5. Get Server Admin SDK Keys (Zero-Loophole Security)
|
||||
## 6. Generate Admin SDK Service Account Keys (Zero-Loophole Security)
|
||||
|
||||
To cryptographically mint secure `httpOnly` session cookies that cannot be accessed by browser scripts (XSS protection):
|
||||
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**, switch to the **Service accounts** tab.
|
||||
2. Ensure **Firebase Admin SDK** is selected (Node.js).
|
||||
3. Click **Generate new private key** and confirm. A JSON file will download.
|
||||
4. Open the downloaded JSON file and copy the values into `.env.local`:
|
||||
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=your-project-id
|
||||
FIREBASE_CLIENT_EMAIL=firebase-adminsdk-xxxxx@your-project-id.iam.gserviceaccount.com
|
||||
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"
|
||||
```
|
||||
|
||||
> **Note:** The private key must include the surrounding quotes and newline `\n` characters as formatted in the JSON download.
|
||||
> [!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.
|
||||
|
||||
---
|
||||
|
||||
## 6. Restart Server
|
||||
## 7. Customize Authentication Email Templates
|
||||
|
||||
Once your `.env.local` file is populated:
|
||||
```bash
|
||||
npm run dev # or npm run build && npm run start
|
||||
```
|
||||
The authentication system will immediately activate in full production mode!
|
||||
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. |
|
||||
|
||||
Reference in New Issue
Block a user