Session Bridging Overview

Clients can interact with the B2C Commerce platform using controllers, HTTP APIs, or both. Controllers and APIs use different authentication and authorization (authnz) methods, which means you must “bridge” the different authnz methods in hybrid implementations to keep them in sync for shopper login, logout, and other shopper-related events.

This topic provides an approach for “session bridging” using a hybrid SCAPI/OCAPI and B2C Commerce controller implementation. You can use this approach as a guide when working with PWA Kit or any other headless Backend for Frontend (BFF). For additional session bridging instructions that apply when using a hybrid implementation (SiteGenesis/SFRA and PWA Kit), see Phased Headless Rollouts. In our case, session bridging involves synchronizing a SLAS JWT (for SCAPI) with a session dwsid (for B2C Commerce controllers), or vice versa. At any time, the browser must be able to make a request to either the controller or an API and be recognized as the same shopper.

Note: SLAS tokens can be used with all SCAPI and OCAPI Shopper APIs, but using SCAPI is preferred.

This section outlines the authnz methods for a headless implementation using PWA Kit and Plugin SLAS, providing a guide for other headless implementations. PWA Kit uses SCAPI for authnz, while B2C Commerce controllers use Plugin SLAS. For details, see Plugin SLAS Phased Headless Rollouts.

Make sure you understand the authnz methods of whatever components you include in your headless implementation.

Summary of SCAPI and B2C Commerce controller authnz mechanisms:

You must perform session bridging for various lifecycle events, for example: when a shopper first lands on a storefront, when a shopper subsequently logs in or out, and when tokens or sessions expire.

The call flows that are detailed in the following sections are the flows that PWA Kit and Plugin SLAS use. The purpose of these flows is to obtain a JWT (SLAS access token) and a dwsid (session) that reference the same shopper, so that subsequent requests are in sync, regardless of whether those requests come from an API or a controller.

These flows are for new shoppers who have never before visited your storefront. The series of calls you must make depends on whether a shopper first lands on a headless/PWA site or the B2C Commerce (SFRA) site.

In our case, we are using PWA Kit, but the following guidance applies to any BFF:

1. Get a JWT From SLAS. Depending on whether you’re using a public or private client, the flow varies. If you use a SLAS private client, you only need to call getAccessToken.
   1. Call SLASauthorizeCustomer (oauth2/authorize)
   2. Call SLASgetAccessToken (oauth2/token)
2. You now have a SLAS token, which includes a JWT that you can use to access the APIs, and a refresh token you can use to get a new JWT.
3. Call OCAPI Shop/sessions.
4. You now have a cookie with a dwsid that is associated with your JWT.

With a SLAS access token and a Session ID, you can make requests using either APIs or controllers.

The following image shows the request flow for new shoppers landing on a headless site:

In this flow, the browser makes a request to B2C Commerce, which automatically creates a session and returns a dwsid for any request that meets the following criteria:

• Doesn’t contain a DWSID cookie.
• The session referenced by the cookie is expired or otherwise invalid.

Use Plugin SLAS or manually perform the following steps:

1. Get a JWT From SLAS. Depending on whether you’re using a public or private client, the flow varies. If you use a SLAS private client, you only need the token call, not the authorize call.
   1. Call SLASauthorizeCustomer (oauth2/authorize)
   2. Call SLASgetSessionBridgeAccessToken (oauth2/session-bridge/token)
2. You now have a SLAS token, which includes a JWT that you can use to access the APIs, and a refresh token you can use to get a new JWT.

The following image shows the request flow for new shoppers landing on a B2C Commerce site:

Returning guest and returning registered shopper flows are the same, but the sequence of calls depends on whether the shopper first landed on the headless storefront or B2C Commerce.

1. Use the SLAS refresh token to call SLASgetAccessToken (oauth2/token?refresh_token=...)
2. Call OCAPI Shop/sessions to get new DW cookies for the shopper.
   1. Now you've got both an access token and a session to call APIs or controllers. The returning shopper is now logged in again.

The following image shows the request flow for the returning shopper on the headless site:

If your browser doesn’t have a dwsid in its cookie jar to send, or the dwsid that you send is invalid or expired (maximum session life is six hours), then you will get a new session when the request is made to B2C Commerce and you must perform session bridging.* * Use Plugin SLAS or manually perform the following steps:

1. Use the refresh token to call SLASgetAccessToken (oauth2/token?refresh_token=...)
2. Call OCAPI Shop/sessions to get new DW cookies for the shopper.
3. Reload the page. This forces the page to be rendered using the newly acquired session.

The following image shows the request flow for a returning shopper on B2C Commerce:

If a guest shopper logs in, the sequence of calls you need to make depends on whether the shopper logs in to the headless storefront or B2C Commerce.

If the guest shopper logs in to the headless storefront:

1. Provide the user's credentials to login with oauth2/authorize. At that point, you'll have a JWT for the logged in shopper.
2. Whatever dwsid you currently have references the guest session, which means it is stale.
   1. Call OCAPI Shop/sessions with the logged in JWT to retrieve a dwsid for the logged-in shopper.

If the guest shopper logs in to B2C Commerce (SFRA):

1. Provide the user's credentials to login with oauth2/authorize. At that point, you'll have a JWT for the logged in shopper.
2. Call OCAPI Shop/sessions with the logged in JWT to retrieve a dwsid for the logged-in shopper.
3. Return a redirect to the shopper so the page is re-rendered with the updated session.

When a shopper logs out of your storefront, the sequence of calls you need to make depends on whether the shopper logs out of the headless storefront or B2C Commerce.

If the shopper logs out of the headless storefront:

1. Discard the current JWT and refresh token. You can log the customer out using the loguoutCustomer endpoint.
2. Obtain a new guest JWT usinggetAccessToken.
3. Call OCAPI Shop/sessions.

If the shopper logs out of B2C Commerce (SFRA):

1. The existing session is automatically cleared.
2. However, the JWT still is logged in. Obtain a new guest JWT usinggetAccessToken.

SLAS access tokens are good for 30 minutes from the time they are granted. You can decode the JWT and look at the exp field for the exact timestamp.

After 30 minutes elapses, the token can no longer be used to make an API request. If you make a request with an expired JWT, an error is thrown.

1. Use the refresh token to call SLASgetAccessToken (oauth2/token?grant_type=refresh_token) to get a new token.
   1. Note: Refresh tokens from public clients can only be redeemed once, while refresh tokens from private clients can be used for multiple days.
   2. For prd instances, refresh tokens are good for 90 days. For other instances, refresh tokens are good for nine days. The exact value can be found in TokenResponse's refresh_token_expires_in property.

• When the session expires due to a timeout, the next call to B2C Commerce results in the OnSession hook firing, so this will be the same as the returning visitor scenario.
• Returning Shopper on B2C Commerce (SFRA)