Authorization architecture, design and implementation¶

It's 2023. Trump may become President of God's Own Country next year. We have moved from bespoke authentication and authorization design and implementation to Keycloak and IDshield. With all this comes a new view about the architecture of authorization data, and its implementation.

Authorisation information¶

This information specifies what a user can and cannot do. It has four dimensions:

• Raw capability: this specifies if the user can perform a specific operation. In implementation, it maps on to a web service call (WSC). Can user X call WSC Y?
• Visibility constraints: this specifies whether the user can see all data in a specific table or for a specific call (e.g. all sales data) and if not, then which subsets can he see? This is equivalent to doing a SELECT on a table and using the visibility constraints for a WHERE clause. For instance, user X can see all sales data and user Y can see only North Zone data. In other words, the visibility constraint defines the scope of the access right.
• Attribute constraints: this specifies whether the user can see/edit all the attributes (or columns, in DB parlance) of a class of entities, or can only see a subset. For instance, some privileged users can see the full employee list with all attributes, but most users are not allowed to see the salary data. So, there are restrictions on certain restricted attributes. We can then divide the list of attributes into a general-access set and a privileged set.
• Value constraints: this specifies whether a user's access is restricted to certain value limits of certain quantitative fields. For instance, a junior manager is permitted to approve an invoice with a total value less than a million dollars, whereas a vice president can approve invoices of up to ten million.

Combining all these, we can make a sample statement like this: Mister Joe Pesci can do voucher edits (he has the voucheredit capability) for vouchers of only retail sales (visibility constraint based on voucher type) whose value is less than $20,000 (value constraint). And while he does so, he is not permitted to change the date of the voucher (attribute constraint).

Expressing this in a tight notation, we can specify this tuple:

joe.pesci:   (voucheredit, vouchertype=retailsales, val=(amt,le,20000), attr=!date)

We call these tuples qualified capabilities, which are the result of applying constraints to raw capabilities. Here, the (amt, le, 20000) indicates that the amount of the voucher needs to be less than or equal to (hence le) the limit given.

Mr Pesci may have multiple such qualified capabilities, for various combinations of these four elements.

joe.pesci:   (voucherview, vouchertype=ALL, val={}, attr={})
joe.pesci:   (voucheredit, vouchertype=retailsales, val=(amt,le,20000), attr=!date)
joe.pesci:   (vouchernew,  vouchertype=retailsales, val=(amt,le,20000), attr={})

With this set of records, Mr Pesci can see all vouchers, create vouchers only in retail sales of value less than $20,000 and enter all details (no attribute constraints) but when editing these vouchers, he is not allowed to edit the date.

We can collapse the semantics of the fourth term (attribute constraints) if we expand the set of values for the first term. So, instead of having a generic voucheredit raw capability, we define two raw capabilities: vouchereditfull and vouchereditnodate. With this refinement, we can express the previous set of qualified capabilities in the following way:

joe.pesci:   (voucherview,        vouchertype=ALL,         val={})
joe.pesci:   (vouchereditnodate,  vouchertype=retailsales, val=(amt,le,20000))
joe.pesci:   (vouchernewfull,     vouchertype=retailsales, val=(amt,le,20000))

Thus, the fourth member of the tuple can be eliminated everywhere by applying this trick of defining a more fine-grained set of capabilities.

We make one more pragmatic simplification: we assume that quantitative limits (i.e. val=) will always be upper caps. It is very unlikely that there will be a lower cap to authorisation constraints. In that case, we may assume that the operator will always be le, therefore val=(amt, le, 20000) now becomes simplified to limit=(amt, 20000). Therefore we now have:

joe.pesci:   (voucherview,        vouchertype=ALL,         limit={})
joe.pesci:   (vouchereditnodate,  vouchertype=retailsales, limit=(amt,20000))
joe.pesci:   (vouchernewfull,     vouchertype=retailsales, limit=(amt,20000))

We can now move from the particular to the general. If we generalise the example of Mr Pesci's capabilities. We can now say that a qualified capability has

• one raw capability
• zero or more scope constraints
• zero or more upper-limit constraints

Switching to JSON, we get

"usercaps": {
    "user": "joe.pesci",
    "caplist": [{
        "cap": "voucherview",
        "scope": [
            {"vouchertype": "ALL"}
        ],
        "limit": []
    },{
        "cap": "vouchereditnodate",
        "scope": [
            {"vouchertype": "retailsales"}
        ],
        "limit": [
            {"amt": 20000}
        ]
    },{
        "cap": "vouchernewfull",
        "scope": [
            {"vouchertype": "retailsales"}
        ],
        "limit": [
            {"amt": 20000}
        ]
    }]
}

There will be one such block for each user in the system, and the caplist can have dozens or hundreds of elements in its array. In this representation, one qualified capability is represented by:

    {
        "cap": "vouchernewfull",
        "scope": [
            {"vouchertype": "retailsales"}
        ],
        "limit": [
            {"amt": 20000}
        ]
    }

Both scope and limit are arrays, so it's possible to have additional entries in them. For example:

    {
        "cap": "vouchernewfull",
        "scope": [
            {"vouchertype": "retailsales"},
            {"region": "N"}
        ],
        "limit": [
            {"amt": 20000},
            {"voucherage": 30}
        ]
    }

This may mean that the user has the vouchernewfull raw capability, which allows the user to create new vouchers, but

• only for retail sales transactions
• only for the North region, not for any other part of the business
• only for voucher values less than or equal to 20,000 in whatever is the currency
• only for vouchers younger than or equal to 30 days, which means there is a cap on how far back-dated the new vouchers may be

Using the authorisation information: authz_check()¶

A function called authz_check() will go through a user's usercaps data structure and decide whether there is any qualified capability in her caplist which matches the access being attempted.

