Hybrid Authentication

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

Only existing customers can access some of the links on this page. Visit Salesforce Commerce Cloud GitHub Repositories and Access for information about how to get access to the Commerce Cloud repositories.

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 is an improvement over the Plugin SLAS approach, offering a more efficient and streamlined method.

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.

This section applies to the SFRA/SiteGenesis and non-PWA Kit hybrid implementation use cases listed in the previous section. If your implementation includes PWA Kit, see Set up Hybrid Auth for Composable Storefront.

  1. Set up a SLAS Private Client:

    • As of B2C Commerce v25.3, Hybrid Auth ONLY supports SLAS private clients. Create a SLAS private client if you don’t already have one. If you are currently using plugin SLAS with SLAS public clients, you must implement private clients when adopting hybrid auth.
    • For hybrid storefront implementations, see: Authorization for Shopper APIs.

  2. Configure Business Manager:

    1. Open a support case that asks Salesforce Customer Support to enable the Hybrid Auth feature. Provide the exact tenant_ids for which you want the feature enabled.

      Currently, Hybrid Auth is behind support enablement.

    2. Configure site settings for Hybrid Auth:

      1. After Salesforce Customer Support enables the required feature toggles, you should see a new Hybrid Auth Settings screen in Business Manager (BM).
      2. In Business Manager, go to Merchant Tools > Select Site > Site Preferences > Hybrid Auth Settings, and:
        1. Enable the checkbox for Hybrid Auth Enabled for Site.
        2. Enter your SLAS private client ID, which you previously set up.
        3. Enter your SLAS private client secret.
        4. Enable the Hybrid Auth Shopper Context Enabled for Site checkbox to take advantage of the Shopper Context features with hybrid auth.
        5. Enable the Do Not Track Synchronization Enabled for Site checkbox to take advantage of DNT sync with hybrid auth.
        6. Click Apply.

    3. Remove Plugin SLAS from the cartridge path:

      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.

      With the migration to B2C Commerce Hybrid Auth, use of Plugin SLAS is no longer required.

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

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

  4. Verify your Hybrid Auth setup:

    1. Go to your storefront using the vanity domain configured in eCDN in a browser.
    2. Open Developer Tools in the browser to inspect cookies.
    3. 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 will only show up on an SFRA pages)

This section applies to new and existing hybrid implementation use cases listed in Hybrid Auth Use Cases.

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.

This section applies to new and existing hybrid implementation use cases listed in Hybrid Auth Use Cases.

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 the Shopper Context Guides and Shopper Context API Docs.

You can enable or disable DNT settings for all Hybrid Auth use cases.

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:

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.

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.