The Case of the Heinous Holds

Summary

Designing authorization rules within an Authorization OSID Provider can provide visibility in who has access to what and simplify base service implementations. Working from the authorization evaluation perspective can solve the puzzle that is difficult to see through data attributes. This is a case study of a project that tackles this issue.

The Student System Project

The Student System Project is using the Hold OSID as a means of restricting registration access to students. The registration process uses the Rules.Check OSID as a means of managing what hold Blocks will be checked. 

The product owner understands that one organization may place a Hold on a student while another organization is responsible for expiring it. The Issue has a single responsible Resource? The product owner asks that a list of Organizations, not Resources, who can place the Hold and a list of Organizations who can remove the Hold be added to the Issue.

Work Begins

The application programmer and OSID implementor collaborate to define an OsidRecord for these extra lists of Organizations. The application populates them from user input on a hold administrative screen. 

Holds are tested and they can be created or removed by anyone. The product owner tells the application programmer that these organizations should be checked so that only people inside the organization are allowed to perform these operations.

The application programmer scratches his head, and looks to see how he can figure out who belongs to what organization. He looks to the Personnel OSID to answer this question and sees that Persons are related to Organizations via Appointments and Positions. Dismayed at the bizarre complexity of the situation, shovels out the following code:

boolean checkPlaceHold(org.osid.id.Id issueId, org.osid.id.Id agentId)
    throws org.osid.NotFoundException,
           org.osid.OperationFailedException,
           org.osid.PermissionDeniedException {
    org.osid.resource.ResourceAgentSession resourceAgentSession = resourceMgr.getResourceAgentSession();
 
    // I'll assume the resourceId is the same as the personId
    org.osid.id.Id resourceId = resourceAgentSession.getResourceIdByAgent(agentId);
 
    org.osid.hold.IssueLookupSession issueLookupSession = holdMgr.getIssueLookupSession();
    org.osid.hold.Issue issue = issueLookupSession.getIssue(issueId);
    
    // our local org data
    OrganizationHoldRecord record = (OrganizationHoldRecord) issue.getIssueRecord(organizationHoldRecordType);
 
    // could they have made this any more difficult!
    org.osid.personnel.AppointmentLookupSession appointmentLookupSession = personnelMgr.getAppointmentLookupSession();
    appointmentLookupSession.useEffectiveAppointmentView();
    org.osid.personnel.PositionLookupSession positionLookupSession = personnelMgr.getPositionLookupSession();
    positionLookupSession.useEffectivePositionView();
 
    // get the positions of an org - blasted there's no way to get a list of people in an org!
    try (org.osid.id.IdList orgIds = record.getOrgIdsWhoCanPlaceHold()) {
        while (orgIds.hasNext()) {
            org.osid.id.Id orgId = orgIds.getNextId();
            try (org.osid.personnel.PositionList positions = positionLookupSession.getPositionsForOrganization(orgId)) {
                while (positions.hasNext()) {
                    org.osid.personnel.Position position = positions.getNextPosition();
                    try (org.osid.personnel.AppintmentList appointments = appointmentLookupSession.getAppointmentsForPersonAndPosition(resourceId, position.getNextId()) {
                        if (appointments.hasNext()) {
                            return (true);
                        }
                    }
                }
            }
        }
    }
 
    return (false);
}            

Performance

It may come as a shock but the product owner complains that it takes too long to create a hold. Hundreds of database queries are spawned from these looping calls. Both the application programmer and OSID implementation programmer are in agreement on this one. They complain that these APIs were designed to their requirements. They first consider retrieving all the organization data in bulk and filtering through the results, but this seems wasteful. They conclude that if they can have a simple method:

boolean isAgentInAnyOfTheseOrgs(agentId, orgIds)

then they can optimize for this case in a single call and implement it in a direct SQL query. They put such a method in their own Java interface and wire it to the db via an SQL query that joins the Organization, Appointment, Position, and Resource tables. It's now lightening fast. 

Give Us Our New Method

The service architect is brought in to make it official. She asks why these services have been joined together and she is told that the service design does not meet their needs. She is informed that if this new method was put into the interface, then it would be compliant. However, there isn't much she can do to affect the OSIDs within the time frame of this project's milestone. Not yet knowing the details of the problem she talks in generalities -- "this is usually sign of a factoring issue." This has no impact because as fas as the project is concerned, she was already given the solution to the problem and simply has to execute.

On other projects, the service architect can generally align with one of the project roles to help get the others on board. She can speak to the product owner's vision or simplify the work of an OSID implementation developer. When it comes to performance issues, she is alone to defend a methodology that appears to fly in the face of efficiency.

Back in The Lair

The service architect returns to her think tank to ponder the problem. She traces the problem starting from the requirement of discerning among the organizations who can do what with Holds of various Issues. Issues do constrain Holds and that seems like the place to do it. She eventually arrives at the same place the developers on the project did.

Knowing that hacking up cross-service methods made to look like legititmate service operations is akin to putting lipstick on a pig, she takes a different approach. She decides to work the problem backwards. 

Why are they capturing this data? To enforce a policy.

Authorization

At the end of the day, it's all about saying yes or no to an Agent. The service architect looks at authorization without concerning herself with how it got there. Immediately she notices something disturbing. The application is performing its own authorization in the checkPlaceHold() method and not even allowing the Hold OSID Provider to perform its own authorization enforcement. The enforcement must occur within the provider and the Authorization OSID can be brought in to help it out. 

Authorization Mapping

An Authorization check based on an Agent, Function, and Qualifier. 

• Agent: the authenticated entity
• Function: "can create Hold" "can update Hold" "can delete Hold"
• Qualifier: ???

Qualifiers are the slipperiest of the bunch. They vary by Function.

• can update Hold? qualifier=the Hold
• can delete Hold? qualifier=the Hold
• can create Hold? qualifier=we don't have a Hold yet

Holds are created to an Issue and a Resource (student) in the context of a Oubliette OsidCatalog. The qualifier can only be one of these as this is the only information we have on which to authorize. It's probably more common in OSIDs to align Qualifiers with OsidCatalogs. This doesn't necessarily need to be the case. The project wanted Organizations associated with Issues, so aligning Qualifiers to Issues is a good place to start.

Again, this is not concerning itself about managing Authorizations. The choice of Qualifier for the purpose of checking Authorizations is based on what is known at the time of the check. This narrows it down quite a bit. 

Wiring in Authorization

The service architect creates a Hold OSID Adapter wrapping the following methods.

public class HoldAdminSession
    extends net.okapia.osid.jamocha.adapter.hold.spi.AbatractAdapterHoldAdminSession
    implements org.osid.hold.HoldAdminSession
 
    private final org.osid.authorization.AuthorizationSession authzSession;
    private static final org.osid.id.Id CREATEHOLD_FUNCTION_ID;
    private static final org.osid.id.Id UPDATEHOLD_FUNCTION_ID;
    private static final org.osid.id.Id DELETEHOLD_FUNCTION_ID;
 
    HoldAdminSession(org.osid.hold.HoldAdminSession session, org.osid.authorization.AuthorizationSession authzSession) {
        super(session);
        this.authzSession = authzSession;
        return;
    }
    public org.osid.hold.HoldForm getHoldFormForCreate(org.osid.id.Id issueId, org.osid.id.Id resourceId, org.osid.type.Type[] recordTypes) {
        if (this.authzSession.isAuthorized(getAuthenticatedAgentId(), CREATEHOLD_FUNCTION_ID, issueId) {
            throw org.osid.PermissionDeniedException();
        }
        
        // wrap the form so we need can get the issueId on the way back in
        return (new HoldFormAdapter(super.getHoldFormForCreate(issueId, resourceId, recordTypes), issueId);
    }
 
    public org.osid.hold.Hold createHold(org.osid.hold.HoldForm form) {
        if (this.authzSession.isAuthorized(getAuthenticatedAgentId(), CREATEHOLD_FUNCTION_ID, getIssueId(form)) {
            throw org.osid.PermissionDeniedException();
        }
 
        return (super.createHold(form));
    }
    public org.osid.hold.HoldForm getHoldFormForUpdate(org.osid.id.Id holdId) {
        if (this.authzSession.isAuthorized(getAuthenticatedAgentId(), UPDATEHOLD_FUNCTION_ID, holdId) {
            throw org.osid.PermissionDeniedException();
        }
    
        // wrap the form so we need can get the issueId on the way back in
        return (new HoldFormAdapter(super.getHoldFormForUpdate(holdId), holdId);
    }
 
    public org.osid.hold.Hold updateHold(org.osid.hold.HoldForm form) {
        if (this.authzSession.isAuthorized(getAuthenticatedAgentId(), UPDATEHOLD_FUNCTION_ID, getIssueId(form)) {
            throw org.osid.PermissionDeniedException();
        }

        return (super.updateHold(form));
    }
    public void deleteHold(org.osid.id.Id holdId) {
        if (this.authzSession.isAuthorized(getAuthenticatedAgentId(), DELETEHOLD_FUNCTION_ID, holdId) {
            throw org.osid.PermissionDeniedException();
        }
    
        return (super.deleteHold(holdId));
    }
 
    private static org.osid.id.Id getIssueId(org.osid.hold.HoldForm form) {
        if (!(form instance of HoldFormAdapter)) {
            throw new org.osid.InvalidArgumentException("not my form!");
        }
 
        return (((HoldFormAdapter) form).getIssueId());
    }
}

The Gap

The next step is to note the gap between the above Authorizations and the way the project wants to manage Authorizations. Somehow we need to get from Issues and Holds to Organizations. 

Bouncing Off The Organization Wall

Working from the Organization side, the service architect needs to map Organizations to Issues. While there is an owning Organization in the Issue, it doesn't capture the nuance that separate Organizations have access to place and remove Holds. She is already aware that this translates into create and update operations. Perhaps this can be done using an OsidRecord.

With this data the service architect believes she can create the proper Authorizations. But how? 

public org.osid.hold.Issue createIssue(org.osid.hold.IssueForm form) {
    foreach (org in getHoldCreatorOrganizationIds) {
        foreach (person in org) { // insert complexity from first iteration here
            createAuthorization(person, function, newIssue);
        }
    }
    ....
}

This doesn't seem right. This is worse than the code from the first iteration. Yes, it's now in the service provider but it fixes the membership such that if the organization changes, the authorization service is out of date. 

It appears that the Organization OSID is important but it has no idea about hold authorizations. Resolving the organization above the Hold OSID looks terrible and resolving it within the Hold OSID Provider isn't an improvement. There's only one service left.

It's A Song About Alice

The goal is to manage Authorizations in such a way that the Authorization checks in the adapter work as expected. This stake in the ground for the most common pathway, the checking of authorizations, is the simplest. 

The service architect needs to look deeper into the Authorization OSID.