@commercetools-backend/express

@commercetools-backend/express

Zero-config HTTP server as Express.js to facilitate development.

This package is primarily built for HTTP servers used by Custom Applications and it provides a set of components to facilitate the development of the HTTP server.

Install

$ npm install --save @commercetools-backend/express

Session middleware

This Express.js middleware should be used to handle the authentication exchange between the server and the /proxy/forward-to endpoint of the Merchant Center API Gateway.

You can read more about the "Proxy to External API" concepts here.

const {
  createSessionMiddleware,
  CLOUD_IDENTIFIERS,
} = require('@commercetools-backend/express');

app.use(
  createSessionMiddleware({
    audience: 'https://my-api-server.com',
    issuer: CLOUD_IDENTIFIERS.GCP_EU,
  })
);
app.use((request, response, next) => {
  // `request.session` contains the useful information
});

Middleware options

• audience (string): The public-facing URL of your API server. The value should only contain the origin URL (protocol, hostname, port), the request path is inferred from the incoming request.

• issuer (string): Either a cloud identifier or a valid URL to the Merchant Center API Gateway. The cloud identifier maps to the Merchant Center API URL of the related cloud region.

  • gcp-au: https://mc-api.australia-southeast1.gcp.commercetools.com
  • gcp-eu: https://mc-api.europe-west1.gcp.commercetools.com
  • gcp-us: https://mc-api.us-central1.gcp.commercetools.com
  • aws-fra: https://mc-api.eu-central-1.aws.commercetools.com
  • aws-ohio: https://mc-api.us-east-2.aws.commercetools.com

• inferIssuer (boolean): Determines whether the issuer should be inferred from the custom request HTTP header x-mc-api-cloud-identifier which is sent by the Merchant Center API Gateway when forwarding the request. This might be useful in case the server is used in multiple regions.

• jwks (object): See options of jwks-rsa.

Usage in Serverless Functions

If your HTTP server runs as a Serverless Function, the Express.js middleware should not be needed. Instead you can use the underlying function that does not require the next callback.

Example for Google Cloud Functions

const {
  createSessionAuthVerifier,
  CLOUD_IDENTIFIERS,
} = require('@commercetools-backend/express');

const sessionAuthVerifier = createSessionAuthVerifier({
  audience: 'https://my-api-server.com',
  issuer: CLOUD_IDENTIFIERS.GCP_EU,
});

exports.handler = async function (request, response) {
  try {
    await sessionAuthVerifier(request, response);
  } catch (error) {
    response.status(401).send(JSON.stringify({ message: 'Unauthorized' }));
    return;
  }

  // `request.session` contains the useful information
};

The same concept applies for serverless functions in other cloud providers.