Hybrid Auth is a standalone solution for implementations that need both Storefront Reference Architecture (SFRA) or SiteGenesis authorization and Shopper Login and API Access Service (SLAS) authorization. Hybrid Auth maintains both a dwsid (SFRA or SiteGenesis) and a JSON Web Token (SLAS), keeping these tokens in sync.
Hybrid Auth is designed for various use cases, all of which involve using both SFRA or SiteGenesis and SLAS.
For the architecture-neutral shared setup (SLAS client, session bridging, third-party IDP, Business Manager configuration, and Plugin SLAS removal), see Shared Hybrid Auth Setup. For the PWA Kit and SFRA/SiteGenesis implementation paths, see Hybrid Authentication Overview.
Note
Hybrid Authentication Benefits
Hybrid Auth provides key advantages for implementing storefronts alongside traditional SFRA or SiteGenesis pages.
Platform-Native Data Synchronization
Launch faster with out-of-the-box authentication, ensuring automatic data synchronization between SFRA and Storefront Next pages.
Seamless Shopper Experience
Shoppers can navigate across your hybrid site with no disruption or loss of data. Synchronization is expanded to include Shopper Context session attributes and support for consistent analytics.
Full Support for All Templates
Whether you’re using SiteGenesis or SFRA, we have you covered with a fully supported and productized solution to ease your path to Storefront Next success.
Supported Configurations
B2C Commerce version 25.6 Hybrid Auth support includes:
Storefront Next
SLAS public and private clients
SFRA and SiteGenesis templates
Third-party IDP login with SLAS:
Configure third-party IDP logins by using SLAS, not Business Manager.
Perform all third-party IDP interactions by using SLAS.
SFRA third-party IDP logins are only supported when using SLAS.
Set Up a Hybrid Storefront with Storefront Next
Step 1: Set Up Your Storefront with Hybrid Auth
Before you configure Storefront Next, complete the Shared Hybrid Auth Setup. It covers the architecture-neutral configuration that every hybrid storefront needs:
Set up a SLAS client (public or private) and add the sfcc.session_bridge scope for session bridging. Use the same client ID in Hybrid Auth and in your Storefront Next application. See Shared Hybrid Auth Setup, Steps 1–2.
(Optional) Configure third-party IDP and Social Login with SLAS, not Business Manager. The IDP name in the SLAS Admin configuration is case sensitive and must match the OAuth Provider ID in SFRA/SiteGenesis. See Shared Hybrid Auth Setup, Step 3.
Configure Business Manager: enable the Hybrid Auth toggle, enter your SLAS client ID (select Is Public Client for a public client, or enter the client secret for a private client), and set optional features as needed—Shopper Context, Do-Not-Track Synchronization, HTTPOnly True, guest and registered refresh token TTL overrides, and the cookie domain level. Then enforce HTTPS. See Shared Hybrid Auth Setup, Step 4.
Remove Plugin SLAS from the cartridge path if you previously used it, and review any Plugin SLAS-specific code customizations. Make sure no custom cartridge code calls session bridging endpoints; Hybrid Auth handles session bridging for you. See Shared Hybrid Auth Setup, Step 5.
If you used Storefront Next Automated Setup, the SLAS client is already configured. Skip creating a SLAS client, and just confirm that it includes the sfcc.session_bridge scope. Complete the SLAS client setup only if you set up your storefront manually.
Note
Then configure the Storefront Next-specific routing and application settings:
For Storefront Next: Set up Embedded Content Delivery Network (eCDN) origin rules:
Configure the embedded content delivery network (eCDN) to send page requests at the top of the funnel to the Storefront Next: home page (/), the category listing page (/category), and the product details page (/product). These pages are deployed to a Managed Runtime (MRT) environment running on mystorefront.mobify-storefront.com. When the shopper decides to make a purchase, the eCDN redirects the shopper to the existing SFRA/SG checkout page running on www.mystorefront.com.
To configure eCDN routing rules in the Business Manager UI (recommended), see CDN Routing Rules for Hybrid Implementations. To automate or script rule management instead, use the CDN Zones API documented in the same guide.
Provide these values for new rules:
Rule Name: Any name that helps you identify that this ruleset is for hybrid storefronts. A storefront can have more than one ruleset.
Enable Rule Once Saved: Select this checkbox to immediately apply the ruleset when you click Save.
Hostnames: Click Select Hostnames and select the hostname for your hybrid storefront.
MRT Origin: Your MRT storefront domain, which you can find in Environment Settings in Runtime Admin.
Rule Expression: Your origin ruleset.
For hybrid storefronts with Storefront Next, always include /resource/auth/.* and ^/action/.* paths to your eCDN rule expression to route all requests to server resources and actions to Storefront Next on MRT.
Note
For more information about routing traffic to MRT, see:
For Storefront Next: Update Storefront Next configuration.
This guide assumes that you’ve already set up a Storefront Next application. If you haven’t created a Storefront Next application yet, complete the initial setup before proceeding with hybrid configuration.
Note
To enable hybrid mode in your Storefront Next application, update your config.server.ts file to set hybrid.enabled: true and specify which routes to redirect to SFRA/SiteGenesis using legacyRoutes:
enabled: Set to true to enable hybrid mode. This setting allows your Storefront Next application to coexist with SFRA/SiteGenesis pages.
legacyRoutes: An array of route patterns to redirect to SFRA/SiteGenesis instead of being handled by Storefront Next.
Route parameterization:
The legacyRoutes configuration supports parameterization using React Router syntax:
Exact path matches: /checkout, /cart — Matches only the exact path
Dynamic segments: /checkout/:confirmationId, /product/:id — The :parameter syntax matches any value in that segment
Multiple parameters: /category/:categoryId/item/:itemId — Supports multiple dynamic segments in a single route
Any request matching a pattern in legacyRoutes is redirected to the corresponding SFRA/SiteGenesis page, maintaining the full URL path and query parameters.
Update the configuration directly in config.server.ts or use environment variable overrides for per-environment customization. To override via environment variables:
For more information about configuration options and environment variable overrides, see Project Configuration.
Note
Required Route Patterns
Include these patterns so React Router server endpoints continue to work.
Pattern
Required for
^/resource.*
React Router resource routes
^/action/.*
React Router actions
.*\.data.*
Production parity in shared rule sets
Page Route Patterns (Optional)
Add patterns for Storefront Next pages that your team has already migrated.
Pattern
Route
^/$
Homepage
^/login.*
Login page
^/logout.*
Logout
^/signup.*
Registration
^/reset-password.*
Password reset
^/account.*
Account pages
^/product.*
Product detail pages
^/category.*
Category and PLP pages
^/search.*
Search results
^/social-callback.*
Social login callback
Full Rule Set Example
This example keeps homepage, auth, product, category, search, account, and server endpoints on Storefront Next.
1HYBRID_ROUTING_RULES='(http.request.uri.path matches "^/$" or http.request.uri.path matches "^/reset-password.*" or http.request.uri.path matches "^/signup.*" or http.request.uri.path matches "^/logout.*" or http.request.uri.path matches "^/login.*" or http.request.uri.path matches "^/category.*" or http.request.uri.path matches "^/product.*" or http.request.uri.path matches "^/search.*" or http.request.uri.path matches "^/account.*" or http.request.uri.path matches "^/social-callback.*" or http.request.uri.path matches "^/resource.*" or http.request.uri.path matches "^/action/.*" or http.request.uri.path matches ".*\\.data.*")'
Step 2: Configure Basket Management for Hybrid Auth
Storefront Next implements merging basket on Shopper Login. The B2C Commerce platform provides a default, out-of-the-box implementation for merging baskets. Some customers need further customization and can use the sample implementation in Github GIST, which behaves like the default implementation, making it an ideal starting point for customization.
After a guest shopper logs in as a registered shopper, manage the shopper basket with the dw.order.mergeBasket hook (added in B2C Commerce version 25.10). Invoke this merge hook using either of these options:
With a REST API call for headless storefronts
Within the controller logic for non-headless storefronts
After invoking the hook, verify that the guest shopper’s basket is appropriately combined with the registered shopper’s basket.
Hook Invocation Using REST API
When you use the transferBasket endpoint with the parameter merge=true, the guest basket is transferred and becomes the current basket. The dw.order.mergeBasket hook is then invoked, merging the registered shopper’s basket into the current basket. This API behavior is described in the transferBasket specification.
Hook Invocation With Custom Controller Implementation
To add the basket merge hook into an existing controller, use the Script API to transfer the basket from the guest shopper to the registered shopper by calling BasketMgr.getCurrentBasket(). Personal information, such as payment/address information, is removed from the guest basket, and it becomes the current basket. Invoke the dw.order.mergeBasket hook to process the merge ensuring a seamless and consistent shopper experience. Use BasketMgr.getStoredBasket() to access the registered shopper’s basket, which is deleted when the request ends.
For example: to add the basket merge hook for Account-Login, append the merge handling to the login function. The Github GIST contains a detailed explanation of how to accomplish this, but the following example provides a quick summary of how baskets can be obtained and merged using Script API with the dw.order.mergeBasket hook:
1// the (transferred) basket from the previous guest shopper2var currentBasket = BasketMgr.getCurrentBasket();34// the basket from the registered shopper which was attached before the login (will be deleted when request ends)5var storedBasket = BasketMgr.getStoredBasket();67if(storedBasket && currentBasket){8 dw.system.HookMgr.callHook("dw.order.mergeBasket", "mergeBasket", storedBasket, currentBasket);9}
Step 3: (Optional) Set Shopper Context for Hybrid Auth
For Hybrid Auth, we recommend the use of Shopper Context to drive geolocation-based personalizations for:
Promotions and other experiences based on request.geolocation.* attributes in Customer Groups
Region-specific content based on client IP
To maintain consistency across a hybrid storefront, use the same geolocation for both SCAPI and controller calls:
Call Shopper Context with the clientIp.
Set the evaluateContextWithClientIp query parameter to true. Set &evaluateContextWithClientIp=true for the IP-related context features to work correctly.
Shopper Context Script API You can use the Shopper Context Script API to personalize shopper experiences for hybrid implementations that use SFRA/SiteGenesis pages.
Step 4: (Optional) Enable or Disable Do Not Track Synchronization
To enable or disable DNT synchronization in Business Manager, navigate to Merchant Tools > Select Site > Site Preferences > Hybrid Auth Settings.
SFRA-only sites: The DNT value is automatically synchronized to the extended session, providing a seamless experience across sessions.
SFRA and Storefront Next hybrid implementations: When you enable both Hybrid Auth and DNT synchronization, the tracking consent provided by a shopper on one site is automatically synchronized with the other site. For example, in a hybrid site where the home page runs on Storefront Next and the cart page runs on SFRA:
On the home page (Storefront Next), the shopper is presented with a consent form and provides their tracking preference.
When the shopper navigates to the cart page (SFRA), the DNT value from Storefront Next is synchronized with SFRA.
As a result, the SFRA cart page doesn’t prompt the shopper for tracking consent again.
Tracking consent is enabled by default in Storefront Next. You can manage tracking consent settings in config.server.ts:
j