# Configure a Hybrid Storefront with Hybrid Auth (PWA Kit) Starting with B2C Commerce version 25.3, hybrid authentication (Hybrid Auth) replaces Plugin SLAS. Hybrid Auth keeps the SFRA/SiteGenesis session (`dwsid`) and SLAS authorization (JWT) synchronized across a storefront that spans PWA Kit (Composable Storefront) and platform-rendered routes. This guide covers the **PWA Kit / Composable Storefront** implementation path on **PWA Kit v3**. It's the path for new Hybrid Auth implementations—new customers must start on PWA Kit v3. :::note - For the shared, architecture-neutral setup (Business Manager Hybrid Auth settings, SLAS session bridging, Shopper Context, Do-Not-Track synchronization, and basket merge), see [Shared Hybrid Auth Setup](/docs/commerce/b2c-commerce/guide/hybrid-auth-shared-setup.md). - Building a **Storefront Next** hybrid storefront instead? See [Use Storefront Next in a Hybrid Implementation](/docs/commerce/b2c-commerce/guide/sfnext-hybrid.md). - Maintaining an **existing PWA Kit v2.x** project that isn't moving to v3 yet? See [Hybrid Auth Implementation with PWA Kit v2.x](/docs/commerce/b2c-commerce/guide/hybrid-auth-pwa-kit-v2.md). ::: ## Prerequisites Build your PWA Kit site with: - `commerce-sdk-react@4.0.0` or later - Progressive Web App (PWA) Kit version 3.12 or later For details, see [Get Started with Composable Storefront](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/pwa-developer-workflow.md). ## Complete the Shared Hybrid Auth Setup First Before configuring PWA Kit, complete the [Shared Hybrid Auth Setup](/docs/commerce/b2c-commerce/guide/hybrid-auth-shared-setup.md): - Create a SLAS client (public or private) and add the `sfcc.session_bridge` scope. - Enable Hybrid Auth in Business Manager (**Merchant Tools > Select Site > Site Preferences > Hybrid Auth Settings**) using the same SLAS client ID. - (Optional) Enable Shopper Context and Do-Not-Track synchronization. - Remove `plugin_slas` from the cartridge path if you previously used Plugin SLAS. ## Configure PWA Kit for Hybrid Auth After you complete the shared setup, configure your PWA Kit project with the following steps. ### Step 1: Create or Update Your PWA Kit Retail React App Do either of these: - Create a Retail React App with a SLAS public or private client configuration: - Run the generator command in a terminal window: `npx @salesforce/pwa-kit-create-app my-hybrid-storefront`. - Select **The Retail app using your own B2C Commerce instance** and follow the terminal instructions. - Or generate a Retail React App with a preset configuration, then change the SLAS client ID to your public or private client after generation: - Follow the steps in the [Quick Start](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/quick-start.md). - Use a SLAS public or [private client](/docs/commerce/b2c-commerce/guide/use-a-slas-private-client.md). - Make sure the SLAS client used for Hybrid Auth includes the `sfcc.session_bridge` scope. ### Step 2: Enable `hybridAuthEnabled` in the `_app-config` Component In `app/components/_app-config/index.jsx` (or `overrides/app/components/_app-config/index.jsx` if you use [template extensibility](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/template-extensibility.md)), find the `CommerceApiProvider` component and uncomment the `hybridAuthEnabled` prop: ```jsx ``` Do **not** set this prop for hybrid storefronts that still use Plugin SLAS. Enable it only for sites that use Hybrid Auth. ### Step 3: Update PWA Kit Routes By default, PWA Kit uses the [History API](https://developer.mozilla.org/en-US/docs/Web/API/History_API) for navigation. When a shopper clicks a link made with a [React Router](https://reactrouter.com/home) component, it triggers a soft navigation to the component matching the path in `app/routes.jsx`. To link to a non-PWA Kit page (one powered by SFRA, for example), remove any route matching that 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](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/template-extensibility.md), override the `overrides/app/routes.jsx` file to filter out links to non-PWA Kit pages using JavaScript. For an example override that filters out `/cart` and `/checkout`, see this [public gist](https://gist.github.com/shethj/c9d52aa1fe4188c431336438305f8e32). 2. Update the PWA catch-all route (`/*`) in `app/routes.jsx`. In this example, the PWA `` component is replaced with a redirect to the default origin: ```js import {withRouter} from 'react-router-dom' ... { path: '*', component: withRouter((props) => { const {location} = props const urlParams = new URLSearchParams(location.search) useEffect(() => { const newURL = new URL(window.location) if (!urlParams.has('redirected')) { newURL.searchParams.append('redirected', '1') window.location.href = newURL } }, [window.location.href]) if (urlParams.has('redirected')) { return } return null }) } ``` ### Step 4: Handle Cookie Responses in the Client Browser As part of Hybrid Auth, SLAS token calls include the `dwsid` in the `Set-Cookie` response header. Make sure the `Set-Cookie` headers from SLAS API calls are respected and the cookies are set in the browser. :::note If you use the Commerce Cloud React SDK with the Composable Storefront, this cookie handling is done for you with PWA Kit v3.9 and later. If your site uses `commerce-sdk-react`, upgrade to `@salesforce/commerce-sdk-react@4.0.0` or later. ::: ### Step 5: Enable Cookies on Managed Runtime 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](https://runtime.commercecloud.com/). 2. Navigate to your project and environment. 3. Select **Environment Settings**. 4. Scroll to the **Advanced** section and select **Edit**. 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. ### Step 6: Configure eCDN Origin Routing Route top-of-funnel pages (home `/`, category `/category`, product `/product`) to your PWA Kit storefront on Managed Runtime (MRT), and route transactional routes (such as `/cart` and `/checkout`) to SFRA/SiteGenesis. - To configure eCDN routing rules, see [CDN Routing Rules for Hybrid Implementations](/docs/commerce/b2c-commerce/guide/ecdn-rules-for-phased-headless-rollout.md). - To compare route split patterns, see the [Hybrid Storefront Routing Matrix (PWA Kit)](/docs/commerce/b2c-commerce/guide/hybrid-routing-matrix.md). - (Optional) Get analytics with [Einstein Activities for Hybrid Implementations](/docs/commerce/b2c-commerce/guide/einstein-activities-for-phased-headless-rollouts.md). ## Set Up Hybrid on On-Demand Sandbox (ODS) Instances Using eCDN **Applies to: PWA Kit** On-demand sandbox (ODS) instances include an embedded CDN (eCDN), so configure hybrid routing on ODS the same way you do on a Primary Instance Group (PIG) instance—through the eCDN UI in Business Manager—rather than with the local hybrid proxy. This lets you validate hybrid behavior in a deployed environment that mirrors production routing. 1. Deploy your PWA Kit bundle to a Managed Runtime environment connected to the ODS instance. 2. Complete the [shared Hybrid Auth setup](#complete-the-shared-hybrid-auth-setup-first) and the PWA Kit configuration steps above (Steps 1–5). 3. Configure eCDN origin routing rules for the ODS zone using the Business Manager UI. Route top-of-funnel pages (home, category, product, search) to Managed Runtime, and keep transactional routes (such as `/cart` and `/checkout`) on SFRA/SiteGenesis. For the UI steps, see [CDN Routing Rules for Hybrid Implementations](/docs/commerce/b2c-commerce/guide/ecdn-rules-for-phased-headless-rollout.md#configure-routing-rules-in-the-business-manager-ui). 4. Verify routing and cookie/session behavior as described in [Verify Your Hybrid Auth Setup](#verify-your-hybrid-auth-setup). :::note Use eCDN—not the hybrid proxy—on ODS instances. Reserve the hybrid proxy for local development on `localhost`. ::: ## Set Up Hybrid Locally for Local Development **Applies to: PWA Kit** For local development on `localhost`, eCDN isn't available, so use a reverse proxy instead. The PWA Kit **hybrid proxy** feature is available starting in PWA Kit v3.14 in the `pwa-kit-runtime` package. Enable hybrid proxy for **local development only**. On PIG and ODS instances, use eCDN to direct requests to the PWA Kit Composable Storefront or SFRA/SiteGenesis store. Don't enable hybrid proxy on PIG or ODS instances: because hybrid proxy sets `localAllowCookies: true`, it can cause security issues on deployed instances. Follow these steps to enable hybrid proxy locally. 1. Upgrade the `pwa-kit-runtime` package dependency to v3.14.0 or later. 2. Configure the `hybridProxy` value in your Composable Storefront `ssr.js` for a server-side reverse proxy: - `localAllowCookies: true` - `hybridProxy.enabled: true` - `hybridProxy.sfccOrigin: [your SFCC store]` 3. Update `default.js` to configure client-side routing: - Update `app.commerceAPI.parameters` to point to the correct Commerce API SIG instance. - Add `app.enableHybrid: true` so that you can toggle hybrid mode on and off. - Add a proxy config for the `dwrestatic` path: ```text ssrParameters.proxyConfigs: add { host: [your SFCC store], path: 'dwrestatic' } ``` 4. In `app/components/_app-config/index.jsx`, uncomment `hybridAuthEnabled` (see [Step 2](#step-2-enable-hybridauthenabled-in-the-\_app-config-component)). Don't set this flag for hybrid storefronts that still use Plugin SLAS. 5. Update `app/routes.jsx` to exclude routes from PWA Kit so that the matching pages render on SFRA/SiteGenesis. This example removes the `/cart` and `/checkout` routes from the PWA Kit store and uses the catch-all `*` route to trigger server-side rendering of the proxied SFRA/SiteGenesis cart and checkout pages. For reference, see this [public gist](https://gist.github.com/clavery/c0c8689ee852876cfc5b297985c4300e#file-routes-jsx-L116). ```js // Remove SFRA/SiteGenesis routes from PWA Kit const ecomRoutes = ['/cart', '/checkout', '*'] const hybridRoutes = [ ...routes.filter((route) => !ecomRoutes.includes(route.path)), { path: '*', component: withRouter((props) => { const config = getConfig() const {location} = props const urlParams = new URLSearchParams(location.search) const {site} = useMultiSite() const siteId = site && site.id ? site.id : config?.app?.defaultSite if (typeof window !== 'undefined') { useEffect(() => { const newURL = new URL(window.location) if (!urlParams.has('redirected')) { newURL.searchParams.append('redirected', '1') newURL.pathname = `/s/${siteId}/${window.location.pathname .split('/') .slice(2) .join('/')}` window.location.replace(newURL) } }, [window.location.href]) } if (urlParams.has('redirected')) { return } return null }) } ] export default () => { const config = getConfig() // Use these routes only in hybrid mode; otherwise use the defaults. // This is driven by the config and environment variables. const routesToConfigure = config.app.enableHybrid ? hybridRoutes : routes return configureRoutes(routesToConfigure, config, { ignoredRoutes: ['/callback', '*'] }) } ``` For environment-specific differences (PIG, ODS, localhost), see [Hybrid Auth Environments and Routing](/docs/commerce/b2c-commerce/guide/hybrid-auth-environment-matrix.md). ## Verify Your Hybrid Auth Setup 1. Go to your storefront using the vanity domain configured in eCDN. 2. Navigate to a page on SFRA/SiteGenesis. 3. Open browser **Developer Tools** and inspect cookies. Confirm these cookies are set: - `cc-nx-g_{Site_ID}`: Guest refresh token - `dwsid`: B2C Commerce session ID - `usid`: SLAS customer ID - `cc-at_{Site_ID}`: SLAS access token (appears only when the user lands on an SFRA page; not seen when navigating from a PWA Kit page to an SFRA page) 4. Navigate to any PWA Kit page and verify: - `cc-nx-g_{SiteID}` is unchanged. - `dwsid` is unchanged. - `usid_{SiteID}` is unchanged. - `cc-at_{SiteID}` is no longer present, because PWA Kit consumes it and moves the access token to `localStorage`. Confirm the `accesstoken{SiteID}` value in `localStorage` matches the original `cc-at_{SiteID}` cookie. 5. In Developer Tools, switch to the **Network** tab. 6. Add an item to the cart on PWA Kit. 7. Inspect the SCAPI **Add to Cart** request. In **Request Headers**, confirm the `sfdc_dwsid` header is set to the `dwsid` cookie value. This header is required to keep hybrid storefront behavior stable at production scale when traffic is distributed across multiple app servers. If you're not using PWA Kit, set this header from your headless application whenever the `dwsid` cookie is available. :::note You might observe a 302 redirect if a session has expired (while retaining a valid refresh token in the `cc-nx*` or `cc-nx-g*` cookies) or if a refresh token is invalid. This is expected. Make sure your implementation follows these redirects. ::: ## Hybrid Auth Feature Support Matrix The following table compares PWA Kit feature support for Plugin SLAS versus Hybrid Auth. | Feature Name | Supported in PWA Kit w. Plugin SLAS | Supported in PWA Kit w. Hybrid Auth | Notes | | -------------------------------------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | SiteGenesis | N | Y | | | Third Party IDPs and Social Login | N | Y |
  • Third-party IDP: Starting with B2C Commerce version 25.8, hybrid auth supports third-party IDP and Social Login, but you must perform all interactions with a third-party IDP using SLAS. Configure OAuth2 providers in [SLAS Admin](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-identity-providers.md) instead of Business Manager and add a redirect URI in Hybrid Auth Settings.
  • Social Login: Starting with B2C Commerce version 25.8, you must perform all logins using SLAS.
