Configure a Hybrid Storefront with Hybrid Auth

With B2C Commerce version 25.3, hybrid authentication (auth) replaces the Plugin SLAS cartridge option.

Hybrid auth is a standalone solution for site implementations that need both Storefront Reference Architecture (SFRA)/SiteGenesis (SG) authorization and Shopper Login and API Access Service (SLAS) authorization. This means you need both a dwsid (SFRA/Site Genesis) and a JSON Web Token (SLAS), and these tokens must be kept in sync. Hybrid auth is an improvement over the Plugin SLAS approach, offering a more efficient and streamlined method.

Hybrid auth improves the performance and stability of hybrid storefronts by moving the feature directly into the B2C Commerce platform.

This guide explains how to configure hybrid auth for a hybrid storefront that’s part SFRA/SiteGenesis and part Composable Storefront.

For more information about hybrid auth, see Hybrid Authentication.

The tasks involved in a hybrid implementation with hybrid auth include:

Complete the steps in Hybrid Authentication.
Configure Hybrid Auth for Composable Storefront (Required).
Use Commerce API CDN Zones to route traffic to Managed Runtime. See CDN APIs for Phased Headless Rollouts (Required).
Get analytics Using Einstein Activities for Phased Headless Rollouts (Optional).

To use hybrid auth, build your site with:

commerce-sdk-react@3.2.0 or later
Progressive Web App (PWA) Kit version 3.9 or later

To configure hybrid auth for a hybrid storefront that’s part SFRA/SiteGenesis and part Composable Storefront, follow these steps that are described in detail in this guide.

Set up Embedded Content Delivery Network (eCDN) Origin Rules.
Create a PWA Kit Retail React App.
Update PWA Kit Routes.
Upgrade @salesforce/commerce-sdk-react.
Remove Plugin SLAS from the Cartridge Path.
Enable/Disable Do Not Track Synchronization.

Configure the embedded content delivery network (eCDN) to send page requests at the top of the funnel to the Composable Storefront: 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 use Commerce API CDN Zones to route traffic to Managed Runtime, follow the steps in CDN APIs for Hybrid Implementations.

For more information about routing traffic to MRT, see:

Do 1 or 2.

Create a Retail React App with SLAS private client configuration
- Create a PWA Kit app by running the following generator command in a terminal window: npx @salesforce/pwa-kit-create-app my-hybrid-storefront
- Select The Retail app using your own Commerce Cloud instance.
- Follow the instructions in the terminal.
- Answer Yes when asked Is your SLAS Client Private?

Alternatively, you can generate a Retail React App with a preset configuration and change the SLAS client ID to your private client once the app is generated.
- Follow the steps in the Quick Start.
- Use a SLAS Private Client.

By default, PWA Kit uses the History API for navigation. When a shopper clicks a link made with a React Router component, it triggers a soft navigation to the component matching the path in the route object defined in app/routes.jsx. To link to a non-PWA Kit page (one powered by SFRA, for example), remove any route matching the URL pathname from app/routes.jsx.

If your PWA Kit project was generated with version 3.x of the Retail React App template using template extensibility, you can override the overrides/app/routes.jsx file to filter out links to non-PWA Kit pages using JavaScript.

We’ve created an example override of the overrides/app/routes.jsx file with all the changes in place to filter out /cart and /checkout routes. Customize the example override code in this public gist to filter out links to non-PWA Kit pages.
Update the PWA catch-all route (/*) in app/routes.jsx. In this example, replace the PWA <PageNotFound /> component with a redirect to the default origin.

If your site uses commerce-sdk-react, upgrade to @salesforce/commerce-sdk-react@3.2.0 or later.

These steps apply only if you previously used Plugin SLAS in your hybrid storefront. If you have a new hybrid storefront and you never used Plugin SLAS before, you can skip these steps.

With the migration to B2C Commerce hybrid auth, PWA Kit no longer uses Plugin SLAS. To remove Plugin SLAS from your hybrid storefront:

Go to Administration > Sites > Manage Sites > Select Site.
Go to the Settings Tab.
Remove Plugin SLAS from the cartridge path.
If you have any code customizations around shopper authentication but not specific to Plugin SLAS, they should continue to work as is.
- If you’ve made any Plugin SLAS-specific customizations, review those customizations. Those changes might not be required or you might need to re-implement the changes in a different cartridge.
- Follow best practices. All your code customizations must be implemented in a separate cartridge instead of directly in the out of the box SFRA cartridge code.
- Make sure that when you switch over to hybrid auth, none of your custom cartridge code invokes session-bridging endpoints. This will cause issues in shopper sessions. Hybrid auth now takes care of shopper sessions for you.

For SFRA-only sites, when hybrid authentication is enabled for the shopper login extension, the DNT value is automatically synchronized to the extended session, ensuring a seamless experience across sessions.

To enable/disable do not track (DNT) synchronization in Business Manager, navigate to Merchant Tools > Select Site > Site Preferences > Hybrid Auth Settings.

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 PWA Kit and the cart page runs on SFRA:

On the home page (PWA Kit), 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 PWA Kit is synchronized with SFRA.
As a result, the SFRA cart page doesn't prompt the shopper for tracking consent again.

If you have customized or plan to customize the default DNT implementation, the default synchronization might not be required nor work as expected. In such cases, you can disable DNT synchronization using a site preference. You can still enable hybrid auth even if DNT synchronization is turned off.

There's a key difference in DNT cookie expiration between SFRA and PWA Kit:

SFRA sets the DNT cookie to expire at the end of the session.
PWA Kit sets the expiration to match the refresh token’s lifespan (for example, 30 days for guest shoppers).

When a shopper moves from a PWA Kit page to an SFRA page, the DNT cookie’s expiration changes from the refresh token’s expiry to a session-based expiry. If the shopper closes the browser, the cookie is deleted. As a result, when the shopper returns, the tracking consent banner is displayed again as expected.