Using BigCommerce Customer Identity & Access Management to Authenticate Your APIs

BigCommerce is an excellent ecommerce platform with a robust feature set. But sometimes merchants or app developers need to extend the platform in a way that requires shoppers to invoke an API on some external application. For instance, if I’m developing an app that awards loyalty points to customers for taking some action like inviting friends or buying products, then I may need to expose an API that shoppers may invoke from the BigCommerce storefront. For example, shoppers may need to invoke my API to view their loyalty points balance or redeem their points for some reward. I need to make sure that a shopper is only able to view their own balances or redeem their own points, and I need to make sure that shoppers are not able to view another shopper’s balance or redeem someone else’s points.

To manage access to my API properly, I need to know the identity of the shopper accessing my API. In other words, I need a system for Customer Identity and Access Management (CIAM).

BigCommerce Customer Identity & Access Management

Out of the box, BigCommerce provides CIAM capabilities for managing access to BigCommerce resources. For instance, a shopper must log in to their customer account before they are able to view their order history or make purchases with their store credit balance. But without taking some extra steps, BigCommerce CIAM capabilities aren’t available to my rewards points application.

If your enterprise already manages a CIAM solution to access other systems outside of BigCommerce, then it may be more appropriate to integrate your existing solution with BigCommerce such that customers continue to log in using the existing system. Then that system can generate tokens to authenticate shoppers against BigCommerce using the Customer Login API. That’s a perfectly valid approach for an enterprise that already uses a system like Okta, Auth0, PingIdentity, AWS Cognito, or some other CIAM solution as the system of record for customer identities. And with that approach, I may choose to use the third-party CIAM solution to authenticate shoppers and authorize access to my APIs. But that’s not what this article is about.

If I’m building an application that needs to work on any BigCommerce store, or if BigCommerce is my company’s system of record for customer identities, then I need a way for BigCommerce to tell my API who the customer is. It’s not a good idea to solely rely on the request from the browser to tell my application who the customer is because anyone with a JavaScript console and a little bit of know-how could easily forge the request to pretend to be another user.

I’m not really Shane.

To identify the shopper before exposing any sensitive information, my application should rely on something that the user can’t tamper with. To solve for this, BigCommerce provides the Current Customer API. The Current Customer API generates a JSON web token (JWT) that is signed by a secret shared only by my application and BigCommerce. If the shopper were to try to forge the token, my application could easily tell by validating the signature. For more information on how JWT signing and validation works, check out the JWT documentation: https://jwt.io/introduction

So, before the browser calls my application’s API, it should first retrieve an identity token from BigCommerce. The built-in CIAM features in BigCommerce will ensure that only shoppers that are logged into an account can generate a token, and that the token will identify the shopper accurately. Then, the browser can include that token in requests to my application.

My app knows that I’m Patrick because the identity token says so

The rest of this article will explain…

• … how to retrieve the identity token from BigCommerce
• … when to retrieve it
• … how to use it to authenticate requests to your API
• … and an example AWS API Gateway authorizer

How to Retrieve an Identity Token from the Current Customer API

To retrieve an identity token from the current customer API, you will need:

• a BigCommerce client ID
• a BigCommerce client secret

While the API keys that you can generate from the BigCommerce control panel come with a client ID and secret, they do not work on the Current Customer API. Instead, the client ID and secret need to come from https://devtools.bigcommerce.com.

The DevTools portal is typically where an app developer would go to register their application’s callbacks (for an example, see my article How I Built a Serverless BigCommerce App on AWS), but to use the Current Customer API, all you need are the client ID and secret so you can skip most of the app registration.

To get your BigCommerce client ID and client secret, complete the following steps:

1. Navigate to https://devtools.bigcommerce.com and log in. If you’ve never logged into the devtools portal before, then you will be prompted to authorize the BigCommerce Developer Portal to access your account.
2. Click “Create an App”.
3. Enter any name for your app and click “Create”.
4. Scroll to the bottom of the modal prompting you for information like a name and partner ID, then click “Close”.
5. Click “View Client ID”, then copy and securely store the client ID and client secret.

That’s it! You don’t need to build callback URLs or even install the app on your store to use the client ID and secret with the Current Customer API.

Calling the Current Customer API

Once you have your client ID, then you can use it to make a request from your browser to the Current Customer API. The BigCommerce documentation provides a code snippet using XMLHttpRequest that should play nice with every browser. But for simplicity, you can manually generate a token by using your browser to navigate to the Current Customer API endpoint:

1. Navigate to your (or any) BigCommerce storefront, then log into a customer account.
2. Once you’ve logged in, navigate to
   /customer/current.jwt?app_client_id=<YOUR_APP_CLIENT_ID>

You should see a JWT in the browser:

For this example, you can copy the token and paste it into the debugger on https://jwt.io to read the content. You can even paste your client secret into the Verify Signature section to see the tool validate the token signature.

When to Retrieve an Identity Token

Great, now you can get and decode an identity token! In a real-world implementation, your app obviously can’t rely on shoppers to navigate to the Current Customer API and copy/paste a token. Instead, your app should use JavaScript on the BigCommerce storefront to query the Current Customer API, then include the token in the request to your API.

In most cases, it’s okay to simply request the token each time you need to invoke your app’s API. But if you need to make several authenticated requests to your app in a short time, then you may want to simplify the process by requesting the token just once. The tokens are valid for 15 minutes (i.e. the exp and iat timestamps in the token payload are 15 minutes apart), but be very careful about storing the token for multiple requests. Consider scenarios where a shopper may log out of one account then log into another account, like when the shopper is on a shared computer. To be sure you’re always getting the current customer’s identity in your API request, you don’t want to store the token in a cookie, localStorage, or even in-memory in the browser for any significant period.

Calling Your API

Once the browser has the identity token, it can include the token in requests to your API. Consider sending it as a bearer token in the Authorization header, or another header. Query parameters can also work especially if you can’t otherwise send headers in the request, such as a request to open a WebSocket connection. But, be wary of exposing the shopper’s email address in the token payload as a query parameter if you can avoid it.

Your application must validate the signature on the token before authorizing access to sensitive resources. Fortunately, validating the signature is very easy using the libraries available today. The homepage of https://jwt.io lists libraries for many languages.

Examples

If you use AWS API Gateway to manage your application’s APIs, check out my API Gateway Authorizer that may save you some time building your own API: https://github.com/hatertron3000/bigcommerce-current-customer-jwt-api-gateway-authorizer

I’ve also implemented that authorizer in an AWS SAM application. The application deploys an API Gateway and Lambda functions to authenticate requests from the storefront and write values from requests to Customer Attribute Values in BigCommerce. You can check out the code here: https://github.com/hatertron3000/bc-ciam-demo