Mobile Platform as a Service:Cross-origin resource sharing

If your browser console shows a Cross-Origin Request Blocked error when calling mPaaS gateway APIs from a web app, enable CORS on the Mobile Gateway to allow cross-origin requests from your app's origin.

How CORS works

Browsers enforce a same-origin policy that blocks cross-origin requests initiated by scripts. Cross-origin resource sharing (CORS) is a W3C standard that lets servers explicitly allow requests from other origins.

A request is cross-origin if the target URL differs from the page URL in any of the following ways:

• Different domain (for example, from example.com to api.otherservice.com)

• Different subdomain (for example, from app.example.com to api.example.com)

• Different port (for example, from example.com to example.com:8080)

• Different protocol (for example, from https://example.com to http://example.com)

There are two types of CORS requests:

• Simple requests

• Preflight requests: Before sending the actual request, the browser sends a preflight request using the OPTIONS method to confirm the server allows the cross-origin request. The browser sends the actual request only after the server confirms it is allowed.

Simple requests

A request is simple if it meets all of the following conditions:

• The request method is one of the following:

  • HEAD

  • GET

  • POST

• The HTTP request headers contain only the following fields:

  • Cache-Control

  • Content-Language

  • Content-Type

  • Expires

  • Last-Modified

  • Pragma

  • DPR

  • Downlink

  • Save-Data

  • Viewport-Width

  • Width

• The Content-Type header is one of the following values:

  • text/plain

  • multipart/form-data

  • application/x-www-form-urlencoded

Preflight requests

Any request that does not meet the simple request criteria triggers a preflight. The browser sends an OPTIONS request first, including the following headers:

• Origin: The source of the request.

• Access-Control-Request-Method: The HTTP method of the upcoming request, such as POST or GET.

• Access-Control-Request-Headers: The headers the upcoming request will include.

The server responds with its CORS policy:

• Access-Control-Allow-Origin: The origins allowed to make cross-origin requests.

• Access-Control-Allow-Methods: The HTTP methods allowed for cross-origin requests.

• Access-Control-Allow-Headers: The request headers allowed in cross-origin requests.

• Access-Control-Expose-Headers: The response headers the browser can access.

• Access-Control-Max-Age: How long, in seconds, the browser can cache the preflight response.

• Access-Control-Allow-Credentials: Whether the browser can send cookies with the request.

If the preflight passes, the browser sends the actual request.

Configure CORS

The mPaaS Mobile Gateway lets you configure CORS rules per appId and workspaceId combination to control which cross-origin requests to allow.

Enable CORS in the console

Log on to the mPaaS console and complete the following steps:

1. In the navigation pane on the left, choose Backend Service Management > Mobile Gateway.

2. In the navigation pane on the left, choose Mobile Gateway.

3. Choose the Gateway Management tab, and then choose the Feature Switch tab. Configure CORS.

After you enable CORS, all API services for the application in the workspace accept cross-origin requests that match the configured rules. Set the following fields:

• Allowed origins: Access-Control-Allow-Origin. One or more origins, separated by commas. Wildcard (*) is allowed.

• Allowed methods: Access-Control-Allow-Methods. One or more HTTP methods.

• Allowed headers: Access-Control-Allow-Headers. One or more request headers, separated by commas. Wildcard (*) is allowed.

• Exposed headers: Access-Control-Expose-Headers. One or more response headers the browser can access, separated by commas. Wildcard (*) is not allowed.

• Max age: Access-Control-Max-Age. How long, in seconds, the browser caches the preflight response.

• Allow credentials: Access-Control-Allow-Credentials. Whether the browser can send cookies with cross-origin requests.

Send cross-origin requests

Add the X-CORS-${appId}-${workspaceId} header to all cross-origin API requests. When a preflight request reaches the gateway, the gateway parses this header from Access-Control-Request-Headers to retrieve the appId and workspaceId and look up the correct CORS configuration.

A cross-origin gateway request must include the following headers:

• X-CORS-\${AppId}-\${WorkspaceId}: Required. Replace the placeholders with the actual AppId and WorkspaceId.

• Operation-Type

• WorkspaceId

• AppId

• Content-Type

• Version

The following example shows a cross-origin request using jQuery Ajax. All custom headers must also be listed in Allowed headers in your CORS configuration:

$.ajax({
    url: 'http://${mpaasgw_host}/mgw.htm',// Enter the gateway address
    headers: {
      'X-CORS-${appId}-${workspaceId}':'1', // This request header is required
      'Operation-Type':${operationType}, // Enter the operationType
      'AppId':${appId}, // Enter the appId      
      'WorkspaceId':${worksapceId}, // Enter the workspaceId
      'Content-Type':'application/json',
      'Version':'2.0',
    },
    type: 'POST',
    dataType: 'json',
    data: JSON.stringify(reqData),
    success: function(data){}
  });