I'll explain each point of the multi-app server-side token refresh solution in detail:
1. Global Front Door - Token Refresh Service
Purpose
This creates a secure API endpoint in your authenticating app that other apps can call to refresh tokens.
Key Components:
Security Verification:
const authHeader = req.headers.authorization
if (authHeader !== `Bearer ${process.env.INTER_APP_SECRET}`) {
return res.status(401).json({ error: 'Unauthorized' })
}- Validates that requests come from your trusted main app
- Uses a shared secret (
INTER_APP_SECRET) for inter-app authentication - Prevents unauthorized token refresh attempts
OAuth2 Token Refresh:
const response = await fetch(`${process.env.OAUTH2_TOKEN_URL}`, {
method: 'POST',
headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
body: new URLSearchParams({
grant_type: 'refresh_token',
refresh_token: refreshToken,
client_id: process.env.OAUTH2_CLIENT_ID,
client_secret: process.env.OAUTH2_CLIENT_SECRET,
}),
})- Makes the actual OAuth2 refresh request to your provider (Google, Microsoft, etc.)
- Uses your stored client credentials
- Exchanges the refresh token for a new access token
JWT Generation:
const newJWT = await generateJWT({
access_token: refreshedTokens.access_token,
refresh_token: refreshedTokens.refresh_token || refresh_token,
expires_at: refreshedTokens.expires_at,
user: refreshedTokens.user
})- Creates a new JWT containing the fresh tokens
- Maintains the same structure as your original JWT
- Returns this to the calling app
2. Main App - Server-Side Token Refresh Utility
Purpose
This utility handles token validation and refresh logic within your main application's server-side code.
Key Functions:
Token Expiry Check:
const now = Math.floor(Date.now() / 1000)
const isExpired = decoded.expires_at <= now- Compares current time with token expiration
- Uses Unix timestamps for precision
- Triggers refresh before making API calls with expired tokens
Server-to-Server Communication:
const response = await fetch(`${process.env.AUTH_APP_URL}/api/auth/refresh`, {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Authorization': `Bearer ${process.env.INTER_APP_SECRET}`,
},
body: JSON.stringify({
refresh_token: decodedToken.refresh_token,
access_token: decodedToken.access_token,
}),
})- Calls your global front door's refresh endpoint
- Includes the inter-app secret for authentication
- Sends current tokens for refresh
Cookie Management:
cookieStore.set('auth-token', newJWT, {
httpOnly: true,
secure: process.env.NODE_ENV === 'production',
sameSite: 'lax',
maxAge: 60 * 60 * 24 * 7, // 7 days
path: '/',
})- Updates the browser cookie with the new JWT
- Uses secure settings for production
- Ensures the refreshed token is available for subsequent requests
3. Middleware for Automatic Token Refresh
Purpose
Intercepts all requests to automatically refresh tokens before they reach your pages or API routes.
Key Features:
Proactive Refresh:
const willExpireSoon = decoded.expires_at <= (now + 300) // 5 minutes
if (isExpired || willExpireSoon) {
// Refresh token
}- Refreshes tokens 5 minutes before expiration
- Prevents API calls with expired tokens
- Improves user experience by avoiding auth errors
Request Interception:
export const config = {
matcher: [
'/((?!api/health|_next/static|_next/image|favicon.ico).*)',
],
}- Runs on all routes except static files and health checks
- Processes every user request through your app
- Excludes Next.js internal routes
Transparent Updates:
const response = NextResponse.next()
response.cookies.set('auth-token', refreshedTokens.jwt, {
// cookie options
})
return response- Updates the cookie in the response
- User doesn't notice the token refresh
- Request continues normally with fresh tokens
4. Server Components Implementation
Purpose
Shows how to use the refresh utility in Next.js App Router server components.
Key Concepts:
Server-Side Session Access:
const session = await getServerSession()- Runs on the server during page rendering
- Automatically handles token refresh if needed
- Returns fresh session data for the component
Error Handling:
if (!session) {
redirect(`${process.env.AUTH_APP_URL}/login`)
}
if (session.error) {
redirect(`${process.env.AUTH_APP_URL}/login?error=token_refresh_failed`)
}- Redirects to login if no session exists
- Handles refresh failures gracefully
- Provides error context to the auth app
API Calls with Fresh Tokens:
const response = await fetch(`${process.env.API_BASE_URL}/user`, {
headers: {
'Authorization': `Bearer ${session.access_token}`,
},
})- Uses the refreshed access token for API calls
- Ensures API requests don't fail due to expired tokens
- Works seamlessly in server components
5. API Routes with Token Refresh
Purpose
Demonstrates how to handle authentication in your app's API routes.
Key Features:
Route Protection:
const session = await getServerSession()
if (!session || session.error) {
return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
}- Validates session before processing the request
- Returns 401 if authentication fails
- Prevents unauthorized access to protected endpoints
Downstream API Calls:
const response = await fetch(`${process.env.API_BASE_URL}/data`, {
headers: {
'Authorization': `Bearer ${session.access_token}`,
},
})- Uses fresh access tokens for external API calls
- Maintains authentication chain through your system
- Handles token refresh transparently
6. Environment Variables
Purpose
Configuration that connects your apps and external services.
Main App Variables:
AUTH_APP_URL: URL of your global front door appINTER_APP_SECRET: Shared secret for secure inter-app communicationJWT_SECRET: Secret for JWT verificationAPI_BASE_URL: Your backend API endpoints
Global Front Door Variables:
OAUTH2_CLIENT_ID/SECRET: OAuth2 provider credentialsOAUTH2_TOKEN_URL: Provider's token refresh endpointINTER_APP_SECRET: Same shared secret as main app
How It All Works Together
Request Flow:
- User Request → Middleware checks token expiry
- If Expired → Middleware calls Global Front Door refresh API
- Global Front Door → Calls OAuth2 provider to refresh tokens
- New JWT → Returned to Main App and set in cookie
- Request Continues → With fresh tokens to server component/API route
- Server Component → Uses fresh tokens for any API calls
Benefits:
- Seamless UX: Users never see authentication errors
- Security: Tokens are always fresh, reducing security risks
- Scalability: Can support multiple apps using the same auth service
- Maintainability: Auth logic centralized in one place
- Performance: Proactive refresh prevents failed API calls
This architecture ensures your server-side rendered pages and API routes always have valid tokens, while keeping your authentication logic centralized and secure.
NextAuth CLIENT_FETCH_ERROR Analysis
The error you're encountering indicates that NextAuth is receiving a non-JSON response when it expects JSON. The base64 string "Rm9yYmlkZGVuCg==" decodes to "Forbidden", which suggests your authentication endpoint is returning a 403 Forbidden response.
Root Cause Analysis
In your multi-app architecture, this error typically occurs when:
- CORS Issues: Your main app can't access the global front door's auth endpoints
- Incorrect NEXTAUTH_URL: NextAuth is trying to fetch from the wrong URL
- Missing Authentication: The inter-app communication is being blocked
- Proxy/Load Balancer Issues: Something is intercepting the requests
Solution for Multi-App Architecture
Since you have a global front door handling authentication and routing to another app, you need to configure NextAuth properly:
Alternative Approach: Custom Session Provider
If NextAuth continues to cause issues with your multi-app setup, consider a custom session provider:
Key Fixes for Your Error:
- Proper CORS Configuration: Ensure your global front door allows requests from your main app
- Correct NEXTAUTH_URL: Set it to your main app's URL, not the global front door
- Custom Fetch Function: Handle non-JSON responses gracefully
- Inter-app Authentication: Add proper headers for secure communication
- Error Handling: Catch and handle 403 Forbidden responses
The "Rm9yYmlkZGVuCg==" (Forbidden) error suggests your main app is being blocked when trying to access the authentication endpoints. Make sure your global front door is configured to accept requests from your main app's domain.
To configure the generation, complete these steps: