Hybrid Authentication

Starting with B2C Commerce version 25.3, hybrid authentication (Hybrid Auth) replaces the Plugin SLAS cartridge option. To take advantage of the improved performance and streamlined workflow, we recommend migrating to Hybrid Auth.

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. This means you need both a dwsid (SFRA/SiteGenesis) and a JSON Web Token (SLAS), and these tokens must be kept in sync.

Hybrid Auth fully replaces Plugin SLAS and improves performance and stability of hybrid storefronts by moving the feature directly into the B2C Commerce platform.

Hybrid Auth is designed for various use cases, all of which involve using both SFRA/SiteGenesis and SLAS.

• Hybrid implementation (partial headless site, which could include PWA Kit or other headless solution): Some parts of your site (like product list pages and product detail pages) are done in a headless application, while the other parts of the site (like cart and checkout) remain in SFRA or SiteGenesis.
  • If you plan to use any headless technology for part of your site (a hybrid setup with SFRA/SiteGenesis), you need Hybrid Auth.
• SFRA/SiteGenesis: You can use Hybrid Auth with an SFRA/SiteGenesis site alone, to take advantage of SLAS features, including longer session durations (up to 90 days) and federated login.

For upgrading a PWA Kit v2.x project to Hybrid Auth, see Hybrid Auth Implementation with PWA Kit v2.x.

This image provides an example hybrid B2C Commerce stack using Hybrid Auth and Composable Storefront. Composable Storefront serves the top of the funnel as a headless implementation and uses SCAPI to communicate with the B2C Commerce instance. An SFRA storefront running cart and checkout communicates directly with the B2C Commerce instance. The SFRA project uses Hybrid Auth to facilitate session bridging between the two infrastructures. A CDN (eCDN or your own stacked CDN) routes traffic to the two infrastructures depending on the shopper's requested path.

Launch faster with out-of-the-box authentication, ensuring automatic data synchronization between SFRA and Composable Storefront pages. You no longer need Plugin SLAS!

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 are using SiteGenesis or SFRA, we have you covered with a fully supported and productized solution to ease your path to Composable Storefront success.

• If you plan to use Hybrid Auth with PWA Kit, make sure your site is built with:

  • commerce-sdk-react@3.3.0 or later
  • Progressive Web App (PWA) Kit version 3.10 or later

  For details, see Get Started with Composable Storefront.

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.
   • Make sure that the Client ID used in Hybrid Auth is the same as the one used in your PWA Kit/headless application.

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

   • If you're using Third-Party or Social Login, you must 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.
         • 
      3. Enable the checkbox for Hybrid Auth Enabled for Site.
      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, enable the Is SLAS Public Client ID checkbox.
         • If your SLAS client ID is a private client, enter your SLAS private client secret.
      5. Enable the Hybrid Auth Shopper Context Enabled for Site checkbox to take advantage of the Shopper Context features with Hybrid Auth.
      6. Enable the Do Not Track Synchronization Enabled for Site checkbox 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 Override TTL for Guest Refresh Token Cookie (cc-nx-g_*) field.
         • For this to be effective, the PWA Kit 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 Override TTL for Registered Refresh Token Cookie (cc-nx_*) field.
         • For this to be effective, the PWA Kit 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, you can skip these step. This step applies 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 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.
      • Make sure 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 Composable Storefront: Handle cookie responses in the client browser:

   • As part of Hybrid Auth, SLAS token calls now include the dwsid in the Set-Cookie response header. Ensure the Set-Cookie headers are respected from SLAS API calls and the cookies are set in the browser.
   • NOTE: If you are using Commerce Cloud React SDK with the Composable Storefront, this cookie handling is done for you with PWA Kit v3.9 and later.

7. For Composable Storefront: 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 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.

     • Make sure you provide these values for new rules:
       • Rule Name: Any name that helps you identify this ruleset is for hybrid storefronts. You can have more than one ruleset for a storefront.
       • 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 more information about routing traffic to MRT, see:

     • TLS Certificates
     • DNS CNAME
     • Configure Your Environment

8. For Composable Storefront: Create a PWA Kit Retail React App:

   • Do either of these steps:

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

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

9. For Composable Storefront: Update PWA Kit Routes:

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

10. For Composable Storefront: Upgrade @salesforce/commerce-sdk-react:

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

11. For Composable Storefront: 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.
      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.

12. For Composable Storefront: Use Commerce API CDN Zones to route traffic to Managed Runtime. See CDN APIs for Phased Headless Rollouts.

13. (Optional) For Composable Storefront: Get analytics using Einstein Activities for Phased Headless Rollouts.

14. Verify your Hybrid Auth setup:

    1. Go to your storefront using the vanity domain configured in eCDN in a browser.
    2. Navigate to a page on SFRA/Sitegenesis.
    3. Open Developer Tools in the browser to inspect cookies. Confirm the following cookies have been 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 (This cookie only shows up when the user lands on an SFRA page. This cookie is not seen when navigating from a PWA Kit page to an SFRA page.)
    4. Navigate to any PWA Kit page. Verify these cookies:
       • cc-nx-g_{SiteID}: Should be the same.
       • dwsid: Should be the same.
       • usid_{SiteID}: Should be the same.
       • cc-at_{SiteID}: You no longer see this cookie as the cookie was consumed by PWA Kit and the access token was moved to localStorage. You can inspect localstorage to confirm the accesstoken{SiteID} value matches what you originally had in the cc-at_{SiteID} cookie.
    5. Now switch over to the Network Tab in your browser’s Developer Tools.
    6. Add an item to the cart on PWA Kit.
    7. Inspect the SCAPI request in the network tab for Add to Cart. This is a critical header required to maintain hybrid stability in production at scale when your traffic might be distributed to multiple appservers.
       1. In the headers section, locate the Request Headers.
       2. If you are using PWA Kit, confirm you see the sfdc_dwsid header set to the dwsid cookie value as seen previously. If you are NOT using PWA Kit, set this from your headless application if the dwsid cookie is available.

We highly recommend testing your hybrid setup in a local environment. To do this, you must set up a reverse proxy because eCDN doesn't 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.

Existing hybrid implementations with Plugin SLAS use SCAPI /mergeBasket API to merge guest and registered shopper baskets. Some customers need further customization and they implement custom code for merging or transferring shopper baskets between guest and registered shopper sessions.

Hybrid Auth decouples basket management and authentication. You must configure basket behavior for Hybrid Auth using either of the following options:

• Transfer a basket

  • Headless: Transfer guest baskets to the registered shopper's basket using the transferBasket endpoint. transferBasket replaces the registered shopper's basket with that of the guest shopper. Any items previously added to the registered shopper's basket are overwritten.
  • SFRA/SiteGenesis: Hybrid Auth continues to use the B2C Commerce Login and internally bridges shopper sessions with a SLAS Session. To trigger basket transfer from a guest to a registered shopper account, your implementation of controller extension must include a call to BasketMgr.getCurrentBasket().

• Merge baskets

  • Headless: Merge the guest shopper basket with the registered shopper's basket using the mergeBasket endpoint. mergeBasket merges basket items for guest and registered shopper baskets based on your merge preferences.

  • SFRA/SiteGenesis: Implement merge basket functionality using existing Script API. The recommended approach is to append the SFRA controllers where a shopper can log in and append the login functionality to then merge baskets as shown in the following example. The call to mergeBaskets() is included in MergeBasketUtil. This is a sample utility script provided as a reference. For details, see the Github GIST code.

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 ensure that both SCAPI and controller calls use the same geolocation and maintain consistency across a hybrid storefront:

• Call Shopper Context with the clientIp.

• Set the evaluateContextWithClientIp query parameter to true. You must 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/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, ensuring a seamless experience across sessions.

SFRA and PWA Kit hybrid implementations (new and existing): 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 does not prompt the shopper for tracking consent again.

SFRA and a non-PWA Kit headless hybrid implementations (new and existing): you can leverage the DNT synchronization implemented in the platform provided that:

• SFRA uses the default DNT implementation. For details, see Consent Tracking in SFRA.
• Your non-PWA Kit headless solution implements DNT similar to PWA Kit. For details, see Default Tracking Consent Implementation.

Important: If you 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.

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 is 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 users).

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 popup/banner is displayed again as expected.

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

*Support is planned for a future release.

• Authorization for Shopper APIs
• SLAS Admin API
• Shopper Context Guides
• Shopper Context API Docs