Exemptions and Cross-origin Resource Sharing (CORS)
How to enable exemptions and CORS on a Banyan-secured web service
- Exemptions overview
- Configure an exemption
- CORS overview
- Configuring an exemption for a CORS request
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.,
By Source CIDRs: Exempt requests originating from specific IPs (e.g., from a corporate office)
Configure an exemption
To add an exemption for such requests, complete the following steps:
1. Navigate to the Access Permissions tab on a Hosted Web Service.
2. Expand the Exemptions section, and select Add Exemption.
3. Add a By Paths rule, and add the path
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.
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:
The CORS server at the external domain must be configured to allow credentials via the Access-Control-Allow-Credentials header.
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 Web Service.
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
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 Web Service.
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 Web Service.
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.