Filter Manager Design with Grant Restrictions

General Overview

This page intends to model the notion of grant restrictions, or restrictions placed on an authorized user's right to perform some action and the restriction's use within what is referred to as the Filter Manager channel. An early high-level design of the Filter Manager was put together in the parent page Permissions Enhancements. That page basically describes how the hierarchy would work in the context of the channel publishing workflow and gives a description of how it allows the creation of evaluation expressions (represented internally by a new group type called filter groups) that will ultimately end up being used as the principal in the SUBSCRIBE permission grant that is created by virtue of a channel being published.

At the time it was written, we (those involved at Sungard SCT) had not yet discussed the notion of grant restrictions in detail. The introduction of this capability directly affects how the hierarchy will work going forward and forces changes on the design discussed in the Permissions Enhancements page. Therefore, this page further outlines both the design of the user interface with regards to how it is affected by a user's membership within groups that have been granted authorization to perform an activity (referred to as capacities), such as publish channels, and the changes that are necessary to the underlying permission framework to support the design.

Grant Restriction Overview

One of the difficult issues regarding grant restrictions is determining how we allow an artifact created by one user to be modified by other users. There are obviously many variables involved in determining who can and can't perform various activities on some artifact. This section attempts to tackle those that are unique to the filter hierarchy and its design.

In order to allow applications to protect the objects that they're exposing, it's necessary to indicate what is protecting that object. This is done with grants of traditional permissions, namely the combination of an owner, activity, target, and a principal. However, some protected objects create new objects each with their own protecting permission and hence an audience to which those new permissions can be granted. Channel publishing is one example of such a protection. These types of permissions conceptually have an additional aspect beyond protection of a single object. They are permission-generating permissions.

To enable restriction of the audience to which these generated permissions can be granted, the permission-generating permission concept is enhanced with an additional aspect, namely a restriction on the audience to which the resulting, newly created objects can be granted. This concept of a restricted, permission-generating permission is referred to as a capacity. Now once these generated permissions are created they must be modifiable by the same capacity used to create them. Accordingly, these capacity-generated permissions then portray the capacity that was used to create them. To accomodate this bidirectional relationship between permission-generating permissions and their generated permissions we've introduced additional attributes to the permission grant, such that it will be able to reflect both the ability for some permissions to act as capacities and for others to be governed by capacites.

By virtue of a user's membership within various groups, he or she may be granted authorization to perform some activity in the scope of any one or more of these groups. For example, let's assume that the following named filter groups were defined for the sake of this discussion.

Table 1: Four Named Filter Groups

A user may be able to publish channels because he is a member of the Senior Channel Publishers group and also because he is a member of the Senior Math Majors. This authorization is outlined in the following grants with the principal showing the constituents from table 1 rather than the filter group names.

Table 2: Two Restricted Channel Publishing Grants (Capacities)

To date, grants are represented in the UP_PERMISSION table by virtue of an Owner/Activity/Target (the permission), and an assigned Principal (grantee), which ultimately makes up the entire grant. The addition of the grant restriction dictates the need for new attributes for a grant. The attributes includes a unique id, which can be referenced by other grants, the restriction (an entity key - filter group), and an optional reference id, or unique id of a grant (referred to as the controlling grant) that allowed a grant to be created (referred to as the controlled grant). These attributes will of course be added to the UP_PERMISSION table.

Each grant is reflected in the new design being proposed. In the above table, OAT represents Owner/Activity/Target, and as such represents a specific permission being offered by its owning application. Each permission combined with a principal indicates a grant of that permission to the indicated principal. Each grant combined with an optional restriction creates a construct known as a capacity. Instances of IPermissible which convey all permissions available for a specific application also convey which of those permissions supports restrictions and hence can take part in a capacity, which will be discussed later.

Restricted (delegated) Publish new Channel Use Case

Given the two grants above and that the user in question is a Senior Math Major; a descriptive explanation of that user's rights to publish channels can be summarized in the following sentences:

1 - Members of the Senior group can PUBLISH all channels to Prospective Students.
2 - Members of the Senior Math Major group can PUBLISH all channels to Math Majors.

This use case highlights the first challenge in representing a user's hierarchy, which is to allow a distinction between the groups the user is a member of and their ability to target users based on restricted publishing grants made to those groups. To convey such information the filter hierarchy UI will reflect a sum-of-products logical expression. Since this user is eligible for both channel publishing capacities the audience selection step of the channel publishing workflow will appear as shown in the following screen. Note that the images are not of the best quality (understatement), however they attempt to capture a generic representation of the hierarchy as it would be presented in applications making use of it, such as the Channel Manager.

