@evenicanpm/storefront-core 2.4.2 → 2.5.0

package/src/auth/AUTH GUIDE.md

@@ -0,0 +1,880 @@
+# Authentication Architecture: Better Auth & Microsoft Entra External ID
+
+This document describes the authentication system used in the E4 Storefront, which combines [Better Auth](https://betterauth.dev/) with Microsoft Entra External ID for secure, enterprise-grade user authentication.
+
+## Table of Contents
+
+1. [Overview](#overview)
+2. [Architecture](#architecture)
+3. [Better Auth Configuration](#better-auth-configuration)
+4. [Microsoft Entra External ID Setup](#microsoft-entra-external-id-setup)
+5. [Native Screen Authentication (ROPC)](#native-screen-authentication-ropc)
+6. [Token Management](#token-management)
+7. [Session Management](#session-management)
+8. [Client-Side Usage](#client-side-usage)
+9. [API Integration](#api-integration)
+10. [Deployment & Environment Configuration](#deployment--environment-configuration)
+11. [Troubleshooting](#troubleshooting)
+
+## Overview
+
+The authentication system uses:
+- **Better Auth**: A modern authentication library for TypeScript/JavaScript applications
+- **Microsoft Entra External ID**: Enterprise identity provider for external user authentication
+- **PostgreSQL**: Database for storing user accounts and sessions
+- **OAuth 2.0 with PKCE**: Secure authorization flow for browser-based applications
+- **Resource Owner Password Credential (ROPC)**: Support for native screen (email/password) login
+
+### Key Features
+
+- ✅ OAuth 2.0 / OpenID Connect support
+- ✅ Native email/password login (via Microsoft Entra ROPC)
+- ✅ Automatic token refresh before expiration
+- ✅ Proactive token refresh (5-minute window before expiry)
+- ✅ Secure session management with HTTP-only cookies
+- ✅ Support for multiple identity providers
+- ✅ Graph API access tokens for Microsoft integration
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────┐
+│           Client Application (React/Next.js)        │
+├─────────────────────────────────────────────────────┤
+│                  Auth Client                        │
+│    (createAuthClient from better-auth/react)        │
+└────────────────────┬────────────────────────────────┘
+                     │ HTTP/REST
+                     ▼
+┌─────────────────────────────────────────────────────┐
+│         Better Auth API Handler                     │
+│    (/api/auth/[...all] - Next.js Dynamic Route)     │
+├─────────────────────────────────────────────────────┤
+│  • Session management                               │
+│  • OAuth flow orchestration                         │
+│  • Token storage & encryption                       │
+│  • Proactive token refresh                          │
+└────────────────────┬────────────────────────────────┘
+         │           │           │
+         ▼           ▼           ▼
+    ┌─────────┬──────────┬──────────────┐
+    │ PostgreSQL        │ Microsoft        │
+    │ Database          │ Entra External   │
+    │ (Sessions,        │ ID (OIDC/OAuth2) │
+    │  Accounts,        │                  │
+    │  Users)           │                  │
+    └───────────────────┴──────────────────┘
+```
+
+## Better Auth Configuration
+
+### Core Setup
+
+Better Auth is initialized in [better-auth.ts](./better-auth.ts) with the following configuration:
+
+```typescript
+const authConfig = {
+  secret: process.env.BETTER_AUTH_SECRET,
+  baseURL: process.env.BETTER_AUTH_URL,
+  database: authDbPool, // PostgreSQL connection
+  
+  // Enable email/password authentication
+  emailAndPassword: {
+    enabled: true,
+  },
+  
+  // Session configuration
+  session: {
+    cookieCache: {
+      enabled: false, // Disable cache for fresh data
+    },
+  },
+  
+  // Account storage
+  account: {
+    storeStateStrategy: "cookie",
+    storeAccountCookie: true,
+  },
+  
+  plugins: [
+    // Generic OAuth provider for Microsoft Entra External ID
+    genericOAuth({ ... }),
+    
+    // Custom session enrichment with token management
+    customSession({ ... }),
+    
+    // Next.js cookie handling
+    nextCookies(),
+  ],
+};
+```
+
+### Database Requirements
+
+Better Auth requires a PostgreSQL database with the following tables:
+
+- `public.user`: User profiles
+- `public.account`: OAuth account linked to users (stores encrypted tokens)
+- `public.session`: Active user sessions
+- `public.verification`: Email verification tokens
+
+For setup, see the [e4-Bootstrap database schema](../../../db/schema.sql).
+
+## Microsoft Entra External ID Setup
+
+### What is Entra External ID?
+
+Microsoft Entra External ID (formerly Azure AD B2C) is a Customer Identity and Access Management (CIAM) solution that enables:
+- External user registration and authentication
+- Social login integration
+- Custom branding and policies
+- API protection with access tokens
+
+### Configuration
+
+#### Environment Variables
+
+```bash
+# Entra External ID tenant configuration
+MICROSOFT_ENTRA_EXTERNAL_ID_CLIENT_ID=f6cf50bc-8d8c-4e73-be82-cc29a5ee3bb9
+MICROSOFT_ENTRA_EXTERNAL_ID_TENANT_NAME=e4productdeventraexternalid
+MICROSOFT_ENTRA_EXTERNAL_ID_CUSTOM_SCOPES="offline_access openid email profile User.ReadWrite"
+# Scope Meanings:
+# offline_access: Enables refresh token grant
+# openid: Returns ID token with user claims
+# email: Includes email claim in ID token
+# profile: Includes profile claims (name, picture, etc.)
+# User.ReadWrite: Microsoft Graph permission to read/write user profile
+
+# Better Auth configuration
+BETTER_AUTH_SECRET=dB8GBZaXL0TrSZpKVhpIOxyMnJ15ALtrtPsMOyIqDvw=
+BETTER_AUTH_URL=http://storefront.e4.local # or production URL
+AUTH_DB_URL=postgresql://user:password@host:port/database
+```
+
+#### OAuth Discovery
+
+Better Auth uses Entra's OpenID Connect discovery endpoint:
+
+```
+https://{TENANT_NAME}.ciamlogin.com/{TENANT_NAME}.onmicrosoft.com/v2.0/.well-known/openid-configuration
+```
+
+This endpoint provides:
+- Authorization endpoint
+- Token endpoint
+- JWKS (JSON Web Key Set) for token verification
+- User info endpoint
+- Supported scopes and claims
+
+#### Provider Configuration
+
+```typescript
+{
+  providerId: "entra-external-id",
+  clientId: process.env.NEXT_PUBLIC_ENTRA_EXTERNAL_ID_CLIENT_ID,
+  discoveryUrl: `${loginAuthority}/v2.0/.well-known/openid-configuration`,
+  scopes: [
+    "offline_access",    // Required for refresh tokens
+    "openid",            // Required for ID tokens
+    "email",             // Access email claim
+    "profile",           // Access profile claims (name, picture, etc.)
+    "User.ReadWrite",    // Microsoft Graph permission
+  ],
+  pkce: true,           // Proof Key for Public Clients (required)
+  prompt: "login",      // Always show login screen
+}
+```
+
+**Important**: Entra External ID is configured as a **public client** (no client secret), so PKCE is mandatory for security.
+
+#### User Info Extraction
+
+The `getUserInfo` function decodes the ID token's JWT payload to extract user claims:
+
+```typescript
+getUserInfo: async (tokens) => {
+  const idToken = tokens.idToken;
+  const payload = JSON.parse(
+    Buffer.from(idToken.split(".")[1], "base64url").toString()
+  );
+  
+  return {
+    id: payload.oid || payload.sub,       // Object ID or Subject
+    name: payload.name,                    // User's display name
+    email: payload.email || payload.emails?.[0],
+    emailVerified: !!payload.email_verified,
+  };
+};
+```
+
+**Key Claims:**
+- `oid`: Unique object ID in Entra External ID (preferred for user identification)
+- `sub`: Subject claim (fallback)
+- `email`: Primary email address
+- `email_verified`: Whether email is verified
+- `name`: User's display name
+
+## Native Screen Authentication (ROPC)
+
+### What is ROPC?
+
+Resource Owner Password Credential (ROPC) is an OAuth 2.0 flow designed for trusted applications where users enter credentials directly into the application UI (native screens).
+
+### How It Works in E4
+
+```
+┌──────────────────────────────┐
+│  User Enters Email/Password  │
+│  in Native Login Screen      │
+└──────────────┬───────────────┘
+               │
+               ▼
+      ┌────────────────────────┐
+      │ Entra ROPC Endpoint:   │
+      │ POST /token           │
+      │ - client_id           │
+      │ - username (email)    │
+      │ - password            │
+      │ - scope               │
+      └────────────┬───────────┘
+                   │
+                   ▼
+      ┌────────────────────────┐
+      │ Validate credentials   │
+      │ Return:               │
+      │ - access_token        │
+      │ - refresh_token       │
+      │ - id_token            │
+      │ - expires_in          │
+      └────────────┬───────────┘
+               │
+               ▼
+      ┌────────────────────────────┐
+      │ Better Auth:               │
+      │ 1. Create email/password   │
+      │    user in local DB        │
+      │ 2. Upsert Entra account    │
+      │    with OAuth tokens       │
+      │ 3. Create session          │
+      └────────────────────────────┘
+```
+
+### Implementation Notes
+
+- **Email/Password User**: Better Auth stores a local email/password user for session management
+- **Entra Account**: The actual OAuth tokens from Entra are stored in a separate account record
+- **Account Linking**: Email/password user is linked to Entra account via user ID
+- **Token Storage**: OAuth tokens are encrypted before storage using `setTokenUtil`
+
+### Security Considerations
+
+✅ **Advantages:**
+- No redirect required (native UI)
+- Better UX for trusted applications
+- Direct password validation with Entra
+
+⚠️ **Implemented controls:**
+- HTTPS only in production
+- Secure password input (masked in UI)
+- Rate limiting on the token endpoint
+- Token encryption at rest in the database via Better Auth token helpers
+
+These controls are already part of the authentication stack and should be treated as baseline behavior, not future work.
+
+## Token Management
+
+### Token Types
+
+| Token | Purpose | Scope | Lifetime |
+|-------|---------|-------|----------|
+| **ID Token** | User identity (JWT) | OpenID, profile | ~1 hour |
+| **Access Token** | API authorization (Graph API) | User.ReadWrite | ~1 hour |
+| **Refresh Token** | Obtain new access tokens | offline_access | ~90 days |
+
+### Token Storage
+
+Tokens are stored in the `public.account` table:
+
+```typescript
+{
+  id: string,                    // Account ID
+  userId: string,                // Linked user ID
+  providerId: string,            // "entra-external-id"
+  accessToken: string,           // Encrypted access token
+  refreshToken: string,          // Encrypted refresh token
+  idToken: string | null,        // Encrypted ID token
+  accessTokenExpiresAt: Date,    // Absolute expiration time
+  refreshTokenExpiresAt: Date,   // Refresh token expiration
+  scope: string,                 // Comma-separated scopes
+}
+```
+
+**Token Encryption:**
+- Uses Better Auth's `setTokenUtil()` to encrypt sensitive tokens
+- Uses `decryptOAuthToken()` when reading from database
+- Prevents plain-text token exposure in database
+
+### Proactive Token Refresh
+
+Better Auth implements **proactive refresh** to prevent users from being unexpectedly logged out:
+
+```typescript
+const ACCESS_TOKEN_REFRESH_WINDOW_MS = 5 * 60 * 1000; // 5 minutes
+
+// Before returning the session, check if:
+// 1. Token exists and is not yet expired
+// 2. Token is within 5 minutes of expiration
+// 3. A refresh token is available
+
+if (shouldRefreshUpfront && account.refreshToken) {
+  const refreshed = await refreshEntraTokens(account, context);
+  // Update stored tokens and session
+}
+```
+
+**Why 5 Minutes?**
+- Better Auth's default (~5 seconds) is too late; token may expire during API calls
+- 5-minute window gives buffer for network latency and processing time
+- Balances security (frequent refresh) with performance (not too frequent)
+
+### Token Refresh Flow
+
+```
+Session Request
+       │
+       ▼
+Check Token Status
+  │        │
+  ├─ Expired → Clear tokens, user signs out
+  │
+  ├─ Within 5 min → Attempt proactive refresh
+  │    │
+  │    ├─ Has refresh token?
+  │    │    │
+  │    │    ├─ Yes → Call Entra /token endpoint
+  │    │    │         Update stored tokens
+  │    │    │
+  │    │    └─ No → Keep current token
+  │    │
+  │    └─ Refresh fails? → Use current token (graceful degradation)
+  │
+  └─ Valid (>5 min) → Return current tokens
+       │
+       ▼
+   Return Session with Tokens
+```
+
+### Manual Token Refresh
+
+When needed, manually refresh tokens using the provider's `refreshAccessToken()`:
+
+```typescript
+const provider = await resolveEntraRefreshProvider(socialProviders);
+const newTokens = await provider.refreshAccessToken(currentRefreshToken);
+```
+
+## Session Management
+
+### Session Lifecycle
+
+```
+1. User logs in → Create session
+   - Better Auth creates session record
+   - Sets secure HTTP-only cookie
+   - Returns session data
+
+2. User makes requests → Validate & refresh session
+   - Middleware checks cookie
+   - Session data retrieved from database
+   - Proactive token refresh attempted if needed
+
+3. User logs out → Clear session
+   - Session record deleted
+   - Cookie cleared on client
+   - User redirect to home page
+```
+
+### Session Data Structure
+
+```typescript
+interface Session {
+  id: string;
+  userId: string;
+  expiresAt: Date;
+  token: string;
+  ipAddress?: string;
+  userAgent?: string;
+  
+  // Custom fields from customSession plugin
+  accessToken: string;        // ID token for D365
+  graphAccessToken: string;   // Access token for Microsoft Graph
+}
+```
+
+### Session Security
+
+- **HTTP-only Cookies**: Session token stored in HTTP-only cookie (not accessible by JavaScript)
+- **Secure Flag**: Cookies only sent over HTTPS in production
+- **SameSite**: Prevents CSRF attacks
+- **Session Expiration**: Configurable timeout (default: 30 days)
+- **Token Encryption**: Refresh tokens encrypted in database
+
+### Session Validation in Middleware
+
+```typescript
+ // In Next.js proxy (src/proxy.ts)
+const sessionCookie = getSessionCookie(request);
+
+if (!sessionCookie) {
+  // No session: redirect to login
+  return NextResponse.redirect(new URL("/login", request.url));
+}
+
+// Session exists: allow request
+return intlMiddleware(request);
+```
+
+## Client-Side Usage
+
+### Auth Client Setup
+
+[auth-client.ts](./lib/auth-client.ts):
+
+```typescript
+import { createAuthClient } from "better-auth/react";
+import { genericOAuthClient, customSessionClient } from "better-auth/client/plugins";
+
+export const authClient = createAuthClient({
+  plugins: [
+    genericOAuthClient(),
+    customSessionClient<typeof auth>(),
+  ],
+});
+
+export const { signIn, signOut, signUp, useSession, getSession } = authClient;
+```
+
+### Sign In with OAuth (Redirect Flow)
+
+```typescript
+import { signIn } from "@storefront/auth/auth-client";
+
+const handleOAuthLogin = async () => {
+  await signIn.social({
+    provider: "entra-external-id",
+    callbackURL: "/account", // Redirect after login
+  });
+};
+
+// Button
+<button onClick={handleOAuthLogin}>Sign in with Entra</button>
+```
+
+### Sign In with Native Screen (Email/Password)
+
+```typescript
+const handleNativeLogin = async (email: string, password: string) => {
+  const response = await signIn.password({
+    email,
+    password,
+    callbackURL: "/account",
+  });
+  
+  if (!response.ok) {
+    // Handle errors: invalid email/password, etc.
+    console.error(response.error?.message);
+  }
+};
+```
+
+### Use Session Hook
+
+```typescript
+import { useSession } from "@storefront/auth/auth-client";
+
+function UserProfile() {
+  const { data: session, isPending } = useSession();
+  
+  if (isPending) return <div>Loading...</div>;
+  
+  if (!session) return <div>Not signed in</div>;
+  
+  return (
+    <div>
+      <h1>Hello, {session.user.name}</h1>
+      <p>Email: {session.user.email}</p>
+      
+      {/* Custom session fields from customSession plugin */}
+      <p>Graph Access Token: {session.accessToken}</p>
+    </div>
+  );
+}
+```
+
+### Sign Out
+
+```typescript
+import signOut from "@storefront/auth/signout";
+
+const handleLogout = async () => {
+  await signOut(); // Clears session, redirects to home
+};
+```
+
+### Get Session Directly
+
+```typescript
+import { getSession } from "@storefront/auth/auth-client";
+
+// In server component or API route
+const session = await getSession();
+
+if (session) {
+  // User authenticated
+  // Use session.accessToken for Graph API calls
+} else {
+  // User not authenticated
+}
+```
+
+### Session Hook with Session Data
+
+```typescript
+import { useSession } from "@storefront/auth/auth-client";
+
+function GraphAPIConsumer() {
+  const { data: session } = useSession();
+  
+  // Use graph access token for Microsoft Graph API
+  const graphToken = session?.graphAccessToken;
+  
+  const callGraphAPI = async () => {
+    const response = await fetch("https://graph.microsoft.com/v1.0/me", {
+      headers: {
+        Authorization: `Bearer ${graphToken}`,
+      },
+    });
+    const profile = await response.json();
+    return profile;
+  };
+  
+  return <button onClick={callGraphAPI}>Load Profile from Graph</button>;
+}
+```
+
+## API Integration
+
+### API Route Handler
+
+[/api/auth/[...all]/route.ts](../../../apps/storefront/src/app/api/auth/%5B...all%5D/route.ts):
+
+```typescript
+import { auth } from "@storefront/lib/auth";
+import { toNextJsHandler } from "better-auth/next-js";
+
+export const { GET, POST } = toNextJsHandler(auth);
+```
+
+**Endpoints Provided:**
+- `POST /api/auth/sign-in` - Sign in with email/password
+- `POST /api/auth/sign-out` - Sign out
+- `POST /api/auth/sign-up` - Register new account
+- `GET /api/auth/callback` - OAuth redirect callback
+- `POST /api/auth/callback` - OAuth callback (POST)
+- `POST /api/auth/refresh` - Manual session refresh
+- `GET /api/auth/session` - Get current session (client-side)
+
+### Graph API Access Example
+
+```typescript
+async function getUserProfileFromGraph(accessToken: string) {
+  const response = await fetch("https://graph.microsoft.com/v1.0/me", {
+    headers: {
+      Authorization: `Bearer ${accessToken}`,
+      "Content-Type": "application/json",
+    },
+  });
+  
+  if (!response.ok) {
+    throw new Error(`Graph API error: ${response.statusText}`);
+  }
+  
+  return response.json();
+}
+
+// In API route
+export async function GET(request: Request) {
+  const session = await getSession();
+  
+  if (!session?.graphAccessToken) {
+    return Response.json({ error: "Unauthorized" }, { status: 401 });
+  }
+  
+  const profile = await getUserProfileFromGraph(session.graphAccessToken);
+  return Response.json(profile);
+}
+```
+
+## Deployment & Environment Configuration
+
+### Environment Variables
+
+See [.env.example](../../../../../.env.example) for full list.
+
+**Critical for Authentication:**
+
+```bash
+# Better Auth
+BETTER_AUTH_SECRET=<generated-secret-key-32-chars>
+BETTER_AUTH_URL=https://api.example.com  # Public URL of API
+
+# Database
+AUTH_DB_URL=postgresql://user:pass@host:port/auth_db
+
+# Microsoft Entra External ID
+MICROSOFT_ENTRA_EXTERNAL_ID_CLIENT_ID=<client-id>
+MICROSOFT_ENTRA_EXTERNAL_ID_TENANT_NAME=<tenant-name>
+MICROSOFT_ENTRA_EXTERNAL_ID_CUSTOM_SCOPES="offline_access openid email profile User.ReadWrite"
+
+# Public (safe for client-side)
+NEXT_PUBLIC_ENTRA_EXTERNAL_ID_CLIENT_ID=<same-as-above>
+NEXT_PUBLIC_ENTRA_EXTERNAL_ID_CUSTOM_SCOPES="offline_access openid email profile"
+NEXT_PUBLIC_ENTRA_EXTERNAL_ID_TENANT_NAME=<tenant-name>
+```
+
+### Docker Compose
+
+[compose.yml](../../../../../compose.yml) environment variables:
+
+```yaml
+services:
+  storefront:
+    environment:
+      - BETTER_AUTH_SECRET=${BETTER_AUTH_SECRET}
+      - BETTER_AUTH_URL=${BETTER_AUTH_URL}
+      - AUTH_DB_URL=${AUTH_DB_URL}
+      - MICROSOFT_ENTRA_EXTERNAL_ID_CLIENT_ID=${MICROSOFT_ENTRA_EXTERNAL_ID_CLIENT_ID}
+      - MICROSOFT_ENTRA_EXTERNAL_ID_TENANT_NAME=${MICROSOFT_ENTRA_EXTERNAL_ID_TENANT_NAME}
+      - NEXT_PUBLIC_ENTRA_EXTERNAL_ID_CLIENT_ID=${MICROSOFT_ENTRA_EXTERNAL_ID_CLIENT_ID}
+```
+
+## Troubleshooting
+
+### Common Issues
+
+#### 1. "Session not found" or constant redirects to login
+
+**Possible Causes:**
+- `BETTER_AUTH_SECRET` changed or missing
+- Database connection lost
+- Session database schema not initialized
+- Cookie domain mismatch
+
+**Solutions:**
+1. Verify `BETTER_AUTH_SECRET` is consistent across deployments
+2. Check database connectivity: `AUTH_DB_URL`
+3. Verify session tables exist: `public.session`, `public.user`, `public.account`
+4. Check cookie domain in compose.yml matches application URL
+
+#### 2. "Invalid OAuth provider" or OAuth redirect not working
+
+**Possible Causes:**
+- `MICROSOFT_ENTRA_EXTERNAL_ID_CLIENT_ID` incorrect or missing
+- `MICROSOFT_ENTRA_EXTERNAL_ID_TENANT_NAME` incorrect
+- Entra tenant not configured to allow the redirect URI
+- Discovery URL unreachable
+
+**Solutions:**
+1. Verify Client ID matches Entra External ID app registration
+2. Verify Tenant Name is correct (without ".onmicrosoft.com")
+3. Add redirect URI to Entra app registration: `https://your-domain.com/api/auth/callback/entra-external-id`
+4. Test discovery endpoint: `https://{tenant}.ciamlogin.com/{tenant}.onmicrosoft.com/v2.0/.well-known/openid-configuration`
+
+#### 3. Token refresh fails: "Refresh token invalid" or "Provider not found"
+
+**Possible Causes:**
+- Entra provider not configured in `socialProviders`
+- Refresh token expired (90+ days old)
+- Stored refresh token corrupted or incorrectly decrypted
+
+**Solutions:**
+1. Verify `genericOAuth` plugin configured with `entra-external-id` provider
+2. Check refresh token expiration in database
+3. Clear browser cookies and re-authenticate
+4. Check database for corruption: `SELECT scope FROM public.account WHERE providerId = 'entra-external-id' LIMIT 1`
+
+#### 4. Native screen login not working: "Invalid credentials" or "User not found"
+
+**Possible Causes:**
+- Email/password not enabled: `emailAndPassword.enabled = false`
+- Entra ROPC not configured
+- Entra tenant policy disables password authentication
+- User not created in Entra External ID
+
+**Solutions:**
+1. Verify `emailAndPassword.enabled: true` in auth config
+2. Test Entra ROPC endpoint directly with curl:
+   ```bash
+   curl -X POST https://{tenant}.ciamlogin.com/{tenant}.onmicrosoft.com/oauth2/v2.0/token \
+     -H "Content-Type: application/x-www-form-urlencoded" \
+     -d "client_id={clientId}&username={email}&password={password}&scope=offline_access&grant_type=password"
+   ```
+3. Check Entra user properties: email, enabled, password set
+4. Verify user policies allow password authentication
+
+#### 5. "Cannot find module 'better-auth'" or import errors
+
+**Possible Causes:**
+- `better-auth` not installed in storefront package
+- Node modules not installed
+- TypeScript cache issues
+
+**Solutions:**
+1. Ensure `better-auth` in storefront `package.json` dependencies
+2. Run `npm install` in storefront and root
+3. Delete `node_modules` and `.next` cache: `rm -rf node_modules .next && npm install`
+4. Restart TypeScript server in VS Code
+
+#### 6. Graph API calls fail: "401 Unauthorized" or "Invalid access token"
+
+**Possible Causes:**
+- Access token expired and proactive refresh didn't occur
+- Graph API scopes not requested in Entra
+- Access token is ID token instead
+
+**Solutions:**
+1. Verify `session.graphAccessToken` is not empty
+2. Add `User.ReadWrite` to `MICROSOFT_ENTRA_EXTERNAL_ID_CUSTOM_SCOPES`
+3. Check token type: decode JWT at [jwt.io](https://jwt.io) and verify `aud` claim is Microsoft Graph
+4. Force token refresh: implement manual refresh in session logic
+
+
+### Testing Authentication Locally
+
+1. **Pre-check local config (required before testing):**
+  ```bash
+  # Verify the auth env vars are present
+  grep -E "NEXT_PUBLIC_ENTRA_EXTERNAL_ID_CLIENT_ID|NEXT_PUBLIC_ENTRA_EXTERNAL_ID_TENANT_NAME|BETTER_AUTH_SECRET|AUTH_DB_URL" .env
+
+  # Start docker container and confirm it is healthy
+  # Open http://storefront.e4.local:3000
+  ```
+  Expected result:
+  - Storefront loads without auth-related boot errors.
+  - No `Missing BETTER_AUTH_SECRET` or DB connection errors in server logs.
+
+2. **Test storefront signup and login flow:**
+  ```bash
+  # Go to https://storefront.e4.local/login
+  # Sign up with a real email address
+  # Enter the verification code sent to the email inbox
+  # After verification, the user should be signed in automatically
+  ```
+  Validation checklist:
+  - After code verification, confirm the app lands on the authenticated session without a second login prompt.
+  - Open the storefront and verify catalog flows still work: Categories, PLP, and PDP pages should load normally while signed in.
+  - Go to the account area and open the profile page to confirm the signed-in user's details are shown.
+  - In browser DevTools Network tab, confirm the auth calls return 200/204 (not 401/403).
+  - In DB, confirm an `entra-external-id` account exists for the user:
+  ```sql
+  SELECT u.email, a.providerId, a.accessTokenExpiresAt, a.refreshTokenExpiresAt
+  FROM public.account a
+  JOIN public.user u ON u.id = a.userId
+  WHERE a.providerId = 'entra-external-id'
+  ORDER BY a.accessTokenExpiresAt DESC
+  LIMIT 5;
+  ```
+
+3. **Test Session Persistence (browser refresh and new request):**
+  ```bash
+  # After successful login:
+  # 1) Refresh the page (F5)
+  # 2) Navigate to another protected page
+  # 3) Hard refresh (Ctrl+Shift+R / Cmd+Shift+R)
+  ```
+  Expected result:
+  - User remains authenticated across refreshes.
+  - Cookie `better-auth_session` remains present and rotates only when expected.
+  - No redirect loop to `/login`.
+
+4. **Test Proactive Token Refresh (fast feedback mode):**
+  ```typescript
+  // Temporarily reduce refresh window in better-auth.ts for local testing only
+  const ACCESS_TOKEN_REFRESH_WINDOW_MS = 1000; // 1 second
+  ```
+  Test steps:
+  - Restart the app after changing the constant.
+  - Sign in and keep an authenticated page open.
+  - Trigger one or more authenticated requests (page navigation, profile fetch, Graph call).
+
+  Expected result:
+  - You should see refresh activity in logs.
+  - Session remains valid after refresh attempt.
+  - `accessTokenExpiresAt` advances in `public.account` after successful refresh.
+
+  Verify in DB:
+  ```sql
+  SELECT u.email, a.accessTokenExpiresAt, a.refreshTokenExpiresAt, NOW() AS now
+  FROM public.account a
+  JOIN public.user u ON u.id = a.userId
+  WHERE a.providerId = 'entra-external-id'
+  ORDER BY a.accessTokenExpiresAt DESC
+  LIMIT 5;
+  ```
+
+5. **Reset test-only changes:**
+  ```typescript
+  // Restore default after testing
+  const ACCESS_TOKEN_REFRESH_WINDOW_MS = 5 * 60 * 1000;
+  ```
+  Do not keep a 1-second window in normal development or production.
+
+### Useful Database Queries
+
+```sql
+-- List all authenticated users
+SELECT u.id, u.email, u.name, u.createdAt 
+FROM public.user u 
+ORDER BY u.createdAt DESC;
+
+-- Check Entra accounts and token status
+SELECT 
+  u.email,
+  a.providerId,
+  a.accessTokenExpiresAt,
+  a.refreshTokenExpiresAt,
+  NOW() as current_time
+FROM public.account a
+JOIN public.user u ON a.userId = u.id
+WHERE a.providerId = 'entra-external-id'
+ORDER BY a.accessTokenExpiresAt;
+
+-- Check active sessions
+SELECT 
+  s.id,
+  u.email,
+  s.createdAt,
+  s.expiresAt
+FROM public.session s
+JOIN public.user u ON s.userId = u.id
+WHERE s.expiresAt > NOW()
+ORDER BY s.expiresAt DESC;
+
+-- Clear expired sessions (cleanup)
+DELETE FROM public.session 
+WHERE expiresAt < NOW();
+```
+
+## Additional Resources
+
+- [Better Auth Documentation](https://betterauth.dev/)
+- [Microsoft Entra External ID Docs](https://learn.microsoft.com/en-us/entra/external-id/)
+- [OAuth 2.0 RFC 6749](https://tools.ietf.org/html/rfc6749)
+- [OpenID Connect Specification](https://openid.net/connect/)
+- [PKCE RFC 7636](https://tools.ietf.org/html/rfc7636)
+- [JWT Debugger](https://jwt.io/)
+
+---
+
+Last Updated: 2026-06-23