22 Nov, 2022 | 3 min read

Policy Management with WSO2 API Manager

  • Lakshitha Gunasekara
  • Software Engineer - WSO2

R Mo on Unsplash

REST APIs have become the building blocks of all enterprise business applications over the last few years. There have been significant improvements for these components to make them more convenient to implement, manage, and maintain. Authentication and authorization have been the key element controlling these REST APIs. However, with the advancement of business use-cases, they are used to address modern business problems. As a simple use-case, let’s take a company that wants to introduce a new API that returns confidential information, like an employee review for their HR division. The employees should be able to view their own reviews while only their direct managers should be able to access it. This would be a difficult task with traditional access control mechanisms. This is where WSO2 comes in.

WSO2 has been committed to policy management since its inception in 2005. With the introduction of WSO2 API Manager, the company has immersed itself with several API management deployments, all of which include some form of policy management.

The Policy Framework in WSO2 API Manager 4.1

The latest release of WSO2 API Manager comes with a new powerful, yet lightweight policy framework. This framework has been specifically designed to address problems observed with creating more complex policies and reusing and managing policies at scale. The company decided to address challenges when using the message mediation feature, where policy creators and enforcers try to manage and enforce policies within WSO2 API Manager.

There are different types of policies that can be used to construct a business logic, such as security policies, data population/manipulation policies, audit policies, and compliance policies. Each of these can be enforced before an API request (request flow or inflow), for an API response (response flow or out flow), and in the event of any errors (fault flow). This is shown in Figure 1. 

Figure 1: WSO2 API gateway request, response, and fault flow

Policy Implementation and Governance

Policies are crucial in implementing business logic. We can view a policy in business terms as a set of tasks, or a series of steps executed in a certain order, as part of a business process. There are some terms that explain the policy administration concept, and were initially developed with XACML (attribute-based access control policy language[1]). Let’s observe them below.

  • Policy Administration Point (PAP)
    • The point which manages the policies. 
  • Policy Decision Point (PDP)
    • The point which evaluates API requests against policies before issuing access decisions.
  • Policy Enforcement Point (PEP)
    • The point which intercepts a user's access request to a resource, makes a decision request to the PDP to obtain the access decision, (i.e., access to the resource is approved or rejected), and acts on the received decision.
  • Policy Information Point (PIP)
    • The system entity that acts as a source of attribute values (i.e. a resource, subject, environment).
  • Policy Retrieval Point (PRP)
    • The point where policies are stored.

In WSO2 API Manager, the PAP would be the publisher portal where policy and API creators design, view, and update policies. PDP, PEP, and PIP would be the API gateway where API requests are intercepted and evaluated against applied policies before requests are passed to the backend. Policy decisions are mostly taken by the gateway while in some cases like the “Validate Requests with OPA Policy”, decisions are offloaded to an external policy engine such as OPA. Policy specific information is sent to the gateway when the API is deployed and WSO2 API Manager can customize the policy attributes based on the environment it is deployed. As per PRP, policies are recorded in the internal database and can be exported with the API Controller.

A Dive Into Policies Framework

WSO2 API Manager can implement a policy as a sequence of tasks and make it reusable with fields as parameters. This framework supports both WSO2 API Manager’s API Gateway (Synapse based) and the Choreo Connect microgateway. In this blog, we will focus on the synapse-based gateway. 

The following is a sample policy template that can be used to add a query parameter to the request path.

<property name="rest_postfix" expression="get-property('axis2', 'REST_URL_POSTFIX')"/>
    <filter regex=".*\?.*" source="get-property('rest_postfix')">
	<!-- if there are query params already defined -->
		<property name="REST_URL_POSTFIX" expression="fn:concat(get-property('rest_postfix'), '&amp;{{paramKey}}={{paramValue}}')" scope="axis2" type="STRING"/>

	<!-- if there are no query params defined -->
		<property name="REST_URL_POSTFIX" expression="fn:concat(get-property('rest_postfix'), '?{{paramKey}}={{paramValue}}')" scope="axis2" type="STRING"/>

