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:

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

To use hybrid auth, build your site with:

• [email protected] or later

• Progressive Web App (PWA) Kit version 3.10 or later

The following table compares PWA Kit feature support for Plugin SLAS versus Hybrid Auth.

*Support is planned for a future release.

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.
• Enable Cookies on Managed Runtime.
• 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:

• TLS Certificates
• DNS CNAME
• Configure Your Environment

Do 1 or 2.

1. Create a Retail React App with SLAS public or 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.

or

2. Alternatively, you can generate a Retail React App with a preset configuration and change the SLAS client ID to your public or private client once the app is generated.
   • Follow the steps in the Quick Start.
   • Use a SLAS public or private client.
   • Make sure the SLAS Client used for Hybrid Auth includes the sfcc.session_bridge scope.

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.

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

2. 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/[email protected] or later.

When Hybrid Auth is enabled, SLAS /oauth2/token requests contain a session-bridged dwsid using the Set-Cookie header in the response.

In Managed Runtime, enable cookie passthrough:

1. Log in to Managed Runtime Admin.
2. Navigate to your project and environment.
3. Select Environment Settings.
4. Scroll to the Advanced section and select the Edit button.
5. Enable the switch next to Cookies.
6. Scroll back to the Advanced section and select Update.
7. Wait for your storefront bundle to redeploy.

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

1. Go to Administration > Sites > Manage Sites > Select Site.
2. Go to the Settings Tab.
3. Remove Plugin SLAS from the cartridge path.
4. 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.

We highly recommend testing your hybrid setup in a local environment. To do this, you must set up a reverse proxy because eCDN does not support SIGs and ODS. To set up and test your hybrid site locally on SIG instances, you must use your own reverse-proxy or CDN to split traffic.

We have created a sample Node.js app that can be used to develop and test hybrid deployment shopper flows across PWA Kit and SFRA/SiteGenesis. Setup, configuration, and testing instructions for setting up reverse-proxy are mentioned in the README for the repo.

You can configure your ODS to use an alias's configuration that is similar to your production configuration. This can help to keep your local and production setups identical. For instance by configuring your sandbox such that your hybrid site is available at the / URI ensures that URLs sent by pwa-kit don’t need to be translated to include the site ID. This is usually how a production site is configured.

To enable aliases in Business Manager, follow instructions in this module for Salesforce B2C Commerce Hostname Aliases on Trailhead.

You can configure your PWA Kit routes configuration to prefix all outgoing URLs (for example, those intended for SFRA) to include the /s/SiteID prefix. This ensures that your instance receives controller URLs in a manner normally used on sandboxes without needing to explicitly configure hostname aliases. Note that this may not be appropriate for production configuration so you may want to have a different catch-all route for production vs sandbox deployments.

To configure route prefixes, update the PWA catch-all route (/*) in app/routes.jsx or overrides/app/routes.jsx.

• Use Composable Storefront in a Hybrid Implementation
• Hybrid Authentication
• Hybrid Implementation Guidance
• Configure a Hybrid Storefront with Plugin SLAS
• Protect Privacy with a Tracking Consent Banner
• Get Started with Composable Storefront