# 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 secret key and the HS256 algorithm.

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