Configure CORS for AdminUI, OAuth and your applications

About this task

The CORS protocol is designed to prevent accidental data leakage. A client, such as a browser, curl, Postman, Bruno, presents an origin to Domino REST API to gain access to valid responses. Browsers do that automatically when the origin schema, hostname, or port differ from Domino REST API. Command line or developer tools like curl or Bruno don't automatically send the origin header and thus aren't subject to a CORS check. The same applies to server code like NodeJS, Java, or GO.

You can avoid CORS

Domino REST API allows to host your static applications, which doesn't require additional CORS setup besides your host.

Procedure

Assuming the following setup:

• Your Domino REST API host is https://drapi.company.com:8880.
• You have multiple servers hosting static applications: https://sales.company.com and https://***.otherdomain.com (running on different ports).
• For development, you want to allow http://localhost:5438.

CORS mapping uses Java Regular Expressions (Regex).

Use a Regex tool

Regex can be hard to decipher and understand due to their syntax and flexibility. To test if a Regex does what you want, use an online interactive tool for validation. Make sure to pick the Java flavor.

Create a JSON file in keepconfig.d, for example cors.json, that contains one element per regex with the value true. If you need to temporarily disable an entry, you can set it to false. Make sure you understand Domino REST API configuration.

The regex for https://drapi.mycompany.com:8880 is https:\\/\\/.drapi\\.mycompany\.com:8880$

Note

Inside JSON, the \ of Regex gets escaped to \\.

A few pointers

• ^ → beginning of the string
• http → the literal string http
• s? → optional the string s
• \\/ → double escape the string /
• .* → one or more characters of any type
• \\. → double escape the string .
• (?:\\:\\d+)? → double escaped optional colon and port number
• $ → end of string

Expected result

{
  "CORS": {
    "^https?:\\/\\/localhost(?:\\:\\d+)?$": true,
    "^https:\\/\\/.*\\.otherdomain\\.com(?:\\:\\d+)?$": true,
    "^https:\\/\\/drapi.company\\.com\\:8880$": true,
    "^https:\\/\\/sales.company\\.com$": true
  }
}

You need to include your host

The CORS implementation is designed to be restrictive. any HTTP request presenting an origin header will be checked against your configuration and denied if no match can be found. The CORS specification states:

Ultimately, server developers have a lot of freedom in how they handle HTTP responses and these tactics can differ between the response to the CORS-preflight request and the CORS request that follows it.

We decided on the side of caution and fail any request that is not a match for a presented origin header. As a result, you have to include your Domino REST API host in your CORS setup.

Tip

To check Domino REST API settings, see Check Domino REST API settings.

Calling Domino REST API from your browser-based application

You can use the browser's build in Fetch API with a simple function:

const drapiFetch = async (url, method, token, body) => {
  const options = {
    method: method,
    mode: 'cors',
    headers: {
      Authorization: `Bearer ${token}`
    }
  };
  if (body) {
    options.body = JSON.stringify(body);
  }
  const response = await fetch(url, options);
  if (!response.ok) {
    throw new Error('Fetch failed');
  }
  const json = await response.body.json();
  return json;
};

This is just an example, you need to add error handling. To deal with chunked responses, check this out.

Let's connect

We really like to hear from you!

Your opinion matters. Let us know all your:

• questions
• discussions
• ideas
• feedback

Join the OpenNTF Discord channel.