CORS

This policy controls how your API handles cross-origin requests.

The Cross-Origin Resource Sharing (CORS) mechanism supports secure cross-domain requests and data transfers. It uses specific HTTP headers to define which origins can access selected resources. This policy enables CORS by adding these headers to grant a client or an application permission to access the allowed resources. A cross-origin HTTP request occurs when a client or an application requests a resource from a different domain, protocol, or port than the one used for the current request.

In IBM API Studio, this policy is identified by the kind CORS.

Note: Parameters for the CORS policy are not provided within the policy. The policy retrieves its configuration from the cors section of the API definition and enforces the rules defined in that section.
CORS rule processing
  • The cors section in the API definition is optional. If you do not specify it or leave it empty, the gateway does not enable CORS handling for the API.
  • To enable CORS, you must define at least one rule.
  • The list of rules can include zero or more allow rules where the action is set to allow, and it can include at most one deny rule, which must appear at the end of the list or be the only rule in the list.
  • When the gateway receives a CORS request, it evaluates the rules in the order they are listed. The gateway applies the first rule that matches the requested origin. If no rule matches, the gateway denies the request. The gateway applies only one rule for each CORS request.
Allow rules
  • An allow rule applies when the requested origin matches an origin in the rule’s originList.
  • If the origin matches, the gateway applies the rule. If it does not match, the gateway evaluates the next rule or denies the request if no rule matches.
Deny rules
  • A deny rule denies the request when the requested origin matches an origin in the rule’s originList.
  • If the origin does not match any origin in the originList, the gateway applies the rule. A deny rule does not continue to another rule.

Here is a sample code for the CORS policy.

kind: CORS
apiVersion: api.ibm.com/v1
metadata:
  name: cors
  namespace: wm_policies
  version: '1.0'
  tags: []
  description: ''
spec:
  rules:
    - action: allow
      originList:
        - https://www.domain.com
        - https://www.test.com
      allowCredentials: true
      allowMethods:
        - GET
      allowHeaders:
        - header1
        - header2
      maxAge: 12323
      exposeHeaders:
        predefined: true
        custom: header3, header4
        backend: true

For the CORS policy kind, configure these specifications:

Type Description
spec This section defines the CORS-related properties you configure for the policy.

You can configure the following properties:

  • action. This field is mandatory. Specifies whether the origins in originList are allowed or denied. Possible values: allow and deny.
  • originList. This field is mandatory. Specifies the origins allowed or denied for cross-origin requests, based on the value of action. Origins can contain the * wildcard, which matches zero or more characters.

    Each origin must specify the protocol and host. You can optionally include the port. For example: https://www.domain.com.

  • allowHeaders. Specifies the list of request headers permitted in cross-origin requests. If you do not specify it, all headers requested by the client are allowed. When specifying multiple headers, separate them with commas.
  • allowMethods. Specifies the list of HTTP methods permitted for cross-origin requests. If you do not specify it, the method requested by the client is allowed. For example: GET.
  • allowCredentials. Specifies whether the response can be shared when the request’s credentials mode is include. This property is a Boolean value and defaults to false.
    • If set to true, the response includes the header Access-Control-Allow-Credentials: true.
    • If set to false or not specified, the header is not included.
  • maxAge. This property accepts an integer value and specifies how long in seconds the browser can cache the preflight result. If not specified, the Access-Control-Max-Age header is not returned, and the browser uses its default value of 5 seconds.
  • exposeHeaders. Specifies the response headers exposed to the calling application. This property includes the following:
    • predefined. Exposes the predefined set of headers supported by the product. This property is a Boolean value and defaults to true.
    • custom. Exposes custom response headers. This property is a string. When specifying multiple headers, separate them with commas. It defaults to an empty string.
    • backend. Exposes the response headers returned from the backend service, excluding restricted headers. This property is a Boolean value and defaults to false.

    If you do not specify exposeHeaders, the behavior defaults to:

    • predefined: true
    • custom:""
    • backend: false