Grouper Developers Forum

["Minh N. Nguyen" <>]

This write-up is a summary of my investigation into a Subject-like API 
which could be used by Grouper and Signet.

Background
--------------------
Functionally, a Subject is a generic representation of an entity, such as a 
person, a group, or an application.  These entities may be used in Grouper 
and Signet in the following context:
- as the user of the web applications
- as a member in a group
- as the grantor/grantee of a privilege assignment
- entity's attributes are used as criteria of a condition for an 
assignment, e.g. while person has a "member" affiliation

From a technical perspective, the Subject API provides an abstraction 
layer so sites can plug-in their local implementation to their Subject data 
source.


Requirements
--------------------
In various Grouper and Signet discussions, we've identified the following 
requirements:
R1. A subject must have a unique ID, display name, and description
R2. Retrieve a subject by its type and unique ID
R3. Find subjects by various criteria
R4. Find subjects by "whois-like" unstructured query
R5. Obtain site-specific subject attributes
R6. Perform externalID to subjectID mappings to benefit loaders, 
provisioning connectors, and user interfaces
R7. Passing the querier's subjectID to the adapters so that they can apply 
access control policy to constrain subject lookup & search.  (I'm not sure 
this is a "hard" requirement since we did not agree whether this capability 
should handled by the Subject API or via an external wrapper.)
R8. The API must have abstract classes or interfaces defined
R9. A mechanism to load an implementation of the API at runtime


Analysis
--------------------
I looked at the following Java libraries to see if they supported a 
Subject-like API:
- Java Authentication Authorization Service (JAAS)
- OpenSAML
- uPortal
- Agent OSID 2.0

JAAS is a set of APIs that is used to authenticate users and control access 
to resources.  The "java.security.auth" package in JAAS contains a Subject 
class which represents a grouping of security-related information for an 
entity, such as identities and credentials.  The Subject class, however, 
does not have defined fields for other non-security attributes.

OpenSAML provides Java classes and methods to get subjects and their 
attributes from SAML messages.  A SAML AttributeStatement can be used to 
assert any attribute associated with a subject.  SAML places no restriction 
on the kinds of attributes that can be included in an 
AttributeStatement.  Unfortunately, SAML only specifies SOAP bindings which 
would mean that Grouper/Signet sites would not be able to use other 
protocols, such as LDAP or SQL drivers, to get subject data.  Technically, 
OpenSAML can support other bindings, but I don't know if there are plans to 
support this.

uPortal's "org.jasig.portal.groups" package contains an IEntity interface 
which is designed for differentiating whether a member of a group is an 
entity or a group.  As such, this interface does not support many of the 
above requirements.

Of the four libraries, the Agent OSID most closely meets Signet and 
Grouper's requirements.  It contains:
- an Agent interface which is a generic representation of an entity that 
includes id, displayName, and properties (akin to our attributes)
- a Type abstract class for categorizing agents
- an AgentManager class for searching, creating, and deleting Agents
While the Agent OSID contains many of the needed functionalities, it does 
not support R4, R6, and R7.  This leaves us with a few options:
- drop R4, R6, and R7 and adopt the Agent OSID,
- work with the OKI folks to add functionalities that we need, or
- define a sub-interface that extends the Agent OSID with additional features
Besides not proliferating the Java community with yet another API, adopting 
the Agent OSID would allow sites that already have an OSID implementation 
to reuse it in Grouper and Signet.  This sounds good on paper, but I don't 
know of any Agent OSID 2.0 implementation, so we couldn't realize this 
benefit in the near term.


Recommendation
--------------------
In the interest of keeping the Grouper and Signet development moving 
forward, I'm leaning towards continuing to develop our own Subject API, but 
keeping the functionality to a minimum. At the same time, we should keep an 
eye on the evolution of the Agent OSID and see if we can participate in 
shaping it for our needs.  If this relationship is successful, we can then 
swap Subject API with the Agent OSID.


--Minh