| | Passwordless Login | N | N | Hybrid storefronts don't support passwordless login. See [Implement Passwordless Login](/docs/commerce/b2c-commerce/guide/passwordless-login.md). | | SLAS Private Clients | Y | Y | | | SLAS Public Clients | Y | Y | | | SLAS Trusted System (TSOB) | N | Y | | | Script API "Remember Me" functionality | N | N/A
  • The traditional remember me functionality enhanced with SLAS extended expiry times and is redundant when you migrate to HA.
| | | PWA Kit Version 2.x | Y | Y |
  • To use hybrid auth, you need `salesforce/commerce-sdk-react` *v4.0.0* or later.
  • `salesforce/commerce-sdk-react` *v3.4.0* comes packaged with PWA Kit v2.10.
  • `salesforce/commerce-sdk-react` *v5.1.1* comes packaged with PWA Kit v2.11.
| | PWA Kit Version 3.x | Y | Y |
  • To use hybrid auth, you need `salesforce/commerce-sdk-react` *v4.0.0* or later.
  • `salesforce/commerce-sdk-react` *v3.3.0* comes packaged with PWA Kit 3.10.0.
| | Do Not Track (DNT) | N | Y | You must perform specific steps to enable and synchronize DNT. See [Step 8: Enable or Disable Do-Not-Track Synchronization](/docs/commerce/b2c-commerce/guide/hybrid-auth-shared-setup.md#step-8-optional-enable-or-disable-do-not-track-synchronization). | | Shopper Context | N | Y |
  • Salesforce recommends that you enable Shopper Context for Hybrid Authentication as it is the only way personalization data is made available for APIs. See the [Shopper Context documentation](/docs/commerce/b2c-commerce/guide/shopper-context-api.md).
  • Geolocation-based personalization must be synchronized between Shopper Context and SFRA/SiteGenesis. See [Step 7: Set Shopper Context](/docs/commerce/b2c-commerce/guide/hybrid-auth-shared-setup.md#step-7-optional-set-shopper-context).
  • Note: The Script API for Shopper Context is available for geolocation-based personalization.
| | Controller exclusion | Y | N | In Hybrid Auth, there is no need to exclude any controllers. | | Cookie setting customization | Y, via customization | N/A | In Hybrid Auth, unlike Plugin SLAS, you no longer have access to the cookie object and can no longer override cookie settings. | | Agent/Order On Behalf Of (OOBO) | N | Y | Starting with B2C Commerce version 26.1, Agent/OOBO is supported out of the box in Hybrid Auth with PWA Kit when using the Customer Service Center in Business Manager. If your site uses a third-party cartridge for Agent/OOBO, make sure that you perform testing in a local environment before deploying to your live site. | ## Related Guidance - [Hybrid Authentication Overview](/docs/commerce/b2c-commerce/guide/hybrid-authentication.md) - [Hybrid Storefront Routing Matrix (PWA Kit)](/docs/commerce/b2c-commerce/guide/hybrid-routing-matrix.md) - [Hybrid Auth Implementation with PWA Kit v2.x](/docs/commerce/b2c-commerce/guide/hybrid-auth-pwa-kit-v2.md) - [Hybrid Storefront Basket Guidance](/docs/commerce/b2c-commerce/guide/hybrid-storefront-baskets.md#hybrid-storefront-best-practices-for-working-with-baskets) - [Hybrid Auth Troubleshooting](/docs/commerce/b2c-commerce/guide/hybrid-auth-troubleshooting.md)