Manual Hybrid Auth Setup (PWA Kit, SFRA/SiteGenesis)

Use manual setup for PWA Kit (Composable Storefront), SFRA/SiteGenesis, headless storefronts, or any storefront where you provision Managed Runtime (MRT), SLAS, and eCDN yourself.

Storefront Next storefronts can use Storefront Next Automated Setup instead, which provisions MRT and eCDN for you.

Note

Complete the Shared Hybrid Auth Setup (SLAS, session bridging, and Business Manager) before you begin.

Are You Starting Fresh or Coming from an Existing Setup?

Fresh Setup

Set up the storefront and its supporting services from scratch:

Set up Managed Runtime (MRT). Create a project and environment for your headless storefront.
Set up SLAS. Create a SLAS client and add the sfcc.session_bridge scope (see Shared Hybrid Auth Setup, Steps 1–2).
Set up SFRA/SiteGenesis. Deploy your SFRA or SiteGenesis cartridges.
Link Business Manager to MRT. Connect your Business Manager instance to the MRT environment.

Then follow the implementation guide for your architecture:

PWA Kit / Composable Storefront: Configure a Hybrid Storefront with Hybrid Auth (PWA Kit)
Headless storefront: Headless Storefront + SFRA Hybrid Setup

Existing Setup

If MRT, SLAS, and SFRA/SiteGenesis are already in place:

Link Business Manager to MRT. Connect your existing Business Manager instance to the MRT environment, then continue with the instance-type steps below.

For an SFRA/SiteGenesis-only storefront, see SFRA and SiteGenesis Hybrid Setup (Existing Customers).

Set Up by Instance Type

Across all instance types, the Hybrid Auth configuration is the same: enable Hybrid Auth in Business Manager (see Shared Hybrid Auth Setup, Step 4) and set the hybrid environment variables for your Managed Runtime (MRT) or local runtime. Only the routing setup differs by environment. Configure each instance type as follows.

These instance-type steps apply to storefronts that include a headless or Managed Runtime (MRT) app (Storefront Next, PWA Kit, or a custom headless storefront). For an SFRA/SiteGenesis-only storefront, you don’t need MRT environment variables or eCDN routing—the Shared Hybrid Auth Setup is your complete configuration. See SFRA/SiteGenesis Proper + Hybrid Auth.

Note

PIG (Primary Instance Group)

Enable Hybrid Auth in Business Manager.
Enable the hybrid environment variables for MRT.
Configure eCDN routing using the Business Manager UI. See CDN Routing Rules for Hybrid Implementations.

ODS (On-Demand Sandbox)

Enable Hybrid Auth in Business Manager.
Enable the hybrid environment variables for MRT.
Configure eCDN routing using the Business Manager UI. See CDN Routing Rules for Hybrid Implementations.

Localhost (Local Development)

Enable Hybrid Auth in Business Manager for the target sandbox/site.
Enable the hybrid environment variables for the local runtime.
Configure routing with the local hybrid proxy instead of eCDN, which isn’t available locally. For PWA Kit, see Set Up Hybrid Locally for Local Development.

For the per-environment routing deltas and the step-by-step guide for your architecture and instance type, see Hybrid Auth Environments and Routing.

SFRA/SiteGenesis Proper + Hybrid Auth (Session Extension and SLAS Setup)

Use Hybrid Auth on an SFRA or SiteGenesis storefront for SLAS benefits—such as longer sessions and federated login—without a headless runtime.

This guide is for existing SFRA/SiteGenesis customers only. For new (greenfield) implementations, use Storefront Next with Storefront Next Automated Setup, or PWA Kit with Configure a Hybrid Storefront with Hybrid Auth (PWA Kit).

Important

Use this path when maintaining or incrementally modernizing an existing SFRA or SiteGenesis storefront.

For an SFRA/SiteGenesis-only storefront, the Shared Hybrid Auth Setup is the complete instruction set—the steps below are just the SFRA/SiteGenesis-specific sequence and map to those shared steps. You don’t need the other Manual Setup sections (Fresh or Existing Setup Managed Runtime provisioning and the Set Up by Instance Type routing steps) unless you later add a headless runtime.

Scope

Keep existing SFRA/SiteGenesis storefront operational.
Enable Hybrid Auth to replace Plugin SLAS.
Prepare for phased migration to headless storefront components over time.

High-Level Steps

Enable Hybrid Auth in Business Manager for the site. (Shared Hybrid Auth Setup, Step 4)
Configure the SLAS client and session bridging scope. (Shared Hybrid Auth Setup, Steps 1–2)
Remove Plugin SLAS-specific configuration where applicable. (Shared Hybrid Auth Setup, Steps 5–6)
Validate cross-site session extension and token synchronization.
Introduce headless routes gradually using eCDN rules. (Only when adding a headless runtime.)

Steps 1–3 map to the architecture-neutral Shared Hybrid Auth Setup. For the legacy Plugin SLAS phased-rollout approach, see Configure a Hybrid Storefront with Plugin SLAS.

For an SFRA/SiteGenesis-only storefront—using Hybrid Auth for SLAS benefits such as longer sessions and federated login, without a headless runtime—the Shared Hybrid Auth Setup is your complete configuration. No headless runtime configuration or eCDN routing is required. Step 5 applies only when you start moving routes to a headless storefront.

Note

Validate the Setup

After you complete the shared setup, confirm that Hybrid Auth is working on your SFRA/SiteGenesis storefront:

