Abbreviated Language for Authorization

ALFA
Paradigm	Declarative programming
Designed by	Pablo Giambiagi, David Brossard
Developer	Axiomatics
First appeared	July 16, 2012; 12 years ago
Filename extensions	.alfa
Website	alfa.guide
Major implementations
	Axiomatics, Rock Solid Knowledge
Influenced by
	XML, XACML
Influenced
	Rego, Cedar

‹The template Manual is being considered for merging.›

The Abbreviated Language for Authorization (ALFA) is a domain-specific language used in the formulation of access-control policies.^[2]

History

Origin

XACML, the eXtensible Access Control Markup Language, uses XML as its main encoding language. Writing XACML policies directly in XACML leads to bloated, human-unfriendly text,^[3] therefore a new, more lightweight, notation was necessary. Axiomatics researcher, Pablo Giambiagi, therefore designed ALFA, the Axiomatics Language for Authorization.

ALFA maps directly into XACML. ALFA contains the same structural elements as XACML i.e. PolicySet, Policy, and Rule.

Axiomatics donates ALFA to OASIS

In March 2014, Axiomatics announced it was donating ALFA to the OASIS XACML Technical Committee^[4] in order to advance its standardization.

ALFA was consequently renamed Abbreviated Language for Authorization and filed for standardization.

Sample use cases

Medical use case: doctors can view the medical records of patients they have a relationship with.
Financial use case: employees in Singapore can view the customer accounts of employees based in Singapore.
Insurance use case: an insurance agent can approve the claim of a user if the claim is in the same region as the agent and if the claim amount is less than the agent's approval amount.

The words doctor, view, medical record, Singapore... are all examples of attribute values. Attributes make up the building blocks of policies in ABAC and consequently in ALFA.

Structure

Just like XACML, ALFA has three structural elements:

PolicySet
Policy
Rule

Like in XACML, a PolicySet can contain PolicySet and Policy elements. A Policy can contain Rule elements. A Rule contains a decision (either Permit or Deny). In addition, in ALFA, it's possible to add Rule elements to PolicySet and Policy elements. PolicySet, Policy, and Rule elements can be nested or referenced to.

In order to resolve conflicts between siblings, ALFA (as does XACML) uses combining algorithms. There are several combining algorithms that may be used.

Data types

ALFA supports all the data types that are defined in the OASIS XACML Core Specification. Some datatypes e.g. numerical (integer, double) and boolean map directly from ALFA to XACML. Others need to be converted such as date or time attributes. To convert an attribute into the relevant data type, use the "value":datatype notation. See below for examples^[5]

Native attribute values mapped directly from ALFA to XACML

String, integer, double, and boolean all map directly from ALFA to XACML. They do not need a conversion

ALFA policy using boolean attributes

	namespace exampleBoolean{
		policy article{
			target clause userRole == "editor" and actionId == "edit" and itemType=="article"
			apply firstApplicable
			rule publishedArticles{
				target clause published == true
				permit
			}
		}
	}

Attribute values which need an explicit conversion

The following attribute datatypes need an explicit conversion:

Example: ALFA policy using anyURI

This policy, converts a String value to anyURI.

	attribute userDisallowedResources{
		category = subjectCat
		id = "userDisallowedResources"
		type = string
	}

	rule allowProfileAccess{
		target clause url == "http://<host>:<port>/profile/":anyURI
		permit
	}

Sample policies

A simple policy & rule with a condition

The following ALFA example represents a XACML policy which contains a single rule. The policy and rule both have a target. The rule also has a condition which is used to compare 2 attributes together to implement a relationship check (user ID must be equal to owner). Whenever one needs to check 2 attributes together, they must use a condition.

	namespace example{
		policy article{
			target clause itemType=="article"
			apply firstApplicable
			rule editArticle{
				target clause actionId == "edit" and userRole == "editor"
				permit
				condition userId == owner
			}
		}
	}

Using time in a XACML policy written in ALFA

	namespace exampleTime{
		policy checkTimeAccess {
			apply firstApplicable
		  	rule checkNightAccess {
	   			target clause role == "supervisor" and document == "medicalrecord"
	   			condition timeInRange(timeOneAndOnly(currentTime), "22:00:00":time, "06:00:00":time)
				permit
			}
	  	}
	}

