XACML Reference Architecture based on WSO2 Identity Server

XACML is a powerful access control policy language implemented in XML that can provide a standardized way of validating authorization requests. XACML is the de-facto standard for authorization and provides the ability for a 3rd party application/component to enforce attribute based access control.

Given below is a reference architecture on how different XACML components can work in the deployment.


Policy Enforcement Point (PEP) – PEP is a component that would enforce access control to a resource based on the input received from a Policy Decision Point (PDP). In the actual deployment PEP can be an application that would provide access to a resource. PEP would send attributes to the PDP and the PDP would reply back with response that would be either to allow or deny access to a resource.

Policy Decision Point (PDP) – PDP is the XACML engine that makes policy decisions on behalf of an enforcement point. PDP would make policy decisions based on a set of XACML polices that are deployed in the PDP.

Policy Information Point (PIP) –  PIP is an information source to which PDP can refer to and get more information on an attribute. PIP can be a user store, a flat file, a DB or any data source. For example if the PDP receives a username as an attribute, it can refer to a user store and get the set of roles assigned to that particular role to make a decision on whether to deny or grant access to a resource.

Policy Administration Point (PAP) – PAP is a component from which XACML policies are created/uploaded, edited and deployed to a PDP. An authorized user can come and create these policies in the PAP and the required policies can be deployed to the PDP.

Policy Repository – Policy Repository is where all the XACML policies are stored, policy repository can also manage multiple versions of a XACML policy.

Adding WSO2 public certificate to Java Certificate Store

When using WSO2 Identity Server to provide OpenID Connect based SSO, you may encounter the following error,

javax.net.ssl.SSLHandshakeException: sun.security.validator.ValidatorException: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target

This is commonly observed when trying to generate an access token from the WSO2 Identity Server. This error occurs due to the fact that the public key of the WSO2 Identity Server doesnt exist in the Java certificate store. You can follow the steps given below to avoid this error.

1. Generate a public key from the WSO2 carbon keystore – To do this you would need to access the following folder. <IS HOME>\repository\resources\security. Once inside the folder, run the below command to export the public certificate.

keytool -export -keystore wso2carbon.jks -alias wso2carbon -file wso2PubCert.cer

you will be prompted to enter the password, the default password is ‘wso2carbon’. If this command is executed correctly you will see a newly created PubCert.cer certificate file in this folder.

2. Import the certificate to the Java certificate store -To import the certificate navigate to the following folder. <JavaHome>/jre/lib/security. Open a console from here and run the following command to get the number of certificates that are currently in the certificate store.

keytool -list -keystore cacerts

Default Password : ‘changeit’

This will list down all the certificates in the store. If you scroll up you would see the number of certificates in the store.

Lets import the WSO2 public certificate to this certificate store. You can do this by running the following command. For Windows users please make sure that your command prompt is running as administrator.

keytool -import -keystore cacerts -file <Certificate Path>\wso2PubCert.cer

Default Password : ‘changeit’

You will get the confirmation that the certificate is successfully imported, you can validate this by listing the certificates using the list certificates command given above.

You should now be able to access the OAuth 2.0 endpoint of the WSO2 Identity Server and generate an access token.

Accessing an OAuth 2.0 secured API in WSO2 API Manager with a SAML 2 Bearer token

One of the key feature provided by the WSO2 API Manager is its ability to secure the exposed API’s using OAuth 2.0 tokens. WSO2 API Manager supports all 4 grant types of OAuth 2.0 specification. OAuth 2.0 is a specification that is widely adapted especially in the mobile application space. However we still find the need for API’s to be accessed by web applications that still use standard username-password based credentials. Many of these web applications use SAML 2 based authentication and would prefer to use the same SAML assertion to access OAuth 2.0 protected API’s. This type of a scenario is supported by WSO2 API Manager which supports a SAML 2 Bearer grant type that can allow an application to exchange the SAML 2 bearer token with an OAuth 2.0 access token. This token exchange is transparent to the end-user hence it will not impact their user experience. This token exchange process can be depicted in the diagram below.diag

Step 1 – Application receives a SAML assertion from the SAML IdP after authenticating the user.

Step 2 – When the Application needs to invoke an API, it sends the SAML assertion to the token endpoint of the API Manager. SAML assertion is Base 64 encoded and sent as a SAML Bearer grant. Application will also need to send the consumer key and consumer secret which has to be obtained when subscribing to this API.

Step 3– API Manager will validate the request and exchange the SAML token with an OAuth 2.0 access token and a refresh token.

Step 4 – Application Access the API with the OAuth 2.0 access token (generated in the above step). This OAuth 2.0 token should be included as the Authorization header when invoking API’s via the API Manager.

The objective of this blog is to introduce the concept of token exchange, you would find detailed instructions on how to set this up in the following API Manager document.


WSO2 API Manager for message mediation

Even though the API Manager’s primary focus is to manage and expose API’s to different API consumers, it a common scenario to have the API Manager to perform some level of message mediation for both message requests and responses. The gateway component of the WSO2 API Manager is essentially a lightweight ESB that can perform almost all mediation activities that can be done by a regular ESB.

Newer releases of WSO2 API Manager provides the ability to attach mediation sequence to the request, response or the fault sequence of an API. The sequence gets executed when a request is made or a response is received to a request. Let’s look at how to add a message mediation to an API.

  1. Firstly you need to create message mediation sequence. Lets create the following sequence that would add a header to an out-going message. Save this sequence as setHeader.xml`
<sequence xmlns="http://ws.apache.org/ns/synapse"  name="SetHeader">
<header name="TempHeader" value="Test Header Value" action=set/>
  1. Log-in to the management console of the API Manager. You can access the management console via the following URL https://{IP}:9443/carbon You will find multiple options in the left hand navigation bar, select the ‘Browse’ icon in the Resources tab as shown below to access the internal registry.


  1. Once inside the registry, navigate into ‘/_system/governance/apimgt/customsequences/in/’ folder in the registry and add the newly created setHeader.xml. Similarly if you have any sequence that needs to be added to the out sequence or the fault sequence you can do so by going into each of these folders under ‘customsequences’ folder. You can upload a sequence by selecting ‘Add Resource’ button and upload this file as shown below.


  1. Once this is done, you can go to the publisher of the API Manager, and create a new API. Enter the required information in ‘Design’ and ‘Implement’ tabs and move to the ‘Manage’ tab. In the ‘Manage’ tab tick on the ‘message mediation policies’ and select the ‘SetHeader’ from the inflow dropdown as shown below. Once this is done Save & Publish the API to the API Store.


  1. You can now invoke the API from the API Store. You will see that the new header called ‘TempHeader’ is added to the message request before the backend API is invoked.