Shopfront Developers

Authenticating Requests from the Shopfront Embedded Bridge

Shopfront's Embedded Bridge allows your application's backend to verify that a request came from an Embedded bridge application through the use of a secure token (similar to a cookie).

You'll still need to authenticate your application through the OAuth 2.0 flow so the user can approve it. This is in addition and allows you to prevent unauthorized use of your backend server. It does not assist with making requests to Shopfront.

Sending Requests

After setting up your application with the Embedded Bridge, obtaining a token is easy. For each request you make, simply call the getToken method on the application instance and send the token somehow in your request (such as through a header).

Tokens should be requested for each request as they only have a short period before they expire.

import { Bridge } from "@shopfront/bridge";

const application = Bridge.createApplication({ /* ... your parameters ... */ });

const sendGetRequest = async (url) => {
    return fetch(url, {
        method: "GET",
        headers: {
            // Integrations built by Shopfront use the X-Shopfront-Token header,
            // but you can use whatever name you'd like
            "any-header": await application.getToken(),
        },
    });
};

Receiving & Decoding Requests

When you receive a request to your server from an embedded application, you should validate it by decoding the token provided.

Shopfront's tokens use the JSON Web Token format for which there are a number of libraries available for common server frameworks.

In order to decode and validate your token, you'll need to pass the token to the decode / verify method of your selected JWT library along with your application's secret key and the HS256 algorithm.

decode(tokenFromRequest, process.env.SHOPFRONT_SECRET_KEY, "HS256");

This will use your application's secret key to verify that the contents of the message are valid and will also allow you to read details provided in the token (see below for the anatomy of a token).

If you don't wish to use a library, you can also manually decode the JWT, we'd suggest reading up on the way JWTs work and are formatted on the JWT.io site.

Validating Tokens

Once you decode the token (or by using the verify method of your JWT library) ensure the following are true:

  • The token hasn't expired (the exp claim) - this should be in the future,
  • The issuer is who you'd expect (the iss claim) - for most applications this should be https://onshopfront.com,
  • You're the intended recipient (the aud claim) - this should match your client ID,
  • The token is for the Vendor you're expecting (using either the sub or the vendor_url claim)

The below examples is a Node.js (JavaScript) example using the jsonwebtoken library. It takes a non-decoded token and which vendor it should expect and returns a promise which will resolve with a boolean whether it is valid or not.

const verifyToken = (tokenFromRequest, expectedVendor) => {
    const shopfrontUrl = "onshopfront.com";
    const clientId     = "123456";
    const clientSecret = "abcdef";

    return new Promise(res => {
        verify(tokenFromRequest, clientSecret, {
            algorithms: ["HS256"],
            issuer    : `https://${shopfrontUrl}`,
            audience  : clientId,
        }, (error, decoded) => {
            if(error) {
                return res(false);
            }

            if(typeof decoded !== "object") {
                return res(false);
            }

            if(decoded.vendor_url !== `https://${expectedVendor}.${shopfrontUrl}`) {
                return res(false);
            }

            res(true);
        });
    });
}

Anatomy of a Token

Authentication tokens from Shopfront contain a small amount of useful fields which are helpful for verifying if a request is legitimately from an application embedded within Shopfront's UI.

Header

The values in the header are always the same:

  • alg: The algorithm used to encode the JWT (always HS256),
  • typ: The type of token this is (always JWT)

Payload

The values in the payload are dynamic and can be different for every request:

  • iss: The place the token was created from (typically https://onshopfront.com),
  • aud: The audience the token is for (this is your application's Client ID),
  • sub: The subject of the token (this is the ID of the vendor),
  • exp: When the token expires (in seconds since the Unix epoch),
  • jti: A unique identifier for the token (note, this does not guarantee a unique request),
  • vendor_url: The base URL for the store that the request was made through (typically https://[vendor].onshopfront.com)
  • token_intention: The intention for this token (always embedded)