Policy references

ALFA can use policy (set) references. They are in fact used implicitly when doing the following.

namespace com.axiomatics{
	namespace example{
		/**
		 * A policy about what managers can do. It is linked to from the
		 * documents policy set.
		 */
		policy managers{
			target clause role == "manager"
			apply firstApplicable
			rule allowSameDepartment{
				condition user.department == document.department
				permit
			}
		}
	}
	
	/**
	 * The main policy. It references the managers policy
	 */
	policyset documents{
		target clause resourceType == "document"
		apply firstApplicable
		// The following is a policy reference
		example.managers
	}
}

Obligations and advice

Obligations and advice are statements in XACML that can be returned from the PDP to the PEP alongside the decision (Permit, Deny...). Obligations and advice are triggered on either Permit or Deny.

namespace example{
    import Attributes.*
    advice notify = "example.notify"
    
    policy readDocuments{
        target clause actionId=="read" and objectType=="document"
        apply firstApplicable
        /**
         * This rule denies access if the time is not between 9 and 5
         */
        rule denyOutsideHours{
            target clause currentTime<"09:00:00":time or currentTime>"17:00:00":time
            deny
            on deny{
                advice notify{
                    acme.obligations.message = "You cannot access this service outside office hours"
                }
            }
        }
        /**
         * This rule grants managers access
         */
        rule allowManagers{
            target clause acme.user.role=="manager"
            permit
        }
        /**
         * This rule catches anything else that might have fallen to this point
         */
        rule failsafeDeny{
            deny
            on deny{
                advice notify{
                    acme.obligations.message = "Your request did not match the policy. Please try again"
                }
            }
        }
    } 
}

Break the glass authorization scenario

Start by defining the attributes and obligations:

namespace com.axiomatics.examples{
	
	import Attributes.*
	
	obligation breakTheGlass = "com.axiomatics.examples.breakTheGlass"
	obligation auditLog = "com.axiomatics.examples.auditLog"
	
	namespace user{
		attribute role{
			category = subjectCat
			id = "com.axiomatics.examples.user.role"
			type = string
		}
		attribute identifier{
			category = subjectCat
			id = "com.axiomatics.examples.user.identifier"
			type = string
		}
	}
	namespace patient{
		attribute assignedDoctor{
			category = resourceCat
			id = "com.axiomatics.examples.user.assignedDoctor"
			type = string
		}
	}
	namespace record{
		attribute identifier{
			category = resourceCat
			id = "com.axiomatics.examples.record.identifier"
			type = string
		}
	}
	attribute actionId{
		category = actionCat
		id = "com.axiomatics.examples.actionId"
		type = string
	}
	attribute objectType{
		category = resourceCat
		id = "com.axiomatics.examples.objectType"
		type = string
	}
	attribute isEmergency{
		category = environmentCat
		id = "com.axiomatics.examples.isEmergency"
		type = boolean
	}
	attribute message{
		category = environmentCat
		id = "com.axiomatics.examples.message"
		type = string
	}

The policy can now be defined with 3 rules:

the first rule is for normal access (doctors can view records of patients they are assigned to.
the second rule is for special access because the glass has been broken.
the third rule is the rule that triggers the obligation telling the user how to break the glass.

	/**
	 * Control access to medical records
	 */
	policy accessMedicalRecord{
		target clause actionId == "view" and objectType == "medical record"
		apply firstApplicable
		/**
		 * Doctors can view medical records of patients they are assigned to
		 */
		rule allowRegularAccess{
			target clause user.role == "doctor"
			condition patient.assignedDoctor == user.identifier
			permit
		}
		/**
		 * Doctors can view any medical reason in the case of an emergency
		 */
		rule allowBreakTheGlassAccess{
			target clause isEmergency == true
			permit
			on permit{
				obligation auditLog{
					message = "A doctor has gotten access to a medical record by breaking the glass"
					user.identifier = user.identifier
					record.identifier = record.identifier
					currentDateTime = currentDateTime
				}
				
			}
		}
		/**
		 * Deny other accesses. If access is normally denied, tell doctors how
		 * they can get access by "breaking the glass".
		 */
		rule denyAccess{
			deny
			on deny{
				obligation breakTheGlass{
					message = "You do not have access to this medical record. To be granted access, set the isEmergency flag to true."
					record.identifier = record.identifier
					currentDateTime = currentDateTime
				}
			}
		}
	}
}

Time-based fine-grained authorization policy

The following is an example of an ABAC policy implemented using ALFA. It uses time as attributes. It uses a XACML condition to compare the currentTime attribute to the value representing 5pm (expressed in 24-hour time). Note the use of :time to convert the String value to the right data type.

rule allowAfter5pm{		
	permit
	condition currentTime > "17:00:00":time
}

HL7 policies

Use cases

HL7 defines a series of medical access control use cases which can be easily defined in ALFA.

Sample ALFA policies for HL7

Access control based on category of action

