Setting up storefront authentication and session management
Essential runtime integration steps for B2C/B2B storefront developers. Details
resolveContext flow routing, cookie lifecycle behavior, and Phase 1
(JWT) to Phase 2 (cookie) authentication handoffs.
Authenticating the storefront (B2C / B2B)
Storefront authentication uses the Identity 's
resolveContext mutation as the single entry point. On every
request, the Context Proxy or Shell invokes resolveContext using
three possible inputs:
channelId- Always present. Storefront channel identifier (NanoID format).
- cookieValue
- Present after first request. Signed
commerce_user_tokencookie value. jwt- Present after user login. Auth0 JWT for registered user authentication.
Routing Decision Matrix
cookieValue |
jwt |
Action | Description |
|---|---|---|---|
| Absent | Absent | GUEST_CREATED |
Creates a new guest user and corresponding session. |
| Present | Absent | SESSION_VALIDATED /
SESSION_INVALID |
Validates an existing session cookie. |
| Present | Present | CONVERTED |
Converts a guest user to a registered user and merges carts. |
| Absent | Present | DIRECT_LOGIN_REGISTERED |
Executes direct registered user login without a prior guest session. |
Session Token Structure (commerce_user_token)
The session token is a signed, httpOnly cookie with the
following security attributes:
- Format:
<session_token>.<HMAC_signature> - Signing Algorithm: HMAC-SHA256 using
SESSION_SIGNING_SECRET(minimum 32 characters). - Storage Tables: Server-side
session_livenessandsession_contextdatabase tables. - Security Directives: Configured with
httpOnly,Secure, andSameSite=Laxto prevent client-side script access.
ResolveContext Response GraphQL Payload
type ResolveContextPayload {
action: String! # GUEST_CREATED | SESSION_VALIDATED | CONVERTED | ...
accountId: String # Tenant account ID
userId: String # User NanoID
userType: String # guest | b2c | b2b | admin
activeOrgId: String # Primary organization
eligibleOrgIds: [String!] # All org memberships
personaIds: [String!] # Assigned personas
workspaceIds: [String!] # Contract-derived workspace IDs
activeContractId: String # Primary contract
eligibleContractIds: [String!]
segmentIds: [String!] # Customer segment memberships
activeLocale: String # e.g., "en-CA"
activeCurrency: String # e.g., "CAD"
sessionType: String # guest | registered
setCookie: String # Set-Cookie header directive
clearCookie: String # Clear-Cookie header directive for invalid sessions
xContext: String # Base64-encoded X-Context header string
isPreview: Boolean # Preview override indicator
}
Managing token lifecycle and propagation
Authentication transition occurs across two main execution phases:
- Phase 1: Initial Auth (JWT bearer)
- The browser authenticates with Auth0 to receive an
id_token. The shell passesAuthorization: Bearer <id_token>to the gateway, which forwards it to Identity viaresolveContext. The Identity sets thecommerce_user_tokencookie in the response. - Phase 2: Subsequent Requests (httpOnly cookie)
- The browser transmits requests containing the
commerce_user_tokencookie without Bearer headers. The Gateway injects the Base64-encodedx-contextheader along with context identifiers (x-account-id,x-user-id,x-org-id) to downstream subgraphs.
Token Storage Matrix
| Token | Storage Location | Accessible to JavaScript? |
|---|---|---|
Auth0 id_token |
In-memory (_cachedToken) with
localStorage fallback |
Yes (Temporary) |
Auth0 access_token |
Encrypted secure storage | No (Via secureStorage API only) |
Auth0 refresh_token |
Encrypted secure storage | No (Via secureStorage API only) |
commerce_user_token |
httpOnly cookie |
No (Sent automatically by browser) |