Exemptions and Cross-origin Resource Sharing (CORS)

How to enable exemptions and CORS on a Banyan-secured web service

  • Updated on Jan 08, 2024
  • 10 minutes to read
  • Contributors

This article describes features that are only available in the Banyan Enterprise edition and Banyan Unlimited edition.

Exemptions overview

In some scenarios, you may need to exempt specific URLs or source IPs from Banyan security policies that manage access to a web service. Admins can add access permission exemptions to do this.

Banyan allows you to create exemption rules that target the following network request properties:

  • By Origin Header: Exempt requests originating from a specific URL (e.g.,https://console.website.corp.com:443 )

  • By Target Domain: Exempt requests targeting a specific URL (e.g.,https://public.website.corp.com:443 )

  • By Method: Exempt ORIGIN, HEAD, GET, POST, PUT, and/or DELETE requests

  • By Mandatory Headers: Exempt requests that have specific headers

  • By Paths: Exempt requests targeting specific paths (e.g., /web/public)

  • By Source CIDRs: Exempt requests originating from specific IPs (e.g., from a corporate office)

Configure an exemption

For example, a common scenario arises when Banyan is securing access to a Jenkins Automation Server. Jenkins exposes webhooks at specific paths that third-party applications (such as Github.com) can invoke to trigger a pre-defined build job. Because there is no way to add the Banyan TrustCookie to requests from Github.com, these triggers will, by default, be blocked.

To add an exemption for such requests, complete the following steps:

1. Navigate to the Access Permissions tab on a Hosted Website.

2. Expand the Exemptions section, and select Add Exemption.

3. Add a By Paths rule, and add the path /github-webhook.

4. Optionally, add another rule such as a Source CIDR rule to better limit the scope of the exemption.

5. Save the exemption, and save the updated Hosted Web Service.

Now, Github will be able to send requests to the Jenkins web hook without the request being blocked.

CORS overview

Another common scenario requiring exemptions is related to CORS requests. Cross-Origin Resource Sharing (CORS) allows JavaScript on a web page served on an origin domain to make XML HTTP Requests (XHR a.k.a AJAX) for resources from an external domain, outside of the origin domain.

For example, a web app served on the origin domain, domain-a.com is always allowed to make same-origin requests to resources served on domain-a.com. However, requests to resources on the external domain, domain-b.com are cross-origin.

There are two types of CORS requests:

  • Simple CORS Requests: do not trigger a preflight sequence using the HTTP OPTIONS method.

  • Preflighted CORS Requests: trigger a preflight sequence from the browser to the external domain via the HTTP OPTIONS method. This OPTIONS preflight sequence establishes what methods and headers are supported by the external domain.

Most modern CORS scenarios are Preflighted and involve a preflight sequence via the HTTP OPTIONS method. Furthermore, by default, browsers do NOT send HTTP Cookies and HTTP Authentication headers when making CORS requests. Most modern CORS scenarios use the Requests With Credentials capability to enhance the security of CORS via authentication.

To enable the Requests With Credentials capability, two conditions must be met:

  1. The CORS server at the external domain must be configured to allow credentials via the Access-Control-Allow-Credentials header.

  2. The web application at the origin domain must make XHR CORS requests with the withCredentials property set.

The Access-Control-Allow-Credentials header works in conjunction with the XMLHttpRequest.withCredentials property so CORS requests can use credentials such as cookies, authorization headers, and TLS client certificates.

Configuring an exemption for a CORS request

Different exemptions may need to be set up to handle CORS requests depending on the type of request and the origin/destination of the request. For example, because the HTTP OPTION preflight requests never use HTTP Cookies and HTTP Authentication headers, they would be -by default- blocked by Banyan.

1. Requests without Credentials or Requests without the Banyan TrustCookie

In situations where CORS is used without credentials, or requests from an origin that does not have access to the Banyan TrustCookie (such as single-domain services), a least-privileged exemption should be set up to allow access to the CORS request while being careful not to create too broad of an exemption.

For example, say that we know that the request will always originate from domain-b.com, only targets two specific endpoints at /api/endpoint1 and /api/endpoint2 with GET and POST requests, we can set up an exemption as follows:

1.1 Navigate to the Access Permissions tab on a Hosted Website.

1.2 Expand the Exemptions section, and select Add Exemption.

1.3 Add a By Origin Header rule, and add the origin https://domain-b.com:443.

1.4 Add a By Paths rule, and add the paths /api/endpoint1 and /api/endpoint2.

1.5 Add a By Methods rule, and add the GET and POST methods.

1.6 Save the exemption, and save the updated Hosted Web Service.

2. Requests with Credentials, with access to the Banyan TrustCookie

In situations where CORS is used with credentials, and both the origin and destination are both part of a root domain, a simpler exemption can be used.

For example, say https://origin.website.corp.com makes CORS requests with credentials to https://dest.website.corp.com. We can set up a single multi-domain web service at *.website.corp.com. Then set up an exemption as follows:

2.1 Navigate to the Access Permissions tab on a Hosted Website.

2.2 Expand the Exemptions section, and select Add Exemption.

2.3 Add a By Origin Header rule, and add the origin https://origin.website.corp.com:443.

2.4 Add a By Target Domain rule, and add https://dest.website.corp.com:443.

2.5 Add a By Mandatory Headers rule, and add the headers ACCESS-CONTROL-REQUEST-METHOD and ACCESS-CONTROL-REQUEST-HEADERS.

2.6 Save the exemption, and save the updated Hosted Web Service.

3. Preflighted Requests

In a situation where preflighted CORS requests are being used, we must additionally exempt OPTIONS requests. In order to do so, complete the following steps:

3.1 Navigate to the Access Permissions tab on a Hosted Website.

3.2 Expand the Exemptions section, and select Add Exemption. This is in addition to any other exemption set above.

3.3 Add a By Method rule, and add the ORIGIN method.

3.4 Save the exemption, and save the updated Hosted Web Service.

This extra exemption will make sure that all preflighted requests can reach the service.


Can’t find what you’re looking for?

We’re happy to help. Contact our team.