Part 3 | Enforcer Documentation

Adding advice or obligations

Policies and rules can define actions to take place in the event of a given overall outcome. For example, if a user performs a sensitive action, the system needs to notify the users’ manager of the action. Failure of the policy system to notify the manager of the action should result in the PDP denying the authorization request. The OASIS policy model provides two forms of outcome actions: obligations and advice. Both can be associated with policies, policy sets, and rules. Whereas obligations must be honored by the PEP, the advice is a little looser. Failure to undertake the advice will not change the outcome of the authorization. Advice is particularly useful when the PDP denies an authorization to inform a user why.

The runtime that is hosting the PEP will provide code that handles the advice and obligations. For this tutorial, you will be just issuing advice and obligations.

You will be adding advice to the RestrictAccessToEmployees rule. The advice will inform the user of the reason for denial. Your first task is to define an identifier for the advice. Create a new root namespace called AcmeCorp.Advice, this namespace will host the advice definition. AcmeCorp.Advice.AuthorizationFailure is the name of the advice in ALFA, and “acmeCorp:AuthorizationFailureOutcomeAction” is the identifier for the runtime.

namespace AcmeCorp.Advice
{
    advice AuthorizationFailure = "acmeCorp:AuthorizationFailureOutcomeAction"
}

Use an import statement to bring into scope the AcmeCorp.Advice namespace

namespace AcmeCorp.Finance 
{
    import Oasis.Attributes
    import AcmeCorp.Advice

Now add the advice action to the RestrictAccessToEmployees rule.

rule RestrictAccessToEmployees
{
    condition not Subject.Role == 'employee'
    deny

    on deny
    {
        advice AuthorizationFailure { }
    }
}

Remove the employee attribute value from the Role attribute and re-run the policy. Scroll down to the bottom of the output window, and you will see the advice.
Attributes can be associated with obligations or advice to provide additional context to the handler. Define a string attribute to provide the reason for the authorization failure, and place it into a new attribute category called AuthorizationFailureCat.

namespace AcmeCorp.Advice
{
    category AuthorizationFailureCat = "amceCorp:AuthorizationFailure"

    advice AuthorizationFailure = "acmeCorp:AuthorizationFailureOutcomeAction"

    attribute AuthorizationFailureMessage
    { 
        id = "AuthorizationFailureMessage"
        type = string
        category = AuthorizationFailureCat
    }
}

Assign the AuthorizationFailureMessage inside the on deny statement.

on deny
{
    advice AuthorizationFailure 
    {
        AuthorizationFailureMessage = "You must be an employee to access purchase orders."
    }
}

Re-run the policy and verify in the output window that the advice has the associated attribute values.
There is no limit to the amounts of obligations and advice that the PDP can issue as part of an authorization decision. Add a catch-all piece of advice as part of the PurchaseOrders policy.

policy PurchaseOrders
{
    . . .
    on deny
    {
        advice AuthorizationFailure
        {
            AuthorizationFailureMessage = "Access Denied"
        }
    }
}

Re-run the policy and verify that the output window contains two pieces of advice.
You define Obligations in the same way as advice. Add an obligation to audit all successful authorization requests to the Purchase Order System. Follow the same approach to advice by defining a separate namespace and category for auditing.

namespace AcmeCorp.Obligations
{
    category AuditCat = "acmeCorp:Audit"
    obligation Audit = "acmeCorp:AuditOutcomeAction"

    attribute When 
    { 
        id = "When" 
        type = dateTime 
        category = AuditCat 
    }

    attribute Who 
    { 
        id = "Who" 
        type = string 
        category = AuditCat 
    }

    attribute Description 
    { 
        id = "Description" 
        type = string 
        category = AuditCat 
    }

    attribute What 
    { 
        id = "Action" 
        type = string 
        category = AuditCat 
    }
}

Import the AcmeCorp.Obligations namespace, as you did for advice.
Add an on permit action to the PurchaseOrder policy.

on permit
{
    obligation Audit
    {
        When = CurrentDateTime
        Who = Subject.Email
        Description = "Accessed the Purchase Order system"
        What = Action
    }
}

Add attribute values for Email and CurrentTime.
Re-run the policy to get a permit and verify the obligation is delivered at the bottom of the output window.

Previous Next