Docs Rewrite Proposal: Third-Party Login with Next.js Server Actions & HttpOnly Cookies

[mocker12345]

What Medusa version and documentation are you using?

None

Preliminary Checks

• This issue is not a duplicate. Before opening a new issue, please search existing issues: https://github.com/medusajs/medusa/issues

Issue Summary

Problem Description

The current Third-Party Login Guide primarily describes a Client-Side Flow, where the JS SDK is expected to manage the token in client-side storage (e.g., localStorage).

However, in modern Next.js App Router architectures (like the official starter), we often rely on HttpOnly Cookies for security. In this "Server-Side Only" setup:

1. Token Inaccessibility: The client-side SDK cannot access the HttpOnly cookie.
2. Context Disconnect: When using Server Actions, the sdk.auth.refresh() call defaults to looking for cookies in the incoming request. During the initial callback (creation) phase, the new auth state hasn't been written to the client's cookies yet.
3. Result: Developers following the docs end up with a broken flow or have to force a "Double Login" (User logs in -> Account Created -> User must log in again to get the cookie).

Proposed Solution: Single-Step Server-Side Flow

We successfully implemented a seamless flow by handling the refresh entirely on the server within the callback Server Action.

The key is explicitly passing the initialToken (Identity Token) to sdk.auth.refresh via headers, bypassing the need for browser-to-server cookie roundtrips.

Implementation Pattern

In your validateCallback Server Action:

// src/lib/data/customer.ts (Server Action)
import { sdk } from "@lib/config"

export async function validateGoogleCallback(queryParams) {
  // 1. Get Identity Token from Provider
  const initialToken = await sdk.auth.callback("customer", "google", queryParams)

  // 2. Check if this is a New User (simplified logic)
  const decoded = decodeToken(initialToken)
  const isNewUser = !decoded?.actor_id

  if (isNewUser) {
    // 3. Create Customer
    await sdk.store.customer.create({ 
      email: decoded.email, 
      // ... 
    }, {}, { Authorization: `Bearer ${initialToken}` })

    // 4. CRITICAL STEP: Immediate Server-Side Refresh
    // We manually pass the initialToken in headers because cookies aren't set yet.
    // This exchanges the Identity Token for a full Customer Token.
    const refreshedToken = await sdk.auth.refresh({
      Authorization: `Bearer ${initialToken}`
    })

    // 5. Set the valid cookie (HttpOnly) server-side
    await setAuthToken(refreshedToken)
    
    return { success: true } 
  }
  
  // Existing user logic...
}

Recommendation

Please consider adding a section or a "Recipe" for Next.js Server Actions.

Why: This is a critical pattern for secure enterprise implementations using Medusa + Next.js, as it avoids exposing tokens to localStorage while maintaining a frictionless UX (no double login).

How can this issue be resolved?

No response

Are you interested in working on this issue?

• I would like to fix this issue

[shahednasser]

Thanks for opening this issue! We've kept the storefront development guides general to ensure developers can generally follow them and make changes based on the framework of their choice.

However, we could add an example sub-guide for the server actions. I'll look into that.

[mocker12345]

Thanks for the quick response!

I understand the goal of keeping the core docs framework-agnostic.

The main reason I'm advocating for this specific example is that Medusa's own Next.js Starter strictly implements a Server-Side Auth pattern using HttpOnly cookies.

The current guide assumes the SDK is running on the client-side with access to the token (e.g., in localStorage). This directly conflicts with the official starter's architecture because:

1. Token Access: The Client-Side SDK in the starter cannot access the HttpOnly cookie.
2. Flow Usage: Following the current guide leads to a broken state where sdk.auth.refresh() on the client fails.

Since many developers use your Next.js Starter as the foundation, they hit this wall immediately when adding Social Auth. A dedicated "Server Action / HttpOnly Cookie" sub-guide would effectively bridge the gap between the generic documentation and the specific, secure architecture you recommend in the starter.

[shahednasser]

Thank you for the details and I understand where you're coming from! Like I mentioned, I'll look into adding another guide as an example.

[mocker12345]

complement

Retrieve customer data

const { customer: customerData } = await sdk.store.customer.retrieve({}, {
    Authorization: `Bearer ${refreshedToken ? refreshedToken : initialToken}`
  })