A second example

The following is an example of a policy that uses some additional features of ALFA.

Let us define an advice that will be used in the example.

namespace ObligationAdvice {
    advice reasonForDeny = "http://example.com/advice/reasonForDeny"
}

Let us also define some additional attributes concerning medical records and printers so we can write a set of policies for a hospital.

namespace hospital {
    policyset topLevel {
        apply permitOverrides
        medicalPolicy
        printerPolicy
    }
    
    policy medicalPolicy {
        target clause Attributes.resourceType == "medical-record"
        apply denyOverrides
        rule {
            permit
            target clause Attributes.role == "doctor"
        }
        rule {
            deny
            condition not(booleanOneAndOnly(Attributes.careRelationExists))
            on deny {
                advice ObligationAdvice.reasonForDeny {
                    Attributes.message = "There is no care relation"
                }
            }
        }
        rule {
            deny
            condition booleanOneAndOnly(Attributes.recordIsBlocked)
            on deny {
                advice ObligationAdvice.reasonForDeny {
                    Attributes.message = "The record is blocked"
                }
            }
        }
    }

    policy printerPolicy {
        target clause Attributes.resourceType == "printer"
        apply permitOverrides
        rule {
            permit
            target
                clause Attributes.role == "doctor"
                    or Attributes.role == "nurse"
                    or Attributes.role == "receptionist"
                clause Attributes.userTraining == "printer-use"
        }
    }
}

This second example introduces a few more features of ALFA.

At the top you can see that we have defined a policyset. A policy set contains either policies or another policy set, allowing for arbitrarily deep nesting. The contained policies or policy sets can either be in-lined within the policy set or, as in the example, referenced by their name. In this example, the two referenced policies become their own separate XACML XML files when the ALFA source is compiled to XACML.

Looking at these policies, we see they both concern hospital procedures. One policy refers to medical records access. Access to medical records is permitted for doctors but is blocked if the doctor does not have a caregiving relationship to the patient or if access to the record has been suspended for some reason.

The conditions show an example of how to convert a bag into an atomic value. As was previously mentioned, all attributes in XACML are bags that may contain any number of values. However, in many cases exactly one value per attribute is expected in the request and the policy wants to operate on this single value. The booleanOneAndOnly function converts a bag of Boolean values into an atomic value, and checks that there is exactly one value in the bag. If there is not exactly one value, then the function returns an XACML Indeterminate result.

Another new feature in this example is the use of an advice. An advice is an extra item in the result which can be used to convey extra information to the PEP. The PEP may ignore the advice, however. There is a similar feature called an obligation which may not be ignored by the PEP. There is no obligation in this example though.

In this case we use an advice to return a reason for a denial of access. That may be important to tell the doctor so he knows how he could gain access if needed. For instance, he might have forgotten to register the patient as being treated by him.

The second policy concerns access to a printer. This policy illustrates a more complex target. In this case, there are three different roles that have been granted access to the printer. The two different clauses are ANDed together, with lower precedence than the OR operator, so any of the three roles will work. In addition the user must have training in how to use the printer.

This second example concludes the introduction. The most significant features of the language have been shown in these examples. The rest of this manual consists of reference information on ALFA's features.