# Embedded / Authenticating

# 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.

```javascript
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](https://jwt.io/) 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.

```javascript
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:

```javascript
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](https://jwt.io/introduction).

## 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`](https://github.com/auth0/node-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. 

```javascript
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`)