How do I use the map function in XACML?

Axiomatics   ·   Tuesday, November 1st, 2016

Some examples of policies are:

• Managers can view documents in their city

• Users can edit documents they own

Each policy uses attributes. In the examples above, the policies use the following attributes:

• A user’s role e.g. manager

• An action e.g. view, edit.

• A resource type e.g. document

• A user’s city e.g. Kalamazoo

• A document’s city e.g. Tallahassee

Functions in XACML

To make sense of the attributes and their values, XACML uses functions. There are different types of functions available in the language:

• Bag functions: these functions are here to manipulate attributes as bags. One such example is stringOneAndOnly as previously described in this blog post.

• Date and time arithmetic functions: these functions operate on date and time attributes. They can be useful to apply time-based authorization as described in this blog post

• Regular-expression-based functions: these functions are great to check whether strings or other datatypes comply to a given pattern.

• Set functions: these functions are great to work on bags of values and do unions or intersections.

• String functions: these functions cover different aspects of using string attributes.

• XPath-based functions: these functions are great to extract and compare XML.

• Arithmetic function: these functions include add() and subtract().

• Equality predicates: these functions cover all the equality functions for the different data types in XACML.

• Logical functions: these functions operate on boolean values e.g. and() and or().

• Numeric comparison functions: these functions work on numeric data types.

• Higher order bag functions: these functions are great to apply other functions to bags of values e.g. AnyOf, AllOf… The map function we will discuss today belongs to this category.

The Map Function

Standard Definition

The XACML 3.0 map function is defined in the XACML 3.0 standard in Appendix A.3.12. Its identifier is:

urn:oasis:names:tc:xacml:3.0:function:map

According to the standard, “this function converts a bag of values to another bag of values”.

The map function takes in n parameters:

• The first parameter is the function to be applied e.g. the arithmetic function integerAdd()

• The second parameter is a bag of values of the relevant data type which in this case would have to be integer.

• The remaining parameters – here only one since add() only takes 2 parameters – are atomic values of the relevant data type – integer again in this case – that are to be used along with the function onto each value of the bag in the second parameter so as to produce a bag of the same size with updated values.

ALFA Example #1

Let’s implement the example aforementioned in ALFA. First, we create 2 attributes of type integer, age and groupAges.

Then, we use them inside a XACML condition.

attribute age{ 
      category = subjectCat
      id = "age
      type = integer
}
attribute groupAges{
      category = subjectCat
      id = "groupAges"
      type = integer
}
/**
 * This policy grants access if the user is more than 5 years older than anyone in the group
 */
policy mapExample{
      apply firstApplicable
      rule addAge{
            permit
            condition age > map(function[integerAdd], groupAges, 5)
      }
}

ALFA Example #2

Assume we have an attribute called age of data type string and we want to convert it to an attribute of data type integer. We would do the following, using ALFA notation:

attribute age{
      category = subjectCat
      id = "age"
      type = integer
}
attribute groupAges{
      category = subjectCat
      id = "groupAges"
      type = string
}
/**
 * This policy grants access if the user is older than anyone in the group.
 */
policy mapExample{
      apply firstApplicable
      rule addAge{
          permit
          condition age > map(function[integerFromString], groupAges)
       }
}

A more useful example, perhaps, is to use the map() function to normalize an entire bag of strings to lower or upper case. In this case, the code would look as:

rule allowCitizen{
      permit
      condition
stringIsIn(stringNormalizeToLowerCase(stringOneAndOnly(citizenship)), map(function[stringNormalizeToLowerCase], allowedCitizenship))
}

Conclusion

The map function will always output a bag of the same size and type as the main parameter being applied to. It is useful to work on all the values of the bag in one go. The map function does not care about the order of the values. Lastly, the map function is only available inside conditions. It cannot be used inside XACML targets.

The “Question of the Week” – an ongoing feature that will tackle technical and usage questions. We’ll have input from our sales engineers and customer relations teams. If you have a question to consider, please send it to webinfo@axiomatics.com.