Use Storefront Next in a Hybrid Implementation

Hybrid Auth is a standalone solution for implementations that need both Storefront Reference Architecture (SFRA)/SiteGenesis authorization and Shopper Login and API Access Service (SLAS) authorization. Hybrid Auth maintains both a dwsid (SFRA/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/SiteGenesis and SLAS.

For local development routing with the Vite hybrid proxy plugin, see Set Up Hybrid Proxy Locally in Secondary Instance Group (SIG) Environments.

Hybrid Auth provides key advantages for implementing storefronts alongside traditional SFRA/SiteGenesis pages.

Launch faster with out-of-the-box authentication, ensuring automatic data synchronization between SFRA and Storefront Next pages.

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.

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.

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.

1. Set up a SLAS client:

   • Hybrid Auth supports both SLAS public and private clients. Create a SLAS client if you don’t already have one. For details, see Authorization for Shopper APIs.

2. Enable session bridging:

   • Update the scope of the SLAS client being used for Hybrid Auth to include sfcc.session_bridge. For details, see Shopper Login and API Service (SLAS) Overview.
   • Use the same Client ID in Hybrid Auth and in your Storefront Next application.

3. (Optional) Starting with B2C Commerce version 25.8, Hybrid Auth supports Third-Party IDP and Social Login. Set up Third-Party Login/Social Login using SLAS.

   • If you’re using Third-Party or Social Login, perform all Third Party IDP interactions with SLAS. To set up a supported IDP:
     1. Create an OAuth client in the IDP’s administration portal.
     2. Use the SLAS Admin API or SLAS Admin UI to configure the IDP for a SLAS tenant. In the SLAS Admin UI, navigate to the Idps tab and then select Add Idp.

        • The IDP name in the SLAS Admin configuration is case sensitive and must match the OAuth Provider ID in SFRA/SiteGenesis.

     3. Add the SFRA/SiteGenesis Login-OAuthReentry redirect URI to the SLAS Client ID created in the first step in the SLAS Admin UI, for example:
        • https://<Site Host Name>/on/demandware.store/Sites-<Site Id>-Site/<locale>/Login-OAuthReentry
     4. Add the SFRA/SiteGenesis Login-OAuthReentry redirect URI in the IDP’s administration portal, for example:
        • https://<Site Host Name>/on/demandware.store/Sites-<Site Id>-Site/<locale>/Login-OAuthReentry<IDPProviderId>

4. Configure Business Manager

   1. In Business Manager, go to Merchant Tools.
      1. Select a site that matches your setup, for example: RefArch/RefArchGlobal/SiteGenesisGlobal.
      2. In the quick-find box, search for “hybrid auth”. Select Hybrid Auth Settings in the filtered results. For B2C Commerce version 25.10, the Business Manager interface has been updated. If you’re using a version earlier than 25.10, the options in the interface are slightly different.
         • 
      3. Enable the Hybrid Auth toggle.
      4. Enter your SLAS client ID, which can be for either a private client or a public client.
         • If your SLAS client ID is a public client, select the Is Public Client checkbox.
         • If your SLAS client ID is a private client, enter your SLAS private client secret.
      5. Enable the Shopper Context toggle to take advantage of the Shopper Context features with Hybrid Auth.
      6. Enable the Do-Not-Track Synchronization toggle to take advantage of DNT sync with Hybrid Auth.
      7. Starting with B2C Commerce version 25.8.1, to change the guest refresh token TTL from the default 30 days to a lesser value, enter a value between 360 and 43200 (6 hours and 30 days in minutes) in the Guest Refresh Token Cookie Override TTL field.
         • For this to be effective, the Storefront Next cookie TTL for guest refresh token must be configured to the same value.
         • Making this change effectively reduces the persistent session time for the guest shopper.
      8. Starting with B2C Commerce version 25.8.1, to change the registered refresh token TTL from the default 90 days to a lesser value, enter a value between 360 and 129600 (6 hours and 90 days in minutes) in the Registered Refresh Token Cookie Override TTL field.
         • For this to be effective, the Storefront Next cookie TTL for the registered refresh token must be configured to the same value.
         • Making this change effectively reduces the persistent session time for the registered shopper.
      9. Click Apply.
   2. In Business Manager, click App Launcher and then select Administration.
      1. In the quick-find box, search for Security.
      2. Select the Access Restriction tab.
      3. Enable the Enforce HTTPS checkbox.
      4. Click Apply.

5. Remove Plugin SLAS from the cartridge path. With the migration to B2C Commerce Hybrid Auth, Plugin SLAS is no longer required.

   Perform the following steps if you have ever used Plugin SLAS. If you’re new to hybrid storefront implementations and are now getting started with Hybrid Auth, skip these steps. This step applies only if you previously used Plugin SLAS in your hybrid storefront. If you have a new hybrid storefront and never used Plugin SLAS before, skip this step.

   1. Click App Launcher and then select Administration > Sites > Manage Sites > Select Site.
   2. Go to the Settings Tab.
   3. Remove plugin_slas from the cartridge path.
   4. For code customizations:
      • If you have shopper authentication code customizations that aren’t specific to Plugin SLAS, they should continue to work as is.
      • If you have customizations that are specific to Plugin SLAS, review those changes, because they might not be required or you might need to re-implement the changes in a different cartridge.
      • Following best practices, implement code customizations in a separate cartridge instead of directly modifying out-of-the-box SFRA cartridge code.
      • Verify that none of your custom cartridge code calls session bridging endpoints, because this can cause problems in shopper sessions. Hybrid Auth handles session bridging for you.

6. 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 compare route split patterns, see Choose a Hybrid Routing Matrix.
   • To use Commerce API CDN Zones to route traffic to Managed Runtime, follow the steps in CDN APIs for Hybrid Implementations.
     • 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.

   • For more information about routing traffic to MRT, see:

     • TLS Certificates
     • DNS CNAME
     • Configure Your Environment

7. 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.

   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:

   Configuration options:

   • 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.

Include these patterns so React Router server endpoints continue to work.

Add patterns for Storefront Next pages that your team has already migrated.

This example keeps homepage, auth, product, category, search, account, and server endpoints on Storefront Next.

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.

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.

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:

For basket best practices in a hybrid implementation, see Hybrid Implementation Guidance.

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.

• For example:

For additional details, see:

• Shopper Context Guides
• Shopper Context API Docs
• Shopper Context Script API You can use the Shopper Context Script API to personalize shopper experiences for hybrid implementations that use SFRA/SiteGenesis pages.

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.