axiomatics.com
Developers
Support

Intro: Developing with XACML in Java

This article shows a simple and short example of how to use the Axiomatics XACML APIs to create a request, send it to a policy decision point, get a response, and enforce a result. It also shows how to use attributes in requests. Whilst it is a short and gentle introduction, it will hopefuly whet your appetite for more.

As software developers, we often deal with the issue of authorization. Whenever a user tries to do something, or a service is called, or data is released, we usually have to check whether this is permitted in the current context and act accordingly. In some cases we may also find that what is about to happen is indeed permitted, yet must be limited in some way. For example, a user may retrieve data about customers, but the data returned needs to be filtered in some way in order to comply with certain types of privacy regulation, export control or restrictions imposed by the business. Let's assume that you are familiar with the topic of authorization, the difference between coarse-grained and fine-grained authorization, otherwise may we recommend the following articles on our site about Externalized Authorization and Fine-grained Authorization.

In order to grant access, or even restrict access in a well-defined way, we need to have detailed information about what is about to happen. XACML uses a concept called ABAC (Attribute Based Access Control) to express this. The idea behind ABAC is that we can use any number of attributes to describe a request for authorization as well as the policies implementing the authorization rules. In XACML attributes are grouped into four categories: Subject, Action, Resource and Environemnt. Attributes in the Subject category define who is trying to do something. Action attributes define what the Subject is trying to do. Resource attributes are used to describe what is being accessed, and finally attributes in the Environment can be used to provide information about the when, where and how, for example: what type of credentials has the user authenticated with? Is the user sitting in the office or connected through a VPN? XACML is described in the article "100% pure XACML".

As developers, we can make our lives easier by moving authorization to a layer by itself. We do this by utilizing the XACML APIs to make decisions for us. What remains to be done then is to provide input for the APIs so that they can make a decision. This is done by defining attributes in the four previously mentioned categories, and providing values for them when we call the XACML APIs provided by Axiomatics. We can then invoke the API at the functional points in our code whenever authorization is needed.

The following Java code shows how a XACML request is created, and how attributes in different categories are provided. By default, attributes can be multi-value, meaning that attributes can have more than a single value - as in the case of lists, arrays, and the like. The API we use here is the Axiomatics core XACML API. It gives us all the functionality to create requests.

// Create a XACML request
SimpleRequestWrapper request = new SimpleRequestWrapper(3); // The "3" here means XACML v3
// Add a subject attribute, identified by a URN.
request.addSubjectAttribute(URI.create("urn:oasis:names:tc:xacml:1.0:subject:subject-id"), userName.toString());
// Add a Action attribute (the action ID).
request.addActionAttribute(URI.create("urn:oasis:names:tc:xacml:1.0:action:action-id"), "check-balance");
// Add a Resource Attribute, using a simple identifier.
request.addResourceAttribute(URI.create("resource-owner"), record.owner.toString());

Where in our code should we put authorization calls? Typically whenever we are about to do something but need first to check whether this should be allowed or not. Without XACML, we would probably put some static code into the application where we check for a particular user group or role, or some other information about the current context. For example: Is this entry readable and/or writeable? Should we display all of the data? Instead of coding our logic into our program, we merely collect the information that we have, and then let the XACML authorization API do the work for us. When we call the API with an authorization request, we get back a decision and can then enforce it.

The following example shows how we use our API to make a call-out to the XACML decision engine, which is officially called a policy decision point (PDP). The PDP is where the request is being evaluated against policies. An authorization result then comes back, which we must enforce. For this reason, our piece of software implements a part of the XACML architecture called the policy enforcement point (PEP).

Since the XACML architecture allows many different combinations on how the decision point is called, there is a separation between building a request, and sending the request/collecting the responses, hence there is an APIs for managing requests, and other APIs for communicating with the PDP. These APIs are separated, but work hand-in-hand with each other. Remember the XACML architecture, and what options are available for deploying, and communicating with the PDP? If you need a refresher on the XACML architecture, read up on 100% XACML to get an understanding of the architecture, and optionally read about Policy Decision Points and Policy Enforcement Points.

// Send the request and handle the response
SimpleResponseWrapper response = pep.evaluate(request);

In the simplest case, our authorization request contains either a PERMIT or a DENY. There are also two other results: NOT APPLICABLE and INDETERMINATE. The former tells us that the policy decision point does not have any policy that could make any decision on this request. The latter tells us that there has been an error within the processing of the authorization request. In both cases, our code should be prepared to handle these other two results in a defined way: deny the request or allow the request, depending on what our requirements are.

// Did we get a Permit?
if (response.isPermit()) {
...
} else {
...
}

You've hopefully managed to get an initial grasp of the overall approach to developing with XACML, and how it can simplify your projects. It's not difficult to get started, as you can see from the sample code. Yet XACML is very flexible in terms of giving us many options when it comes to the architecture and the policies. This is why we use several APIs in conjunction. The first API allows us to build XACML requests, and examine the responses. The second API is used to send our request to a PDP and get an answer back. For more information, there is a short video that shows a complete example.

Search


Contact Axiomatics

Would you like to learn more about Axiomatics solutions? Would you like to see a demo? Do you want to speak to an Axiomatics representative about your authorization requirements?

Contact Axiomatics

Analysis and further reading

To get more in-depth information on fine-grained, context aware access control, visit our resource centre. Once you have registered and logged on you can  access all our whitepapers.

Become a registered user