uPortal Permissions and Error Handling

In which I describe uPortal's support for permissioning, using access control on technical information about error conditions as an example.

Channel Error Handling in uPortal

When a channel or portlet experiences an error condition in uPortal, the framework replaces it just-in-time with an instance of the error channel, a component for rendering and optionally affording response to error conditions.

For instance, here's what it looks like when an unprivileged end user views some news feeds that are unavailable. (I created this error condition by running uPortal on my laptop disconnected from the Internet such that it could not retrieve the feeds (not even once to cache them)).

In the default configuration, there's a uPortal-local group named Developers which has been granted the privilege of seeing the technically detailed views on error conditions. Here's what it looks like when a user with privilege to see technical error messages views these same failing channels.

The technical view on error messages identifies the failing channel, categorizes the error, and provides in-browser access to the stack trace of the immediate cause of the failure.

Configuring the privilege

Let's suppose that you'd like to privilege another group to also see the detailed error messages. Sufficiently privileged users (e.g., the Portal Administrator) can configure this permission using the permissions manager channel.

This channel manages permissions of several systems which register manageable permissions with it. The systems registering the permissions are called "owners" (they "own" the application domain of the permissions they register). The initial view on the Permissions Manager invites the administrator to select one or more owning systems the permissions of which to manage. (The Columbia Announcements Channel, for instance, makes additional use of the Permissions Manager uPortal component for managing permissions on announcements topics.)

The relevant owning system in this example is the CError channel. Having selected it, the next step is to choose which Principals to manage in the context of this system's permissions. Principals are users or groups (where groups may be used to represent groups of users or may be used to represent roles.) By default, the principals already granted or denied this permission are selected.

Here, I've selected the Support Staff group in addition to the Developers group.

Having selected these groups, I can then configure whether they are granted or denied this permission. I can also choose to have nothing to say about a particular group's having this permission.

If a permission has been granted or denied to a parent group such that configuring a child group is redundant or contradictory, the channel will tell me so. Here I've granted this permission to Staff, of which Support Staff is a sub-group, so the UI tells me that even if I don't explicitly grant Support Staff the permission, it will inherit permission from above.

After Support Staff has been granted permission to see technical views on channel error conditions, when a user who is a member of the Support Staff group views this tab, here's what he or she will see.

Non-UI ways to manage permissions

The administrative channel shown in this blog post isn't the only way to configure permissions in uPortal. Permissions are importable and exportable via the command line tooling included. The permissions system is an implementation of a pluggable API -- if you'd like to connect up uPortal to something else to determine some or all of the permissions, the APIs support that.

Tips for configuring this permission in testing environments

One common configuration change to make to your uPortal instance in development is to privilege the Guest user (representing the behavior of the portal prior to authentication) to view the detailed technical information on error conditions. This eases troubleshooting in a development environment. It often makes sense to privilege Everyone to see technical error messages in testing environments, so that whereever a channel fails a more informative message is more immediately available.

Errors are also logged

The detailed error view in-browser is only a convenience -- the error conditions are also being logged via log4j (abstracted by Commons Logging).

PS: The screenshots in this post are taken from a uPortal 3.0.1 quickstart environment.