Entitlement Mediator with WSO2 Enterprise Service Bus (ESB)

The WSO2 Identity Server (IS) can function as a eXtensible Access Control Markup Language (XACML) Policy Decision Point (PDP) and the WSO2 Enterprise Service Bus (ESB) can function as a XACML Policy Enforcement Point (PEP). In this post I will explain the configurations available with WSO2 ESB to enforce XACML. The XAMCL standard refrains from specifying what method should be used to communicate from the PEP to the PDP. Many vendors have implemented their proprietary way of doing this. There is a standard around this called “Web Services Profile of XACML (WS-XACML) Version 1.0”. However there hasn’t been any development on this standard for quite a few years now and not much traction is being shown towards it due to its bias to SOAP and its  performance implications due to XML signatures. However the benefit of adopting a standard is the elimination of vendor locking. That is one day you may need move to a PDP from another vendor and still have the current PEP work with it; and if the communication was done based on standards and the new PDP also supports this standard you will easily be able to switch PDPs. Otherwise you may need to modify your existing PEP to adopt to the new PDP. The WSO2 Identity Server has its proprietary SOAP API, Thrift API and basic support of WS-XACML.

Adding Entitlement Mediator to a Sequence

Adding Entitlement Mediator to a Sequence

The PEP in WSO2 ESB is called ‘Entitlement Mediator’. You can engage this mediator within a sequence.

Entitlement Mediator Design View

Entitlement Mediator Design View

As you can see in the above picture, the Entitlement mediator has 4 child sequence references branching from it. ‘OnAccept’ is the sequence which is invoked when the Entitlement mediator returns a result of ‘Permit’. For any other results such as ‘Deny’, ‘Not Applicable’ or ‘Indeterminate’ from the PDP the mediator would invoke the ‘OnReject’ sequence. It is up to the administrator who configures the mediator to decide what to do with the two outcomes. E.g. If the result was ‘Permit’ the request could be directed to the back end service that was requested. If it was ‘Deny’ the request can be directed to a different endpoint or the WSO2 ESB may respond to the client with a message saying “Unauthorized!”. Following images show such a configuration.

OnAccept/OnReject Design View

OnAccept/OnReject Design View

OnAccept/OnReject Source View

OnAccept/OnReject Source View

The ‘Obligations’ and ‘Advice’ sequences are used to handle obligation and advice statements in the XACML response. If there are any obligation or advice statements in the XACML response, the current message context would be cloned and a new message context created and the obligation or advice statements respectively will be set to the SOAP body and the corresponding sequence will be invoked on it. These two sequences have been added as extension points where the user should design it as he want.The advice sequence will be invoked asynchronously and the Entitlement mediator will not wait for its response. The obligations sequence will be invoked synchronously and the Entitlement mediator will wait for its response. If the obligations sequence returns true the Entitlement mediator will proceed to the OnAccept sequence, but if the obligations sequence returns false the Entitlement mediator will proceed to the OnReject sequence. These sequences can be given in-line or by referring to sequences stored in the registry.

Entitlement Mediator Configuration

Entitlement Mediator Configuration

The above image shows the configuration section of the Entitlement mediator. The ‘Entitlement Service Client Type’ is to say which method of communication should be used between the PEP and the PDP. With SOAP there are two options that can be used depending on the method of authentication. You could either authenticate using the Authentication Admin service or using Basic Authentication headers. The Basic Authentication support is only available with WSO2 IS 4.0.0 onwards. With previous Identity Servers you could only use SOAP with Authentication AdminThrift uses its own authentication service over TCP. Thrift is available from IS 3.2.3 onwards. WS-XACML also uses Basic Authentication and is available from IS 4.0.0. ‘Entitlement Sever’ specifies the server URL of the WSO2 IS. This should take the value in the form of


if the Entitlement Service Client Type is set to SOAP or WS-XACML. If it is set to thrift then the Entitlement Server should have the value in the form of


The ‘User Name’ and ‘Password’ fields should take the credentials of a user who has privileges to invoke the Entitlement Service in WSO2 IS. ‘Thrift Host’ and ‘Thrift Port’ should be configured if the Entitlement Service Client Type is thrift. This is the host-port pair used to establish a thrift connection to the entitlement service. The default port on which the thrift service starts is 10500. The Entitlement mediator defines a set of hooks that can be optionally overridden which defines the subject-id, resource-id and action-id attribute IDs respectively of the Subject, Resource and Action categories of the XACML 3.0 request. This configuration is what is known as the ‘Entitlement Callback Handler’. In addition to the above 3 attribute IDs users can add any number of attribute IDs for any number of attribute categories as well. There are four out-of-the-box handlers which can be switched depending on the setup. These handlers exhibit certain behavior for some of the out-of-the-box scenarios that is available with WSO2 ESB. They are:

1. UT – Used if the proxy service is secured with Username Token security policy.
2. X509 – Used if the proxy service is secured with WS-Security policy which requires client certificate or secured with client authentication.
3. SAML – Used if the proxy service is secured with WS-Trust.
4. Kerberos Used if the proxy service is secured with Kerberos.

In addition to these, users can implement their own Entitlement Callback Handlers and plug them to the WSO2 ESB through the synapse configuration. This blog explains how to achieve this.

The properties available in the entitlement mediator can be found here. These properties define the default behavior of the Entitlement Mediator. Specific handlers override this behavior. The default UT handler, overrides the method how the subject-id attribute value is picked. It looks for the property by the name ‘username‘ in the Axis2 message context and sets its value as the XACML request subject-id value. This is because if UsernameToken security is enabled in ESB for a proxy service, once a user authenticates to this proxy service the username would be set to the Axis2 message context. Likewise the other handlers also look at various properties for values for the attributes and construct the XACML request. The following attribute IDs are used by the default handlers.

1. urn:oasis:names:tc:xacml:1.0:subject:subject-id of category urn:oasis:names:tc:xacml:1.0:subject-category:access-subject
2. urn:oasis:names:tc:xacml:1.0:action:action-id of category urn:oasis:names:tc:xacml:3.0:attribute-category:action
3. urn:oasis:names:tc:xacml:1.0:resource:resource-id of category urn:oasis:names:tc:xacml:3.0:attribute-category:resource
4. IssuerDN of category urn:oasis:names:tc:xacml:3.0:attribute-category:environment (used only by X509 handler)
5. SignatureAlgorithm of category urn:oasis:names:tc:xacml:3.0:attribute-category:environment (used only by X509 handler)


One thought on “Entitlement Mediator with WSO2 Enterprise Service Bus (ESB)

  1. himanshu says:

    Hi, if I have understood it clearly then , if we want to standardize our PEP to PDP communication to make PDP changeable in future without any change in PEP, then while creating entitlement mediator we must have to select WS-XACML as Entitlement service client Type… is this correct?

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )


Connecting to %s