The above screenshot is a representation of the effect that the grant restrictions outlined previously have when the user is exercising their capacity to publish channels. Each capacity is reflected as a fixed part of its own top level product clause shown in the hierarchy. For example, there is a product clause for both the Senior Channel Publishers capacity and the Senior Math Major Channel Publishers capacity. Beneath the capacity is the restriction associated with it, so for the Senior Channel Publishers capacity, the restriction is Prospective Students, likewise for the Senior Math Major Channel Publishers capacity, the restriction is Math Majors.

Note that the sum-of-products represented by the top level OR-ing of each capacity's AND construct and the capacity/restriction entries themselves are un-editable, indicating that any additions to the scope of that restriction will serve to narrow the audience of that restriction. For example, the publisher in this instance has further narrowed the audience receiving this channel to users having blue eyes.

The Audience: label above each capacity indicates the current target audience for that published channel with respect to that capacity. The contribution of a capacity's audience to the overall audience of the channel being published is selected by clicking the checkbox next to the capacity's name. Checking the capacity indicates that it and any narrowing constructs should be persisted as part of the principal within the grant for subscribing to this channel once the publication is saved. While users may define narrowing constructs for any of their capacities, they will only be persisted if their associated checkbox is in fact checked.

The top-level OR is an implied indicator of how the combination of all of the defined (and ultimately saved as SUBSCRIBE grants) hierarchy entries will be evaluated. Each grant will be evaluated separately to determine if the authorization principal requesting authorization to subscribe to/view the channel can in fact do so. Authorization is thus allowed if any one of the grants succeeds, indicated by that implied OR.

Unrestricted (admin) Publish new Channel Use Case

The above use case outlines what a given user would see and the actions they can perform with respect to their capacities. This use case does not however indicate what a super user or Administrator would see. This particular case is shown in a modified version of the hierarchy that's applicable to the super user.

Assuming the user discussed in the previous use case was also an administrator, his hierarchy would look like that in the screenshot above. The addition of the Everyone group is an assumed capacity tied to administrators, which in the example is represented by the Public access group. This allows an admin to perform publishing actions w/out a limited capacity or restriction, yet also indicates the user's capacities by virtue of their other group memberships. With the availability of the audiences for the capacities that were used to publish the channel previously, the administrator could then modify one of those existing capacities if necessary. The user that had the capacity to begin with would then be able to see that changes made by the admininstrator.

Modify existing Channel Use Case

The previous section outlined the behavior of the channel hierarchy with regards to a new channel being created. This section will explore the details of modifying a previously published channel.

Let's assume that the user who initially published the channel chose to do so using the Senior Channel Publishers capacity granted via the first row in Table 2. This would have, in addition to the existing publish grant (ID #1) which already existed, created grant ID #3 as shown in the table below. The new channel that was created was assigned an id of 7:

A note on the null values within the columns of each row in the above table: The first row contains a Null in the REF_ID column because that grant entry does not have a 'controlling' grant that it needs to refer to. The Null in the second row indicates that the grant does not need/support a restriction.

Now, let's assume that a different user (another Senior) with an additional publish grant chooses to modify the channel. By virtue of his 'Senior' status, he has the grant ID #1, he also has grant ID #6:

When this user chooses the Audience workflow step of the channel publishing workflow, his hierarchy differs from the original in that it now includes a Content Publishers capacity (restricted to Content Recipients) in addition to the common Senior Channel Publishers capacity. The Senior Channel Publishers capacity is pre-selected to indicate that it is the current target audience of the published channel. Also, the narrowing criteria (Eyes=Blue) is displayed to complete the hierarchy.

Because the user editing the published channel is a member of the Senior Channel Publishers group, he is able to edit that particular capacity's hierarchy, thus affecting the users that the original publisher intended. However, if we assume that the user modifying that channel was not a member of the Senior Channel Publishers capacity, then he would not be able to modify that particular capacity (with the exception of an administrator), but would be able to still modify his own capacities, which is reflected in the next screenshot:

It may not be obvious what the differences between the last two figures are, but basically the icons related to all objects within the Senior Channel Publishers capacity are inactive, or grayed out. This allows the current user to see what the original intended audience of the channel is, but does not allow that user to affect the audience other than to those that he is allowed through his capacities.

Deleting an existing Channel

There are other aspects of an object such as a channel that can be affected by a user's granted permissions, including the ability to delete that object.

Object deletion authorization should be based on the composite set of capacities under which that object was published. This means that a user should not be able to delete an object such as a channel unless they have the entire set of capacities that have been selected during the publishing process.

