This documentation is for WSO2 Enterprise Service Bus version 4.8.0 . View documentation for the latest release.

All docs This doc
Skip to end of metadata
Go to start of metadata

The Entitlement Mediator intercepts requests and evaluates the actions performed by the user against an eXtensible Access Control Markup Language (XACML) policy. WSO2 Identity Server can be used as the XACML Policy Decision Point (PDP) where the policy is set, and WSO2 ESB serves as the XACML Policy Enforcement Point (PEP) where the policy is enforced.   

When configuring the Entitlement mediator, you specify which sequence to execute depending on the entitlement results.

  • OnAccept: the sequence to execute when the Entitlement mediator returns a result of Permit. For example, for this result, you might configure the sequence to direct the request to the back end server as requested.
  • OnReject: the sequence to execute when the Entitlement mediator returns a result of Deny, Not Applicable, or Indeterminate. For example, for this result, you might configure the sequence to respond to the client with a message saying "Unauthorized Request".
  • Obligations and Advice: when the XACML response contains an obligation or advice statement, the Entitlement mediator clones the current message context, creates a new message context and sets the obligation or advice statement to the SOAP body, and then executes the sequence. It executes the obligations sequence synchronously and therefore waits for its response. If the sequence returns true, the OnAccept sequence is executed; if false, the OnReject sequence is executed. The Advice sequence is executed asynchronously, so the mediator does not wait for a response.


<entitlementService remoteServiceUrl="" remoteServiceUserName="" remoteServicePassword="" callbackClass="org.wso2.carbon.identity.entitlement.mediator.callback.[UTEntitlementCallbackHandler|X509EntitlementCallbackHandler|SAMLEntitlementCallbackHandler|KerberosEntitlementCallbackHandler]" 

UI configuration

When you add the Entitlement mediator to a sequence, the Entitlement mediator node appears in the tree with four entitlement results sequence nodes below it.

The Entitlement mediator configuration screen appears below the tree.

Configure the following options (you can also configure the mediator using XML by clicking switch to source view):

  • Entitlement Server - Server URL of the WSO2 Identity Server that acts as the PDP (e.g., https://localhost:9443/services)
  • User Name - This user should have permissions to log in and manage configurations in Identity Server.
  • Password - The password corresponding to the user name.

  • Entitlement Callback Handler - The handler to use to get the subject (user name) for the XACML request:
    • UT: looks for the subject name in the Axis2 message context under the username property. This is useful when UsernameToken security is enabled in ESB for a proxy service, because once a user authenticates to this proxy service the username would be set to the Axis2 message context, so the Entitlement mediator would automatically get the subject value for the XACML request from there. This is the default callback class.

    • X509: specify this class if the proxy is secured with X509 certificates.

    • SAML: specify this class if the proxy is secured with WS-Trust.

    • Kerberos: specify this class if the proxy is secured with Kerberos.

    • Custom: allows you to specify a custom entitlement callback handler class. 

      You can also set properties that control how the subject is retrieved; see Advanced callback properties.

  • Entitlement Service Client - The method of communication to use between the PEP and the PDP. For SOAP, choose whether to use Basic Authentication (available with WSO2 Identify Server 4.0.0 and later) OR the AuthenticationAdmin service, which authenticates with the Entitlement service in Identity Server 3.2.3 and earlier. Thrift uses its own authentication service over TCP. WS-XACML uses Basic Authentication.

    The XAMCL standard refrains from specifying which method should be used to communicate from the PEP to the PDP, and many vendors have implemented a proprietary approach. There is a standard called “Web Services Profile of XACML (WS-XACML) Version 1.0″, but it hasn't been widely adopted because of its bias toward SOAP and the performance implications from XML signatures. However, the benefit of adopting a standard is the elimination of vendor locking, because it will allow your current PEP to work even if you move to a PDP from another vendor (as long as the new PDP also supports this standard). Otherwise you may need to modify your existing PEP to adopt to the new PDP. WSO2 Identity Server has its proprietary SOAP API, Thrift API, and basic support for WS-XACML.

  • Thrift Host and Port - when the Entitlement Service Client is set to Thrift, use these fields to specify 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.

You will now define the sequences you want to run for the entitlement results.

  1. If you want to specify an existing sequence for a result, click Referring Sequence for that result and select the sequence from the registry.
  2. If you want to define the sequence in the tree, leave In-Lined Sequence selected.
  3. Click Update.
  4. In the tree, click the first result node whose sequence you want to define inline, and then add the appropriate mediators to create the sequence. Repeat for each result node whose sequence you are defining inline.

Advanced callback properties

The abstract EntitlementCallbackHandler class supports the following properties for getting the XACML subject (user name), specifying the action, and setting the service name. The various implementations of this class (UTEntitlementCallbackHandler, X509EntitlementCallbackHandler, etc.) can use some or all of these properties. You implement these properties by adding Property mediators before the Entitlement mediator in the sequence.

The default UTEntitlementCallbackHandler looks for a property called username in the Axis2 message context, which it uses as the XACML request subject-id value. Likewise, the other handlers look at various properties for values for the attributes and construct the XACML request. The following attribute IDs are used by the default handlers.

  • urn:oasis:names:tc:xacml:1.0:subject:subject-id of category urn:oasis:names:tc:xacml:1.0:subject-category:access-subject
  • urn:oasis:names:tc:xacml:1.0:action:action-id of category urn:oasis:names:tc:xacml:3.0:attribute-category:action
  • urn:oasis:names:tc:xacml:1.0:resource:resource-id of category urn:oasis:names:tc:xacml:3.0:attribute-category:resource
  • IssuerDN of category urn:oasis:names:tc:xacml:3.0:attribute-category:environment (used only by X509 handler)
  • SignatureAlgorithm of category urn:oasis:names:tc:xacml:3.0:attribute-category:environment (used only by X509 handler)

In most scenarios, you do not need to configure any of these properties.

Property nameAcceptable valuesScopeDescription

By default, the Entitlement mediator expects to find the XACML subject (user name) in a property called username in the message's Axis2 context. If your authentication mechanism specifies the user name by adding a property of a different name, create a property called xacml_subject_identifier and set it to the name of the property in the message context that contains the subject.

xacml_actionstringaxis2If you are using REST and want to specify a different HTTP verb to use with the service, specify it with the xacml_action property and specify the xacml_use_rest property to true.

If you are using REST, and you want to override the HTTP verb to send with the request, you can set this property to true to set to true.

xacml_resource_prefixstringaxis2If you want to change the service name, use this property to specify the new service name or the text you want to prepend to the service name. 



If set to true, the xacml_resource_prefix value is used as the whole service name. If set to false (default), the xacml_resource_prefix is prepended to the service name.



<proxy xmlns=""
         <entitlementService remoteServiceUrl="https://localhost:9443/services"
               <makefault version="soap12">
                  <code xmlns:soap12Env=""
                  <reason value="UNAUTHORIZED"/>
                  <detail>XACML Authorization Failed</detail>
               <property name="RESPONSE" value="true"/>
               <header name="To" action="remove"/>
                     <address uri="http://localhost:8281/services/echo"/>
   <publishWSDL uri="http://localhost:8281/services/echo?wsdl"/>
   <policy key="conf:/repository/axis2/service-groups/EchoProxy/services/EchoProxy/policies/UTOverTransport"/>
   <parameter name="ScenarioID">scenario1</parameter>
  • No labels