Before the application code calls authz_check(), it needs to put together the list of attributes based on which permission will be granted. Let's call this information packet an opreq for operation request. The application code needs to submit the operation request to authz_check() and ask whether the request can be allowed. Basing our example on the tuples shown earlier, the code may go through the following questions and put together the opreq data structure:

• who is the user? joe.pesci
• what operation is being attempted? Voucher edit. Therefore the application code knows the cap the operation needs:
  • Is the date too being updated? If yes, then vouchereditfull
  • Else, vouchereditnodate or vouchereditfull
• What's the type of the voucher being accessed? The application code sees the ID of the voucher being updated, pulls out the voucher record from the database and finds out its type. Let us say it turns out to be bulksales
• What is the amount of the voucher being accessed? This is obtained from the web service request if the amount is being updated, or else from the voucher record in the database: 15520.50

It is not necessary that all details of the operation being attempted are contained in the request parameters of the WSC. Some authorisation determining parameters may be environmental, like

• what is the country from which the access is being attempted (use geo-IP)
• what is the time of day? (It's conceivable that access rules do not permit editing of records outside office hours, only viewing.)

So, first, the application code creates the opreq structure:

"opreq": {
    "user": "joe.pesci",
    "capneeded": ["vouchereditfull", "vouchereditnodate"]
    "scope": [
        {"vouchertype": "bulksales"},
    ],
    "limit": [
        {"voucheramt": "15520.50"}
    ]
}

This structure must be passed to authz_check(), which can then load the user's caplist from backing store and perform a matching operation.

The matching operation steps through the user's caplist, matching each qualified capability against opreq. For a qualified capability to match:

• one of the raw capabilities in opreq must match the cap of the qualified capability
• all the scope terms in the capability must match the corresponding terms in opreq
• all the limit terms in the capability must equal or exceed the figures given in the corresponding terms in opreq
• if there is a term missing in the scope or limit of opreq which is present in the qualified capability, then it is deemed a match. So, for instance, if there is no region specified in opreq when Mister Pesci attempts to view vouchers, and the capability says "region": "N", it is deemed that Mister Pesci can be permitted to perform the operation. (The "region": "N" becomes a constraint which will be returned by authz_check() and will be enforced by the application code, outside the authorisation checking function.)
• if there is a term missing in the scope or limit of the qualified capability which is present in the opreq, it is deemed a match.

The matching operation will return the list of matching elements from the caplist. More than one entry may match; all matching entries will be returned in an array.

The application code which called authz_check() will now scan the entries returned, and will apply any constraints indicated by them. For instance, two users may attempt a voucherview operation, but one user may have a qualified capability with "scope": [{"region": "N"}] and the other user may not have any "region" constraint. In that case, the business logic will receive the matching capabilities list from authz_check(), and in the first user's case, will see the "region" constraint, and will pull out only the matching subset of vouchers to show the user. In the second user's case, the business logic must query the database and pull out all vouchers which exist, since there is no visibility constraint. This is to be done by the business logic, not by the authorisation module.

How authz_check() works¶

The function will take one parameter, opreq, and will return (i) a boolean to indicate whether the request is allowed, and (ii) an array of one or more qualified capabilities which match opreq. This array will be of length zero if the first response is false.

func authz_check(opreq)
        returns boolean permitted
                caplist matchingcaps

    thiscaplist=get this user's caplist from in-memory cache
    if caplist is not there in the cache or if it has expired then
        load from backing store
        insert into cache with an expiry time
    endif

    matchingcaps = []     // empty array of qualified capabilities
    for each qualifiedcap in caplist do
        if qualifiedcap.cap is absent in opreq.capneeded then
            // we must skip this capability, because the cap itself doesn't match
            break out of for-loop
        endif

        entrymatches = true

        //
        // check each entry in the scope arrays for mismatch
        //
        for each scopeentry in qualifiedcap.scope do
            if the corresponding entry is present in opreq then
                if the two values do not match then
                    entrymatches = false
                    break out of for-loop
                endif
            endif
        endfor

        if entrymatches == false then
            // if the scope list itself threw up a mismatch, why
            // bother trying to match the limit list?
            break out of for-loop
        endfor

        //
        // check each entry in the limit array for mismatch
        //
        for each limitentry in qualifiedcap.limit do
            if the corresponding entry is present in opreq then
                if the value in opreq > the value in limitentry then
                    entrymatches = false
                    break out of for-loop
                endif
            endif
        endfor

        // at this point, we've matched all the scope and limit terms
        // of qualifiedcap and opreq. If they all match, we must add the
        // qualifiedcap to the array of matching caps to be returned.
        //
        if entrymatches == true then
            append qualifiedcap to matchingcaps
        endif
    endfor    // for each qualifiedcap in caplist

    if matchingcaps has one or more entries then
        return "true" and matchingcaps array
    else
        return "false" and matchingcaps empty array
    endif
end   // func authz_check()

Variety of constraint variables¶

The examples above have dealt with voucher operations including viewing, editing, and creation. For those operations, the list of constraint variables were

• voucher type
• voucher amount

For an entirely different operation, say viewing of MIS reports of sales data, the constraints may be

• which zone the user belongs to (he will see only his own region's data)
• which department he belongs to (he will see only his product category's data, and dept maps to product category)
• what his rank is (this decides whether he can see only the last month's data, or the last year's, or all historical data)

So, for voucher-related capabilities, one set of constraint variables are applied, and for sales report viewing, a totally different set of variables apply. These can be keyed to the capability:

• for voucherview, vouchereditfull, vouchereditnondate, vouchernew, the voucher type is a constraint variable
• for salesreport, the user's department ID is a constraint variable