Authentication Flow

Plan: B2B Developer

Lesson 18 of 25 · 15 min

Introduction

The abstraction layer provided by the Buyer Portal, as you used in the previous lab, will handle the details of authentication with the B2B or BigCommerce GraphQL Storefront APIs automatically, based on the user’s logged-in state. You will not typically need to worry about obtaining and tracking API tokens in your own code.

However, it is helpful to have a baseline understanding of the API authentication flow, particularly since the Buyer Portal manages multiple tokens (for the B2B GraphQL API and the standard BigCommerce GraphQL Storefront API) as well as syncing Stencil session login.

B2B GraphQL API

B2B GraphQL API queries and mutations are either:

• Anonymous, requiring no authentication token. The login mutation itself is an example of this.
• Authenticated, requiring a Bearer token unique to the user. This describes most queries and mutations.

It’s essential that a logged-in user in the Buyer Portal have a B2B storefront token for use with this API. The most straightforward way to obtain one is with the user’s credentials and the login mutation. As you’ll see below, there are other methods as well.

BigCommerce GraphQL Storefront API

Requests to the standard BigCommerce GraphQL Storefront API include two pieces of information relevant to our discussion:

• Storefront token: This Bearer token is required for all requests. It is not specific to a user but is generated by a BigCommerce API consumer.
• Customer context: The individual user’s context is provided in one of the following ways.
  • Storefront session: Only in client-side, stateful requests, the customer context is derived from the same session cookie that tracks the overall session. This makes this method viable for Stencil storefronts.
  • Customer access token: In server-side, stateless requests, a user-unique token obtained at login provides the context. As a server-side method, this is not used by the Buyer Portal. However, this token can be relevant for obtaining a B2B storefront token. (See below.)

Because of the nature of customer context, the Buyer Portal uses two different approaches for making requests to the GraphQL Storefront API:

Direct Requests

When the storefront is Stencil, most requests are made directly to the storefront domain (via the /graphql endpoint, as standard with this API). The client-side nature of the requests allow the customer context to be provided automatically by the Stencil storefront session, as described above.

In this scenario, the Buyer Portal must track a standard storefront token for such requests, in addition to the B2B token.

Proxied Requests

In a headless storefront, GraphQL Storefront API requests are proxied through a B2B Edition endpoint, which accepts the B2B storefront token and handles the proper authentication and customer context on the backend.

Authentication Flow in Stencil

In Stencil storefronts, the authentication flow must account for:

• Obtaining a B2B storefront token for B2B GraphQL API requests
• Obtaining a standard storefront token for BigCommerce GraphQL Storefront API requests
• Logging the user in via the normal Stencil storefront session

The Buyer Portal presents its own custom login page, which performs these major steps:

1. Credentials are passed to the B2B GraphQL API login mutation.
2. A successful login returns a B2B storefront token and a signed JWT (storefrontLoginToken).
3. The B2B storefront token is set in the session.
4. The Customer Login API endpoint is called, using the storefrontLoginToken, to log the customer into the Stencil session.
5. A side effect in the central App entry point is triggered, calls the B2B storeFrontToken mutation to obtain a standard storefront token, and sets it in the session.

By the end of this process, the user has been logged into the Stencil storefront and has obtained tokens for both APIs.

Rehydrating the B2B Token

If the user’s B2B storefront token is removed from the session or invalidated in any way, but the user is still logged into the Stencil storefront, the Buyer Portal automatically takes care of re-obtaining a token without requiring the user to provide their credentials again.

1. The Current Customer API endpoint is called to obtain a signed JWT verifying the logged-in user’s identity.
2. The B2B authorization mutation is called with the JWT to obtain the B2B token.

Authentication Flow in Headless

When using the Buyer Portal in a headless storefront, there are a couple of possible approaches to authentication:

Built-in Login Page

If your headless storefront presents the Buyer Portal’s built-in login page, the authentication flow will be the same as described for Stencil above. The key difference is that the steps for logging into the storefront session and obtaining a standard storefront token will not be performed, as these are not relevant outside Stencil. (Remember, in a headless storefront GraphQL Storefront API requests are proxied.)

Custom Login Page

Most headless storefronts will utilize their own authentication and session management. In addition, the most common approach to the standard BigCommerce GraphQL Storefront API in headless storefronts is to use server-side, stateful requests with a customer access token for customer context.

In this scenario, these two key steps will provide the necessary B2B storefront token to the Buyer Portal:

• Use the B2B REST Management API to obtain a B2B storefront token using the BigCommerce customer access token.
• Use window.b2b.utils.loginWithB2BStorefrontToken to set the token properly in the session and ensure the Buyer Portal hydrates the user’s session details.

Resources

• Customer Login API
• Current Customer API
• B2B GraphQL Playground