	/*
	 * Access Control Based on Category of Action
	 * URL: https://web.archive.org/web/20160304081703/http://wiki.hl7.org/index.php?title=Security_and_Privacy_Ontology_Use_Cases#Access_Control_Based_on_Category_of_Action#Access_Control_Based_on_Category_of_Action
	 * Access to progress notes
	 */
	policy progressNotes{
		target clause objectType=="progress note"
		apply firstApplicable
		/*
		 * A primary physician can create a patient's progress note
		 */
		rule createNote{
			target clause role=="physician" and action=="create"	
			condition primaryPhysician==requestorId
			permit
		}
		/*
		 * A physician can update a patient's progress note he/she wrote themselves
		 */
		rule updateNote{
			target clause role=="physician" and action=="update"
			condition author==requestorId
			permit
		}
		/*
		 * Safety rule to explicitly deny access unless one of the matching rules above has been matched
		 */
		rule safetyHarness{
			deny
		}
	}

Implementations

VS Code extension

A free extension for the VS Code editor that supports code completion, syntax highlighting, refactoring, and go-to-definition navigation. It can also compile ALFA into XACML 3.0.^[6]

Plugin for Eclipse

The ALFA Plugin for Eclipse is a tool that converts your Eclipse programming IDE to a dedicated editor of authorization policies using ALFA syntax. ALFA policies can then easily be converted into XACML 3.0 policies and loaded into your XACML policy management tool.^[7]

References

^ Gebel, Gerry (16 July 2012). "Axiomatics releases free plugin for the Eclipse IDE to author XACML3.0 policies". Axiomatics. Retrieved 31 May 2017.
^ "Simplifying XACML – the Axiomatics ALFA plugin for Eclipse IDE". KuppingerCole. Retrieved 2017-02-10.
^ "XACML 3, section 4.2.3" (PDF). OASIS. Retrieved 2 May 2021.
^ https://www.linkedin.com/grp/post/3934718-5851696088934801412 ^{[self-published source]}
^ https://www.identityserver.com/documentation/enforcer/alfa/QuickGuideToAlfa/
^ "ALFA - Visual Studio Marketplace". 2021-09-10.
^ "How Can I Use Policy References in ALFA?". 2016-10-10.

External References

[1] Gebel, Gerry (16 July 2012). "Axiomatics releases free plugin for the Eclipse IDE to author XACML3.0 policies". Axiomatics. Retrieved 31 May 2017.

[2] "Simplifying XACML – the Axiomatics ALFA plugin for Eclipse IDE". KuppingerCole. Retrieved 2017-02-10.

[3] "XACML 3, section 4.2.3" (PDF). OASIS. Retrieved 2 May 2021.

[4] ttps://www.linkedin.com/grp/post/3934718-5851696088934801412 ^{[self-published source]}

[5] ttps://www.identityserver.com/documentation/enforcer/alfa/QuickGuideToAlfa/

[6] "ALFA - Visual Studio Marketplace". 2021-09-10.

[7] "How Can I Use Policy References in ALFA?". 2016-10-10.

[1]

[2]

[3]

[4]

[5]

[6]

[7]