To make this policy more reusable, we’ve templated the policy by parameterizing the query param key and param value and exposing them as user inputs.

As shown above, a policy is a sequence that executes a set of functions written using synapse mediators. Policy designers can use WSO2 Integration Studio to design such sequences and apply them in WSO2 API Manager. Once the sequence is finalized, you can add the policy to the publisher portal via the policies page. Here, if you need to reuse it in different APIs, you can add it as a Common API Policy, and if it is only applicable to the API, it can be added as an API-Specific Policy. If you wish to improve the reusability of each API, the policies can be parameterized. The policy framework detects such parameters as policy configurations and you can add the values to these configurations when the policy is enforced.

Since policy creators (Authors) and policy users (who apply these to APIs) are two different sets of users, it is crucial to add a description of each policy. You can include such details and explain the use-case behind each policy. With parameterized policies, you can add descriptions of each attribute and configure regex-based validation support for user inputs. The framework supports mandatory and optional parameters as well as shown in Figure 2.

Figure 2: Policy creation

Once created, if the policy is a Common API Policy, you can visit the policies page to view, add, or delete common API Policies as needed. WSO2 has shipped 20 commonly used policies with the 4.1 release, covering several use-cases that out customers require as shown in Figure 3, and we plan to add more in the future.

Figure 3 : Common API Policy view

Policy Enforcement

Once a policy is created as a reusable one, anyone can apply the policy to an API. A policy can be applied to each operation of an API separately, or to all operations at once. You just need to drag and drop the policy into the request, response, or fault of an operation. There’s no limit to the number of policies that can be applied to each operation as a pipeline will execute them in the order they appear and the policy execution order is guaranteed. To change the order of policies, simply drag and drop as illustrated by Figure 4. 

Figure 4: Policy enforcement

Once a policy is dropped to a flow, a side panel will appear with the preconfigured description, policy attributes (which are parameterized), and other information that you can quickly change as needed. This is seen in Figure 5.

Figure 5: Add values for policy parameters

Once policies are added to the operations and changes are deployed in the gateway, they will be aggregated together for an operation while maintaining the policy execution order. 

Design Influence

WSO2 built a framework that supports templating policies and applying policies in bulk while preserving the execution order for individual operations of an API. These changes make policy creators and enforcers more productive and solved several use-cases. Let’s explore this further by answering the following questions.

When the administration or compliance team of an organization decides to apply a new business rule to the APIs of their ecosystem: 

  1. Is it wise to apply such a rule to all the operations of the API at once, or is it better to apply it incrementally to each operation?
  2. If a rule has to be slightly customized from one API to another without parameterized policies, how complex would it be to manage different policies? 
  3. If we can break a complex policy into multiple sub-policies, would it improve the reusability and maintainability?

WSO2 realized that policy enforcers needed to perform bulk policy assignments, create parameterized reusable policies, and compose policies together for the same reasons developers wanted to compose APIs. Let’s take the following example. Say an organization has several hundreds of APIs in its ecosystem. One day, its team notices unusual behavior in its API access pattern in some of its request paths. The developers can easily add an audit policy to all flagged API operations and audit the request trails for possible breaches. If they need to implement more security, additional temporary security policies could quickly be applied in bulk as well.


Although previous versions of WSO2 API Manager versions had similar functionality, the latest version provides assistance for parameterized policies, support to add multiple policies at once, and an interactive user interface to enforce and manage policies. The granularity of policy enforcement has been improved from the API level to an operational level. As for a complex API management requirement, increased granularity will help to accommodate many use-cases. 

Furthermore, Instead of one static mediation policy per API, this new framework splits it into multiple reusable policies, allowing commonly used policies to be parameterized with variable attributes. Instead of duplicating the same logic with different values, you have the option of creating a policy template and providing a set of attributes that can later be used to create mediation stories.

To learn more, check out the release webinar of WSO2 API Manager 4.1 today!

Feel free to reach out if you have questions, we’re more than happy to help.