Important

This feature is currently in Early Availability (EA) status. For more information, see our product lifecycle phases.

Secure token system

The secure token system lets your extension authenticate to your external APIs using Cross-Origin Resource Sharing (CORS) headers and JSON Web Tokens (JWT).

Overview

When your extension calls your external API with the secure token system, the flow is:

1. The extension sends a request to the marketplace's public GraphQL endpoint to exchange the AppDirect session ID for a secure auth token.

2. The extension sends the request with the auth token to your API.

3. Your API validates the auth token by fetching the public keys and then verifying the token.

4. If the token is valid, the API processes the request. Otherwise, it returns an error that the extension can handle.

There are multiple technologies at play to accomplish this.

Technologies

CORS (Cross-Origin Resource Sharing)

CORS is a security feature that allows cross-origin requests, such as when a web application in one domain (your marketplace) requests resources hosted on another domain (your API server). Since cross-origin requests are disabled by default, CORS needs to be enabled in your API server. This can be done by setting CORS headers on the response:

• Access-Control-Allow-Origin: https://your-marketplace-url - allow cross-origin requests only from one or more marketplaces
• Access-Control-Allow-Credentials: true - allow the browser to include credentials in the request, such as auth token or cookies

You can use a library like cors in Node.js to simplify this.

JWT (JSON Web Token)

The secure token is a JWT that represents the user's session in the marketplace. JWT is a compact, self-contained way to securely transmit information between systems, commonly used for authentication.

JWT Usage

The JWT is used only to authenticate your extension with your API so that only authenticated users can access it. It does not authorize calls to marketplace APIs; for that, the extension calls marketplace APIs directly.

The token is generated by the extension service and provided via a dedicated GraphQL endpoint. The extension fetches it and includes it in requests to your external API. Your API fetches the public keys to validate the token.

The token has a short expiration time to reduce the impact of token theft or misuse.

JWT Structure

A JWT token consists of three parts: header, payload, and signature, separated by period (.) characters. The header and payload are Base64Url encoded JSON strings, while the signature is created by signing the combined header and payload with a secret key.

• Header: Contains metadata about the token, such as the type and signing algorithm.
• Payload: Contains claims about the user, including their identity, marketplace, permissions, and token expiration.
• Signature: Ensures the token's integrity by signing the combined header and payload with a private key.

Example JWT:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

JWT Payload

{
  "sub": "abf32c52-801c-4a40-8da0-82096fe455dd", // USER UUID
  "name": "user@example.com", // EMAIL
  "tenant": "PARTNER_ID", // PARTNER ID
  "iat": 1702416920,
  "exp": 1702417220
}

Asymmetric encryption

Asymmetric encryption allows for secure communication without requiring both parties to share a secret key beforehand. It uses a public key and a private key that are linked, but cannot be derived from each other.

To ensure integrity of the JWT token, it is signed with a private key before sending to the client. When the client sends token to the API, the public key is then used to verify the signature, confirming that it came from a trusted sender, which is the marketplace.

Security considerations

The use of JWT and CORS will help secure the external APIs usage. However, it is essential to consider the following security best practices:

JWT

• Avoid storing the token or using it for anything other than authentication.
• It's best to send JWT through the request header or body. If you must absolutely use cookies, use HTTP-only.
• Log and monitor JWT-related operations, such as validation and expiration.
• If applicable, use Content-Security-Policy security headers.

CORS

• Validate the origin of requests and allowlist trusted origins, headers, and methods in your CORS configuration.
• Ensure that the API server includes the Access-Control-Allow-Credentials header and that the client extension UI includes the withCredentials flag.
• If applicable, explicitly specify the allowed HTTP methods using the Access-Control-Allow-Methods header.
• Validate preflight requests (OPTIONS) before processing actual requests.
• Validate and sanitize the Origin header in incoming requests to help prevent CSRF.