CORS with WSO2 Identity Server 5.11

Oshan Ivantha
6 min readDec 4, 2020


What is CORS?

If you are here, chances are you know what CORS is. But let’s go through the basics in case you are a bit rusty on the exact way that CORS works. You can hop over to the next section if you feel confident about your knowledge of CORS.

Cross-origin resource sharing AKA CORS is simply a mechanism for controlling the access to a resource located outside of a given domain. So what is actually a ‘given domain’? Allow me to illustrate this in a more simple manner!

Concept source:

Assume that you are browsing the content of a website hosted in a specific domain. When you try to retrieve resources from a web server in the same origin, that is a “same-origin request”. “Cross-origin request” is when you try to retrieve a resource from a different domain than the one that you are in. The important question is, why does it matter whether a request is from the same origin or a different origin.


CORS is actually a security measure that prevents unwanted access to APIs. Assume that you got an API at Whether or not, should you allow any domain to access your API depends on the authentication method. Assume the authentication to the is based on session cookies. So a user who has previously accessed your API through the website, can have the session cookies saved in the browser. If allows requests from any domain, another website will be able to send requests to using AJAX even without the permission of the user. It doesn’t matter if the request originates from the as browsers automatically attach cookies associated with the destination domains. This is why is it important to be able to control access to the domains that can send requests to your APIs.


Concept source:

A simple breakdown of CORS request flow is as follows.

  1. The user takes an action that triggers a request (A) to a different domain.
  2. The web browser identifies that request A is a cross-origin request and temporarily stops the request.
  3. The web browser sends another request B called the preflight request to the destination domain (Y) asking whether it accepts requests from the domain (X) that the request A originated in.
  4. The destination domain (Y) sends back a response to the preflight request B sent by the browser.
  5. If the preflight request says that the destination domain (Y) accepts requests from the initial domain (X), then the browser proceeds to send the original request A.

For a more detailed explanation on how CORS work, please visit

WSO2 IS and CORS before 5.11

WSO2 IS versions prior to the 5.11 enforced CORS using an open-source CORS filter. This filter was applied to the web.xml file of the internal Tomcat server in order to set the CORS configurations. A sample CORS configuration looked like below.

<param-value>GET, HEAD, POST, OPTIONS</param-value>

There were some limitations to this design. The biggest obstacle was that the Identity Server had to be restarted whenever a CORS origin needed to be added to the configurations. It was not possible to configure these settings through the user interface. This could be a serious limitation in an environment where a large number of applications are managed by a single IS instance.

Another obvious shortcoming in the previous CORS filter was that the configurations were universal to all the tenants. There wasn’t any way of defining separate configurations per tenant. This again wouldn’t be much of an issue where there are few tenants and each of them has only several applications. But it becomes a necessity rather than a nice-to-have when a single IS instance manages a number of tenants.

The dawn of a new era for CORS

The requirement for a new design

It was obvious that the existing CORS filter had to be improved in order to get rid of at least some of its limitations. The expectation was that the new CORS management feature will support,

  1. Modifying the configurations without restarting the Identity Server.
  2. Configuring separate CORS origins per each application.

The first requirement seemed simple enough. However, the issue was that it was apparent that significant work was required in order to extend the existing CORS filter to read the dynamically set configurations.

Allowing users to configure CORS per application was much more complicated. The browser decides whether a specific CORS request is allowed by sending a preflight request. And the user nor the domain which makes the request does not have any control over what is sent in this preflight request. The IS can only respond to the preflight request using the information added to it by the web browser. So the only way for the IS to identify the application which sent the request is through the origin URL of the preflight request.

The WSO2 IS doesn’t support the application URLs yet. At its current state, the WSO2 IS has partial support for the per-tenant-URLs. Therefore, for the time being, the new CORS feature will also have to be supported only at the tenant level. And even that is at the beta level as the tenant URL mode will not be fully available for all the endpoints in IS 5.11.

The new CORS architecture

A new design for the CORS management feature was proposed, considering all the previous requirements and concerns.

In the new design, all the CORS management functionality is achieved using an OSGi service (1). This functionality is made available through the Server Configuration API (4), Application Management API (5) and a new CORS API (6). The custom CORS Valve (2) has replaced the previous CORS Filter where the configurations could only be changed at the deployment stage.

How to use the new feature?

Deployment stage configurations

You can still set up the CORS configuration at the server level using the deployment.toml if that is your cup of tea. As an example, you can set the same configuration mentioned for the web.xml as below.

allowed_origins = [
supported_methods = [
exposed_headers = [ “Location” ]

Simple enough right? You can check out all the configurations that you can set in here. This function will work regardless of whether you have enabled tenant URL mode in the Identity Server or not.

Manage CORS using the REST APIs

These APIs will allow you to set CORS configurations per tenant. But it will only work if the tenant URL mode is enabled.

Server Configuration REST API

This API will allow setting separate CORS configurations per each tenant. If these are not specifically set for a tenant, the server level configurations will be used.

Application Management REST API

The previous PUT API call for OIDC inbound will allow updating the allowed CORS origins per application through the allowedOrigins parameter. Even if these are configurable per application, they will still be applied at the tenant level. In other words, when a CORS origin is allowed for an application, it will be allowed for all the applications of that particular tenant.


The new CORS API will facilitate retrieving all the allowed CORS origins per tenant. This can also show you which applications have allowed CORS requests for specific origins.

So that is it about our new CORS functionality. We are pretty excited about it. Please let us know if you find any bugs when using it.

Yours sincerely,

The author of the new CORS feature 😉