CORS Plugin

Prerequisites

The @myrmex/cors plugin gives the possibility to easily define CORS configuration for the @myrmex/api-gateway plugin.

Installation

Install the npm module in a Myrmex project:

npm install @myrmex/cors

Then enable the plugin in the myrmex.json file:

{
  "name": "my-app",
  "plugins": [
    "@myrmex/api-gateway",
    "@myrmex/cors"
  ]
}

The plugin does not provide new, commands but it allows to define CORS configuration at various levels in the project.

Principle

The plugin @myrmex/cors aims to simplify the configuration of CORS by consuming simple configuration files and automatically creating OPTIONS http methods for APIs and adding http headers to endpoints.

@myrmex/cors supports the pseudo http method ANY available in API Gateway to define DELETE, GET, HEAD, PATCH, POST and PUT method with a single configuration. @myrmex/cors uses it to apply the configuration correctly but it will not be present in http responses.

Configuration

There are four possible levels of configuration in this order of precedence:

• Global configuration
• API level configuration
• Resource path level configuration
• API resource path level configuration

Global configuration

The global configuration applies by default for all endpoints of all APIs.

Using myrmex show-config, it is possible to see the default values:

{
  "apiGateway": {
    "apisPath": "api-gateway/apis",
    "endpointsPath": "api-gateway/endpoints",
    "modelsPath": "api-gateway/models"
  },
  "cors": {
    "Access-Control-Allow-Methods": "DELETE,GET,HEAD,OPTIONS,PATCH,POST,PUT,ANY",
    "Access-Control-Allow-Headers": "*",
    "Access-Control-Allow-Origin": "*"
  }
}

By default, all methods, all origins and all headers are allowed. This configuration allows to quickly experiment, but it can be overwritten to restrict the access to the maximum. For example, to allow the access to the APIs only for the domain www.example.com, it is possible to set this configuration in the file myrmex.json at the root of the project:

{
  "name": "my-app",
  "plugins": [
    "@myrmex/api-gateway",
    "@myrmex/cors"
  ],
  "config": {
    "cors": {
      "Access-Control-Allow-Origin": "https://www.example.com"
    }
  }
}

There are several ways to set this kind of configuration in Myrmex.

The command myrmex show-config shows the new configuration:

{
  "apiGateway": {
    "apisPath": "api-gateway/apis",
    "endpointsPath": "api-gateway/endpoints",
    "modelsPath": "api-gateway/models"
  },
  "cors": {
    "Access-Control-Allow-Methods": "DELETE,GET,HEAD,OPTIONS,PATCH,POST,PUT,ANY",
    "Access-Control-Allow-Headers": "*",
    "Access-Control-Allow-Origin": "https://www.example.com"
  }
}

API level configuration

To override the global configuration for a specific API, it is possible to use a Myrmex extension to Swagger in the spec.json file of the API. If we want to configure an API that has the identifier back-office to accept request only from https://admin.example.com, we can complete the file /api-gateway/apis/back-office/spec.json like this:

{
  "x-myrmex": {
    "cors": {
      "Access-Control-Allow-Origin": "https://admin.example.com"
    }
  },
  "swagger": "2.0",
  "info": {
    "title": "my-api",
    "description": "An API built with Myrmex"
  },
}

This configuration will apply to all resource paths of the API.

Resource path level configuration

To define a specific configuration for a resource path, it is possible to create to create a cors.json file in the resource path.

To forbid the access to all http methods of the resource path /my/resource/path, we can create a file /api-gateway/endpoints/my/resource/path/cors.json with the following content:

{
  "default": {
    "Access-Control-Allow-Methods": ""
  }
}

API resource path level configuration

The cors.json file at the resource path level accepts API specific configurations. Following the previous example, if we want the API that has the identifier back-office to allow GET and POST request from https://admin.example.com, we can complete the file /api-gateway/endpoints/my/resource/path/cors.json like this:

{
  "default": {
    "Access-Control-Allow-Methods": ""
  },
  "back-office": {
    "Access-Control-Allow-Methods": "GET,POST",
    "Access-Control-Allow-Origin": "https://admin.example.com"
  }
}