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 Embedded Signing Key and the HS256 algorithm.

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

This will use your Embedded Signing 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).

Your Embedded Signing Key is shown on your application's page in the developer portal.

Rotating your signing key

Because we sign tokens and you verify them, a rotation can't take effect immediately without breaking every request until you've deployed the new key. So rotating happens in two steps, and you control both.

In the developer portal, go to Applications, then press Edit on your application. The rotation buttons are at the bottom of that page, next to Reset Secret.

  1. Press Rotate Signing Key. We generate your new signing key and show it in the Next Embedded Signing Key field, but keep signing with your current key - nothing changes for your integration yet, so there's no rush.
  2. Deploy the new key, then come back to the same page and press Complete Rotation. We start signing with it straight away.

There's no deadline on the second step. If you need to back out, press Cancel Rotation and the new key is discarded, leaving your current one in place.

The simplest way to handle it is to accept either key while you roll out, then drop the old one once you've completed the rotation:

const verifyWithEither = (tokenFromRequest, options) => {
    try {
        return verify(tokenFromRequest, process.env.SHOPFRONT_SIGNING_KEY, options);
    } catch(e) {
        return verify(tokenFromRequest, process.env.SHOPFRONT_NEXT_SIGNING_KEY, options);
    }
};

Once you've completed the rotation you can drop the old key.

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 signingKey   = "abcdef";

    return new Promise(res => {
        verify(tokenFromRequest, signingKey, {
            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)