Customer Login API Tutorial

Introduction

In this tutorial, you will learn how to enable single sign-on for storefront customers using the Customer Login API and JSON Web Tokens.

Overview

Single sign-on (SSO) is an authentication mechanism that enables users to log into multiple software applications using the same set of credentials entered only once. It eliminates the need to maintain multiple passwords, streamlining the process of accessing web applications. For more details, see Single sign-on.

The Customer Login API authenticates users logged into your web application to your BigCommerce store using SSO.

Use cases for the Customer Login API include:

  • Integration with a SSO provider or Identity Provider (IdP)
  • Continuous login between a BigCommerce store and another application
  • Alternative login methods (ex. phone number and SMS password)

Storefront customers are logged in using the access point URL /login/token/{token}. The {token} must be a JSON Web Token (JWT) containing parameters for the customer login request signed by your application’s OAuth Client Secret. For more information on the OAuth protocol, see OAuth.

JWT is an industry standard (RFC 7519) for securely transmitting information between two parties. A JWT is represented as a sequence of base64url-encoded parts separated by dots (.). The parts include header, payload, and signature. For more details, see Introduction to JSON Web Tokens.

Payload Fields Reference

Field Name Type Description
iss string Indicates the token’s issuer. This is your application’s Client ID.
iat integer Time when the token was generated. This is a numeric value indicating the number of seconds since the Unix epoch.
jti string A unique request ID (ex. uuid).
operation string Must contain the string “customer_login”.
store_hash string Store hash identifying the store you are logging into.
customer_id integer ID of the customer you are logging in.
redirect_to string Optional field containing a relative path for the shopper’s destination after login. Will default to /account.php.
request_ip string Optional field containing the expected IP address for the request. If provided, BigCommerce will check that it matches the browser trying to log in.

Prerequisites

To enable SSO using the Customer Login API, you will need the following:

  • A BigCommerce store
  • API Client ID and Client Secret with the OAuth Scope set to Customers Login
  • Node.js installed on your machine if you plan to use JavaScript

If you do not know your Client ID and Client Secret, follow the steps outlined in Creating an API Account to obtain the necessary credentials. Make sure to set your OAuth Scope to Customers Login: login.

Example OAuth Scope

Tutorial

To log a customer into their storefront account using the Customer Login API, your app needs to redirect the customer’s browser to the following access point URL: https://storedomain.com/login/token/{token}.

The {token} parameter is the JWT containing the payload data signed by your app’s OAuth Client Secret.

We recommend writing a script to generate a login token since JTW’s iat (Issued At) claim is only valid for 30 seconds. BigCommerce supplies helper methods for generating login tokens in our API Client Libraries.

The beginning of this tutorial focuses on manually creating a token using the Debugger tool at JWT.io. Then, we will look at how to use a JavaScript function to programmatically generate an access point URL.

Create JWT Using the Debugger

  1. Retrieve a customer_id using the Customers v3 API. Send a GET request to the Get All Customers endpoint, choose a customer, and make note of the customer_id.
{
    "accepts_product_review_abandoned_cart_emails": true,
    "authentication": {
      "force_password_reset": false
    },
    "company": "BigCommerce",
    "customer_group_id": 2,
    "date_created": "2020-02-06T17:46:33Z",
    "date_modified": "2020-02-07T19:58:03Z",
    "email": "customer@email.com",
    "first_name": "Jane",
    "id": 1,
    "last_name": "Doe",
    "notes": "",
    "phone": "",
    "registration_ip_address": "",
    "tax_exempt_category": "D"
}
  1. Go to JWT.io and open the Debugger. Make sure that the JWT alg (algorithm) is set to “HS256” and the typ (token type) is set to “JWT”.

JWT Header

  1. Create a payload by filling in PAYLOAD: DATA on JWT.io.

JWT Payload

  1. Replace “your-256-bit-secret” with your Client Secret.

JWT Signature

  1. Copy the login token from the encoded box and paste it into the access point URL replacing the {token} parameter.
    Example: https://storedomain.com/login/token/eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJ7Y2xpZW50X2lkfSIsImlhdCI6MTUzNTM5MzExMywianRpIjoie3V1aWR9Iiwib3BlcmF0aW9uIjoiY3VzdG9tZXJfbG9naW4iLCJzdG9yZV9oYXNoIjoie3N0b3JlX2hhc2h9IiwiY3VzdG9tZXJfaWQiOjJ9.J-fAtbjRFGdLsT744DhoprFEDqIfVq72HbDzrbFy6Is

  2. Paste the URL into the address bar of your web browser.

If the request was successful, you will be logged in as a customer and directed to /account.php. If it was unsuccessful, a login attempt error message will be displayed and you will be directed to /login.php.

Login Error

For common causes of login failure, see Troubleshooting.

Create JWT Using a JavaScript Function

In this part of the tutorial, we will walk you through creating an access point URL using JavaScript. You will need to have node.js installed on your machine to complete this section.

  1. Create and open a new folder by running the following commands in your terminal:
    mkdir urlGenerator
    cd urlGenerator

  2. Create a new node project with the following command:
    npm init

  3. Install jsonwebtoken and uuid npm packages:
    npm install jsonwebtoken uuid

  4. Open the urlGenerator folder in your code editor of choice and create a new JS file.

  5. Paste the following code in your JS file:

const jwt = require('jsonwebtoken');
const {v4: uuidv4} = require('uuid');
 
function getLoginUrl(customerId, storeHash, storeUrl, clientId, clientSecret) {
   const dateCreated = Math. round((new Date()). getTime() / 1000);
   const  payload = {
       "iss": clientId,
       "iat": dateCreated,
       "jti": uuidv4(),
       "operation": "customer_login",
       "store_hash": storeHash,
       "customer_id": customerId,
   }
   let token = jwt.sign(payload, clientSecret, {algorithm:'HS256'});
   return `${storeUrl}/login/token/${token}`;
};
 
const clientId = “Your client id”;
const clientSecret = “Your client secret”;
const customerId = “You customer id”;
const storeHash = “Your store hash”;
const storeUrl = “Your store url”;
 
const loginUrl = getLoginUrl(customerId, storeHash, storeUrl, clientId, clientSecret);
console.log(loginUrl);
  1. Replace your app and customer-specific values in the variables.

  2. Run the code:
    node youFileName.js
    You should receive a complete access point URL as an output.

  3. Copy the URL and paste it into the address bar of your browser.

If the request was successful, you will be logged in as a customer and directed to /account.php. If it was unsuccessful, a login attempt error message will be displayed and you will be directed to /login.php. For common causes of login failure, see Troubleshooting.

Sample Code

Helper methods for generating login tokens are provided in our API Client Libraries. See the following BigCommerce repositories for language-specific examples:

For client libraries in other languages, see Libraries for Token Signing/Verification.

Logging Out

To log out a customer, set the redirect_to field of the JWT’s payload to /login.php?action=logout.

Troubleshooting

  • If the clock of the server generating the “iat” claim is not synchronized, the timestamp will be out of sync and the request will fail. If your system’s time is different from the BigCommerce server time, you can use the Get System Timestamp endpoint as a source of truth.
  • The access point URL can be visited only once. The token will be invalidated after the GET request is made.
  • Tokens should not be generated in advance. Instead, the app should generate the token and immediately redirect the user’s browser to the access point URL.

Additional Resources