Introduction

The Customer Login API enables single sign-on (SSO). It allows your apps to programmatically log in a storefront customer by using the login entry point URL: /login/token/{token}. Here, {token} must be a JSON Web Token (JWT) containing the parameters for the customer login request, signed by your application’s Oauth client secret.

Example use cases for the Customer Login API include:

  • Integration with a SSO provider or IdP
  • Continuous login between a BC storefront and another system, such as a WordPress blog
  • Any login method other than BC’s typical email and password login - for example, if you wanted to enable customers to log in via a phone number and SMS password

JWT

JWT is a standard for verifying a login signature between two parties. For a full overview of the JWT standard, please see JWT.IO, where you can find links to client libraries (in many languages) that facilitate the generation and verification of JWT tokens. BigCommerce also supplies helper methods for generating login tokens in our API Client Libraries.

JWT Standard

A valid JWT token is a string composed of three parts, separated by periods (“.”), which correspond to the encoded header, the encoded payload, and the signature.

Example JWT Token
Example JWT Token
Key
Key

Header

The header specifies the type of token (JWT) and the hashing algorithm.

{
	"typ": "JWT",
	"alg": "HS256" 
}

The type and algorithm are always JWT and HS256. Those are the only values BigCommerce supports.

Payload

The payload contains a series of claims that identify the application requesting the login, the store, and the customer to be logged in. Optionally, you can specify a redirect URL to direct the customer to a page other than the My Account page after login.

Once a request has is made with a given jti, it cannot be made again. This parameter is used to prevent replay attacks by malicious actors intercepting the request or obtaining it after the fact.

The request_ip field can be used as an additional security precaution, to prevent a malicious actor from intercepting the request and making it from another browser or system before you do. If you supply this value, BigCommerce checks the incoming request to ensure that it is being made from the stated IP address otherwise the request fails. We strongly encourage setting this IP address value, but doing so is optional, to support those cases where this information is not available.

Example Payload
{
  "iss": "Your app’s Oauth client ID",
  "iat": "timestamp for when the token was issued",
  "jti": "randomly generated string",
  "operation": "customer_login",
  "store_hash": "abc123",
  "customer_id": 1234,
  "redirect_to": "/account.php",
  "request_ip": "111.222.333.444"
}
Field Name Type Description
iss string Indicates the token’s issuer. This is your application’s client ID, which is obtained during application registration in Developer Portal.
iat integer Time when the token was generated. This is a numeric value indicating the number of seconds since the Unix epoch.
jti string Request ID string that must be unique across all requests made by your app. A UUID or other random string would be an appropriate value. Most libraries contain a method for generating a uuid. For testing a UUID generator can be used, but it recommended to use built in libraries.
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, as obtained through the Customer API.
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. If there is not a match, it will be rejected

Signature

The signature is created by signing the header and payload with the hashing algorithm specified in the header (HS256) and your application’s Client Secret.


OAuth Scope

Your OAuth API credentials must include the customers_login scope.


Access URL

After generating the JWT token, your app should immediately redirect the shopper’s browser to the following access point URL to log the customer into their account: /login/token/{token}

Example: https://storedomain.com/login/token/eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9 .eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWV9.TJVA95OrM7E2cBab30RMHrHDcEfxjoYZgeFONFh7HgQ


Logging in a Customer

The following tutorial will walk through creating a login token. We recommend scripting this process since the iat is invalid after 30 seconds. For the purpose of illustration, this tutorial will walk through creating a token manually using the debugger tool at JWT.io, although doing so can be tricky due to time constraints.

Prerequisites: Client ID and Client Secret generated from the store with the scope set to Customers Login.

Create a JWT Token

  1. Run a /GET request against the Customers resource. Choose a customer and make note of the customer_id.
Making a /GET request

If you are unsure how to make a /GET request see our tutorial on making your first request.

  1. Create the payload by filling in the PAYLOAD:DATA on jwt.io
Create the Payload
{
  "iss": "1234r5t6y7u8i9o0p",
  "iat": 1535393113,
  "jti": "20b7c03e-00da-4d29-91bf-2aa06a57575b",
  "operation": "customer_login",
  "store_hash": "{store_hash}",
  "customer_id": 2,
  "redirect_to": "/account.php"
}
JTW.io fields
JTW.io fields
IAT Claim

The iat claim is only good for 30 seconds.

  1. Add your Client Secret in the Verify Signature Section. Replace the text your-256-bit-secret with the Client Secret.
  2. Copy the token from the encoded box and paste at the end of the login/token url.

https://store-url/login/token/generated-jwt-token

Example: https://storedomain.com/login/token/eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9 .eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWV9 .TJVA95OrM7E2cBab30RMHrHDcEfxjoYZgeFONFh7HgQ

  1. Paste the URL into the address bar.

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

Sample Code

Code to generate a valid JWT token for a storefront login request is provided in our API Client Libraries. The list items below link to the repositories maintained by BigCommerce:

Client libraries in many other languages are at JWT.io.

JWT Token Sample Code
Client.php
https://github.com/bigcommerce/bigcommerce-api-php/blob/master/src/Bigcommerce/Api/Client.php#L421
    public static function getCustomerLoginToken($id, $redirectUrl = '', $requestIp = '')
    {
        if (empty(self::$client_secret)) {
            throw new Exception('Cannot sign customer login tokens without a client secret');
        }

        $payload = array(
            'iss' => self::$client_id,
            'iat' => time(),
            'jti' => bin2hex(random_bytes(32)),
            'operation' => 'customer_login',
            'store_hash' => self::$store_hash,
            'customer_id' => $id
        );

        if (!empty($redirectUrl)) {
            $payload['redirect_to'] = $redirectUrl;
        }

        if (!empty($requestIp)) {
            $payload['request_ip'] = $requestIp;
        }

        return JWT::encode($payload, self::$client_secret, 'HS256');
    }

Troubleshooting

  • If the server generating the iat is out of sync, the login token will fail if the timestamp indicates a time in the future or an expired token.

  • The login URL can be visited only once. Once a GET request is run against the link, the token is invalidated.

  • Tokens can be validated or generated for testing purposes using the debugger at https://jwt.io/.

  • Tokens will be valid for a very short timeframe after they are first generated, so tokens should not be generated in advance. Instead, the application should generate the token and then immediately redirect the user’s browser to /login/token/{token}. If you’re seeing issues related to your system time differing from BC’s server time, you can use the /v2/time endpoint as a source of truth.