Log in as a registered shopper and confirm the session persists across SFRA/SiteGenesis pages without a re-login prompt.
Confirm session extension: registered and guest sessions persist for the refresh token TTL you configured in Business Manager, rather than expiring at the default storefront session timeout.
If you configured a third-party IDP or Social Login, complete a federated login and confirm the shopper is recognized on SFRA/SiteGenesis pages.
Confirm the SLAS authorization (JWT) and the B2C Commerce session (dwsid) stay synchronized—the shopper isn’t logged out or forced to reauthenticate while browsing.

If you hit issues, see Hybrid Auth Troubleshooting.

Migration Recommendation

Treat this setup as a transitional state. As you modernize, adopt headless storefront components and follow the implementation guide for your target architecture:

Storefront Next: Use Storefront Next in a Hybrid Implementation
PWA Kit / Composable Storefront: Configure a Hybrid Storefront with Hybrid Auth (PWA Kit)

For an intermediate step that keeps cart and checkout on SFRA while moving other routes to a headless runtime, see Headless Storefronts + SFRA/SiteGenesis.

Headless Storefronts + SFRA/SiteGenesis

For transitional architectures where a custom headless storefront and SFRA/SiteGenesis both serve shopper traffic.

When to Use This Path

You are in a phased migration from SFRA/SiteGenesis to a custom headless storefront.
You are not yet ready to move cart/checkout off SFRA/SiteGenesis.

This path is for headless storefronts that you build and host yourself (not Storefront Next or PWA Kit). If you use one of those frameworks, or you’re starting a greenfield implementation, follow its dedicated guide instead:

Storefront Next: Use Storefront Next in a Hybrid Implementation. For a greenfield build, use Storefront Next Automated Setup.
PWA Kit / Composable Storefront: Configure a Hybrid Storefront with Hybrid Auth (PWA Kit).

Supported Scenario

The headless storefront handles top-of-funnel and selected experiences.
SFRA/SiteGenesis continues to serve cart, checkout, or other controller-based flows.
Hybrid Auth synchronizes authentication and session state across both runtimes.

Before You Begin

Complete the Shared Hybrid Auth Setup before configuring your headless storefront. These steps are the same for every architecture and instance type:

Create a SLAS client and add the sfcc.session_bridge scope. See Shared Hybrid Auth Setup, Step 1.
Enable session bridging. See Shared Hybrid Auth Setup, Step 2.
Enable Hybrid Auth in Business Manager. See Shared Hybrid Auth Setup, Step 4.

Step-by-Step Setup

Step 1: Authenticate Shoppers with SLAS

In your headless storefront, use SLAS to obtain shopper access and refresh tokens. Store them as cookies so that they’re shared with SFRA/SiteGenesis when the shopper crosses runtimes.

For the authentication flows and token handling, see the Session Bridging Overview.

Step 2: Respect SLAS Set-Cookie Responses

SLAS session-bridge token responses return cookies—including a dwsid—through the Set-Cookie header. Make sure your headless storefront applies these cookies to the shopper’s browser so that B2C Commerce and SLAS sessions stay linked across SFRA/SiteGenesis and your headless pages.

Step 3: Send the sfdc_dwsid Header on SCAPI Calls

For non-PWA Kit headless storefronts, when the dwsid cookie exists, include the sfdc_dwsid header with the dwsid cookie value on all SCAPI calls. This header keeps the shopper’s B2C Commerce session aligned with SCAPI requests from your headless runtime.

Step 4: Configure Route Ownership Between Headless and SFRA

Decide which paths your headless storefront serves and which stay on SFRA/SiteGenesis: route headless-owned paths to your headless origin, and keep the remaining paths on SFRA/SiteGenesis.

If your headless app runs on Managed Runtime (MRT), apply the split using the per-instance routing in Set Up by Instance Type: eCDN MRT routing rules via the Business Manager UI for PIG and ODS, or the local proxy for localhost.
If your headless app runs on a different origin, use your CDN’s origin-routing equivalent with the same path split.

For the per-environment routing mechanics, see Hybrid Auth Environments and Routing. For ready-to-use split patterns you can adapt, see Canonical Routing Rules.

Step 5: (Optional) Basket Merge and Shopper Context

Review basket handling across runtimes in Hybrid Storefront Basket Guidance.
To carry shopper context (such as source code or geolocation) across runtimes, see Shared Hybrid Auth Setup, Step 7.

Step 6: Validate Cross-Runtime Navigation

Navigate from a headless page to an SFRA/SiteGenesis page (and back) and confirm the shopper stays logged in.
Confirm the session cookies (including dwsid) are shared across both runtimes.
Confirm SCAPI calls from the headless runtime include the sfdc_dwsid header that matches the dwsid cookie value.

If you hit issues, see Hybrid Auth Troubleshooting.

Next Steps

If you added a headless or Managed Runtime (MRT) app, split routes between it and SFRA/SiteGenesis, and review the environment-specific deltas, in Hybrid Auth Environments and Routing.
For an SFRA/SiteGenesis-only storefront (no headless runtime), no eCDN routing is required—the Shared Hybrid Auth Setup is your complete configuration.
If you hit issues, see Hybrid Auth Troubleshooting.

See also: Storefront Next storefronts can use Storefront Next Automated Setup instead. For how Hybrid Auth and its setup paths fit together, see Hybrid Authentication.