How Can I Comment My Policies?

Joffry Ferrater   ·   Monday, September 5th, 2016

Writing access control policies is an iterative process; You write rules, test for expected results, restructure, amend with additional rules and scope, and retest. One app, two apps or many more and the effort grows. Whether you are alone owning the policy authoring process, or if scope has been delegated or shared across application and/or data owners. Using effective comments can help make sense of work in progress, simplify understanding of finished work and provide more of a snapshot view of policy content.

This blog will focus on the use of comments in the Abbreviated Language for Authorization (ALFA) and will provide examples from both the ALFA Plugin for Eclipse as well as from the ALFA based Condition Editor found in the Axiomatics Services Manager (ASM). If you are unfamiliar with the aforementioned solutions then please check the further reading section first. In short though: ALFA is a pseudo language that simplifies writing Attribute Based Access Control (ABAC) policies. It is provided as a plugin for the Eclipse IDE and it is also incorporated into Axiomatics central administration console, ASM.

Commenting in ALFA

Cutting to the chase, two types of comments are supported in ALFA.
Fig 1: Comments supported in ALFA:

Most developers are familiar with both types of commenting, but both the block and line comment are also easy to understand and learn by policy authors of other backgrounds such as application and data owners and business analysts.

Tasks in ALFA

Optionally and slightly off topic: if you are an advanced user, you might find the ability to create tasks useful. For example a task defined as “//FIXME this condition is wrong” (excluding “” of course) would show up in the Eclipse IDE task associated with your ALFA project. Default task tags include FIXME, TODO and XXX. More can be added through Eclipse preferences.

Note: Tasks will work in the ALFA Plugin for Eclipse, but are not supported in the web-based Policy Editor (PE) incorporated in the Axiomatics Services Manager (ASM).

Okay, with that out of the way, let’s look at a few examples.

Commenting in the ALFA plugin for Eclipse

Documenting work in progress

Perhaps the most common use of comments is in documenting work in progress. I often paste business requirements in their entirety into the ALFA plugin using block comments. This allows me to implement a rule without losing track of the original intent. Once I am done I can either remove the comment or simplify it to serve as a description (see Documenting for a snapshot view below). Other times I leave a line comment near a specific part of the policy to help jog my memory if I need to come back to it later. Another use of course, is documenting for the benefit of colleagues and auditors. Either block comments or line comments will work for all purposes here.

Fig 2: Using block and line comments in ALFA:  

/*
* Block comment: Permit if the user has at least one citizenship
* in the list of allowed citizenships
*/

rule citizenshipCheck{ 
permit
// Line comment: Discuss with David if we can simplify this condition!
condition anyOfAny(function[stringEqual], userCitizenship, allowedCitizenship)
}

 

Authorization for Applications