Given the previously outlined use cases, the channel that was published on behalf of the Senior Channel Publishers capacity could only be deleted by a user that was a member of that capacity. If that channel was further extended to include another capacity for the targeting audience, then only a user with both capacities would be able to delete it. This would prevent the original publisher of the channel with only the Senior Channel Publishers capacity from later returning and deleting a channel that was also targeted to users based on the Content Publishers capacity that was added later. Hence they can essentially delete from the audience to which their capacity allows by revoking all grants to audiences of that capacity. But they can not affect members of another capacity's audience as would be expected.

Permission Grant Design

Permission grants will be restructured to support the ability to associate one permission grant instance, referred to as the 'controlled' grant to a grant instance that initiated its creation, referred to as the 'controlling' grant.

As noted, permission grants currently consist of the following attributes:

Grants will be enhanced to include the following attributes:

To further explain what the above changes are for and what they really mean, the following table outlines a series of permission grants:

Each grant restriction in the above table is described as:

ID - 1 Seniors can PUBLISH all channels to Prospective Students
ID - 2 Senior Math Majors can PUBLISH all channels to Math Majors.
ID - 3 Prospective Students with Blue Eyes can SUBSCRIBE to/VIEW channel 7. This is by virtue of this grant's link (REF_ID) to grant ID 1. The implied AND connection is made between the controlling grant (1)'s restriction and the controlled grant (3)'s principal.
ID - 4 Math Majors can SUBSCRIBE to/VIEW channel 7. This is by virtue of this grant's link (REF_ID) to grant 2. The controlled grant defines no further narrowing of the principal, so only the controlling grant's restriction is evaluated.
ID - 5 *Everyone with Blonde Hair can SUBSCRIBE to/VIEW channel 8. This is by virtue of this grant's link to the 'well-known' UNRESTRICTED group 0, which assumes that an administrator published the channel.

As noted in an early section, changes will need to be made to the UP_PERMISSION table used to store permission grants. These changes will amount to addition columns that reflect the new attributes that support grant restrictions (id, reference id, and restriction).

VERY IMPORTANT: A key aspect of the permission design is the link between a controlled grant and a controlling grant reflected in the REF_ID attribute. Creating this link allows the capacity to be extracted from the controlling permission grant as well as the separation of the top-level restriction from the narrowing scope. These are all artifacts that need to be available to the filter hierarchy when displaying the individual capacities.

Interface/Implementation Changes Necessary to Support Restrictions

The following uPortal interfaces and implementations will need to be udpated to support the addition of grant restriction attributes. The question is, do we update the existing interfaces, which would obviously cause problems for existing installs that may have their own implementations of these interfaces, or do we extend the interfaces? Extending the interfaces would allow the introduction of the grant restriction feature without affecting existing installs, which would then neccessitate that any code wishing to use the new interfaces perform type checking to determine which interface it is using.

org.jasig.portal.IPermissible

Implementations of IPermissible will need to be able to indicate which activities they expose are able to act as controlling activities, thus allowing for the creation of a controlling permission grant. Additionally, they will need to also indicate if a given activity supports restricting. This will allow applications such as the Permissions Manager Channel to present the appropriate workflow based on an activity's ability to support (or not) restricting (i.e. PUBLISH would support restricting while SUBSCRIBE would not). Thus, the IPermissible or extend interface (TBD) needs to provide the following methods:

/**
  * Returns an array of activities that the supplied activity controls or null.
  * @param activityToken the activity to check for controlled activities.
  */
public String[] getControlledActivityTokens(String activityToken);
/**
  * Indicates if the supplied activity supports restricting.
  * @param activityToken the activity to check restriction support for.
  */
public boolean supportsRestrictions(String activityToken);

org.jasig.portal.security.IPermission

As outlined previously, the grant represented by the IPermission needs additional attributes that allow it to indicate its unique id so that if necessary, it can be referred to by another grant, its optional restricted audience key, and the optional reference id that is used to refer to a controlling grant. That said, the IPermission or an extended interface (TBD) needs to provide the following methods:

/**
  * Returns the unique id of the permission grant instance.
  */
public Integer getId();
/**
  * Sets the unique id of the permission grant instance.
  * @param id  the unique id of the permission grant.
  */
public void setId(Integer id);
/**
  * Returns the key of the restricted audience for the permission grant instance or null.
  */
public String getRestriction();
/**
  * Sets the key of the restricted audience for the permission grant instance.
  * @param key the key of the restricted audience.
  */
public void setRestriction(String key);
/**
  * Returns the reference id of the controlling permission grant instance or null.
  */ 
public Integer getReferenceId();
/**
  * Sets the reference if of the controlling permission grant instance.
  * @param id the id of the controlling permission grant.
  */ 
public void setReferenceId(Integer id);