Hybrid Auth works across all B2C Commerce environments. The core setup is identical in every environment—only the traffic routing differs. Use this page to find the setup guide for your architecture and instance type, see what changes per environment, and decide which routes each runtime owns.
Setup Guide by Architecture and Environment
Start here. The core Hybrid Auth configuration is the same for every architecture and instance type—only the routing setup differs by environment. Follow the guide for your architecture and instance type:
| Architecture | PIG | ODS | Localhost |
|---|---|---|---|
| Storefront Next | Use Storefront Next in a Hybrid Implementation | Set Up Hybrid on ODS Using eCDN | Set Up Hybrid Proxy Locally |
| PWA Kit / Composable Storefront | Configure a Hybrid Storefront with Hybrid Auth (PWA Kit) | PWA Kit ODS via eCDN | PWA Kit local development |
| Custom headless + SFRA | Headless Storefront + SFRA Hybrid Setup (Step 4) | same (Step 4) | same (Step 4) |
| SFRA/SiteGenesis only | SFRA and SiteGenesis Hybrid Setup (Existing Customers) (Business Manager only; no eCDN unless adding a headless runtime) | same | same |
Configuration by Environment
This table summarizes what differs by instance type, regardless of architecture:
| Environment | Description | Hybrid Auth in Business Manager | Runtime Environment Variables | Routing Setup |
|---|---|---|---|---|
| PIG (Primary Instance Group) | Production, staging, and development instances | Required | Required | eCDN, configured in the Business Manager UI |
| ODS (On-Demand Sandbox) | On-demand sandboxes in the Secondary Instance Group (SIG) | Required | Required | eCDN, configured in the Business Manager UI |
| Localhost (local development) | A headless runtime running locally during development | Required (target sandbox/site) | Required for local runtime | Local proxy-based routing instead of eCDN |
Route Ownership
In a hybrid storefront, decide which requests your headless runtime serves and which stay on SFRA/SiteGenesis. The following principles are conceptual guidance—for concrete, copy-ready rules, use the canonical matrix for your architecture below.
- Route top-of-funnel discovery paths (home, category, product, search) to the headless storefront runtime.
- Route transaction-critical legacy flows (cart, checkout, account) to SFRA/SiteGenesis until they are migrated.
- Keep path ownership explicit and avoid ambiguous overlap between runtimes.
- Validate redirects and cookie/session propagation during each path transition.
Canonical Routing Rules
Use the ready-to-use split configurations in the matrix for your architecture:
- Storefront Next: Hybrid Storefront Routing Matrix — Cloudflare rule expressions,
HYBRID_ROUTING_RULES, andlegacyRoutesexamples, with six ready-to-use split configurations. - PWA Kit / Composable Storefront: Hybrid Storefront Routing Matrix (PWA Kit) — eCDN rule expressions and
app/routes.jsxfiltering, with six ready-to-use split configurations.
To configure eCDN routing rules in the Business Manager UI (PIG and ODS), see CDN Routing Rules for Hybrid Implementations.
Notes
- Do not use localhost proxy settings in production environments.
- Keep SLAS client and site configuration aligned across all environments.
- Validate auth/session sync after every environment change.