Customer Session Management
As we’ve seen, Catalyst uses a customer access token obtained during customer login to identify that customer’s context when making GraphQL Storefront API queries and mutations.
This is one part of the full picture of managing a customer’s session, which we’ll look at in more detail now.
Auth.js
Auth.js is an open-source solution for managing the common tasks of customer authentication.
BigCommerce is, naturally, the customer authentication provider for Catalyst by default, but Auth.js wraps the simple authentication piece into a reliable system for tracking and managing the customer session.
With the default Catalyst configuration, Auth.js tracks a logged-in customer’s session using a JWT cookie. Important files related to the Auth.js integration include:
- auth/index.ts: This file contains the central configuration and exports key components for other code to interact with. The simple BigCommerce authentication provider is defined here, and the
getSessionCustomerAccessTokenmethod exported here can be used to easily retrieved the logged-in customer’s token. The storefront’s login and logout operations utilize functions exported from this file as well. - app/api/auth/[…nextauth]/route.ts: Exports the API endpoints needed by Auth.js.
- middlewares/with-auth.ts: Invokes Auth.js in all requests to ensure customer session is kept alive.
Session Sync
The GraphQL Storefront API supports syncing a customer’s authenticated session between different front-end applications.
In the default Catalyst experience, this is primarily relevant to the Redirected Checkout process, as customers who have logged in on the Catalyst storefront need to remain logged in when they arrive at BigCommerce checkout.
The createCartRedirectUrls GraphQL mutation used to redirect visitors takes the current customer access token into account, and the tokenized redirect URL handles syncing both cart and authenticated status when the visitor arrives at checkout.
See app/[locale]/(default)/checkout/route.ts for the details of the redirect process.
Single Sign-on
The URL path /login/token/{token} can be used in Catalyst to log in a customer using a specialized token instead of user-provided credentials. This supports single sign-on scenarios, when a customer’s identity has already been authenticated by an outside application.
This process requires a JSON Web Token (JWT) signed by a registered BigCommerce app and containing a payload identifying the customer to be logged in. See Customer Login API in the BigCommerce developer docs for the details of generating a valid JWT.
See these related files for more details on the Catalyst implementation:
- auth/index.ts - The
loginWithCustomerLoginJwtGraphQL mutation used here is responsible for the authentication process. - app/[locale]/(default)/(auth)/login/token/[token]/route.ts - This route handles the request to
/login/token/{token}.
