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 allows authenticated access to your external APIs from within your extension frontend app, with the use of Cross-Origin Resource Sharing (CORS) headers and JSON Web Tokens (JWT).

Overview

This is an overview of the steps involved when the platform extension calls your external API, using the secure token system:

1. The platform extension sends a request to the marketplace's public GraphQL endpoint to exchange the Appdirect session id with a secure auth token.

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

3. API validates the auth token by first fetching the public keys, then verifying the token using those keys.

4. If token is valid, the API can continue processing the request. Otherwise, the API can throw error that can be handled by the Platform Extension.

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 only purpose of the JWT token is to authenticate the platform extension with your API server, ensuring that only authenticated users can access the API. This token does not enable the customers to call their marketplace APIs, whereas for that purpose, the platform extension can call marketplace APIs directly.

The token is generated by the extension service and distributed to the customers via a dedicated GraphQL endpoint. Then, it can be fetched by the platform extension and included to the requests to your external API, which 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 other for purposes outside of 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 implement an allowlist of trusted origins, headers, and methods in CORS headers.
• 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.