Implements and manages the "role-based authorizations" used by the Systems Insight Manager Central Management Server.

Systems Insight Manager supports two separate security models.  The first model is called "role-base authorizations" and is used to grant authority to manage the target nodes/devices discovered by the Systems Insight Manager Central Management Server (CMS).  The second model is called "user privileges" or "user CMS access rights" and is used to grant authority to manage the objects in the CMS database.  This package provides the implementation of the first model, "role-base authorizations".

Systems Insight Manager provides the capability to create and manage "role-based authorizations".  In this specification they will simply be referred to as authorizations.  The objects used to grant "authorizations" are implemented as sub-classes of the MxAuthorization class, MxNodeAuthorization and MxNodeGroupAuthorization.

Architecturally, an authorization is the association of three primary objects from the database: a user, a toolbox, and a target.  Each authorization has a globally unique identifier (GUID) that provides a unique key to persist the authorization in the database.  There is no name associated with an authorization.  It is only defined by the three objects associated with it.

Logically, authorizations specify that a CMS user may apply the tools contained in a toolbox to a target.  A toolbox is associated with a set of tools that are being authorized to be executed by the user.  A target includes a discovered node or device ("System" in the Authorizations UI), or a custom defined group of nodes/devices ("System Group" in the Authorizations UI).

User  +  Toolbox  +  System  =  System Authorization
User  +  Toolbox  +  System Group  =  System Group Authorization

Note: As of Systems Insight Manager 4.1 only a user is supported in authorizations.  In some future release a subject may replace a user to allow authorizations to apply to any subject in the database.  Where a subject would become a user or a trusted application or other objects that might need to have authorizations assigned to apply tools on to targets.

Authorizations are persisted in the database.  The CATEGORY_NAME data member of the base classes and subclasses name the database table where the class attributes are stored and the PERSISTENT_ATTRIBUTES String array of the base classes and the subclasses show the list of attributes that are persisted in the corresponding tables for each of the classes: MxObject, MxAuthorization, MxNodeAuthorization, and MxNodeGroupAuthorization.  The MxObject contains the unique GUID for each authorization and a NULL name.  The MxAuthorization class contains the common elements of all authorizations, the MxObjectID of a user and the MxObjectID of a toolbox.  The MxNodeAuthorization adds the MxObjectID of a node to complete a node authorization.  The NxNodeGroupAuthorization adds the MxObjectID of a node group to complete a node group authorization.

The MxAuthorizationManager is a singleton class whose single instance is created within the Domain Manager JVM to maintain an in-memory cache of all the authorization objects in the database.  The MxNodeAuthorizationCache and and MxNodeGroupAuthorizationCache classes maintained the two sub-classes of authorizations as separate lists, which are kept synchronized with the database.  The Authorization Manager also maintains a number of keyed data structures derived from the contents of these two caches: MxAuthInfoQueryEngine, MxNodeToToolBoxSet, and MxNodeToToolBoxSetTableForUser.  The two internal caches extend the Observable class to allow the integrity of the derived data structures to be maintained by being notified whenever a cache is modified via add or delete operations.  There is also a special method on the MxAuthorizationManager class named updateAuthorizationInfo() that is called externally when a node group's list of node members is modified.  This method triggers the observers of the node group cache to update their content.

A derived node authorization table is also created in the SQL database in order to allow the authorizations to be used in SQL queries. In the same manner that the derived keyed data structures need to be refreshed when the authorizations lists are changed, this database table must also be reconstructed. This operation is also invoked through the same updateAuthorizationInfo() method.

TODO: The updateAuthorizationInfo() method is actually called much more often.  It is called whenever any user, toolbox, node, or node group is renamed or modified in order to force the derived keyed data strucures to rebuild because many of the keyed data structures use the names of the user, toolbox, or node in the authorizations or the derived authorizations.  This can cause much volatility of the derived data structures during discovery.  The derived data structures should all be re-factored to use the GUID (MxObjectID) to key the data structures, instead of using the MxObjectName sub-class.  If this is done, then all the calls to\ updateAuthorizationInfo() from the modify*() methods of the various user, toolbox, and node controllers could be removed and we could again limit the method to only be called when the node group member list is modified.

During the add of a new authorization object, the Authorization Manager verifies that the user, toolbox, and node or node group elements (object IDs) referenced in the new authorization all exist as current objects in the database. 

When the various controller classes for the objects referenced in an authorization are instructed to delete an object they control, they are responsible for first telling the Authorization Controller, MxAuthController, to delete all the authorizations that reference that object. This must be successfully executed before the controller can proceed to have their associated manager delete that object.  To make this easy the Authorization Manager provides many convienience methods for deleting all the authorizations that contain a specific user, toolbox, node, or nodegroup object ID, which are called by the Authorization Controller.

The Authorization Manager cannot be restored from the repository until after the managers of its associated objects have been restored. This is necessary because the Authorization Manager validates the authorization object to ensure that the authorization object’s components still represent real objects that exist in the repository. If any of the components no longer exist the authorization object is removed from the cache and repository.

The Authorization Manager provides the capability to determine if a specified user is authorized to execute a specified tool on a specified list of targets. It determines this authorization by attempting to assemble a set of existing authorization objects that consist of the specified user, each of the specified targets, and any toolbox associated with the specified tool. Please note that the Authorization Manager does not have to authorize the user with the same toolbox on every target. It will search for a toolbox with the specified tool on a specified target. Different toolboxes may specify the same tool on different targets. If Authorization Manager can assemble a set of authorizations from the derived cache that meet this criteria, the user is authorized; otherwise, the user is not authorized.  The primary methods for this are boolean isTaskRunnable( MxRunnableTask theRunnableTask) and boolean isUserAuthorizedForTool(MxTool aTool, MxUser aUser)

The Authorization Manager and Controller provide services to controllers to allow them to retrieve objects based on authorizations. For instance, it allows controllers to retrieve the list of targets on which a specified user can execute a specified tool.  An example of this API would be as follows:

List listNodeNamesForUserByToolBox( MxObjectID userID, MxObjectID toolboxID);

The above authorization manager method will accept an MxObjectID object of a user and an MxObjectID object of a toolbox and return a List of MxNodeName objects on which the specified user is authorized to run the specified tool.

A set of authorization filters derived from the MxAuthFilter base class provide a generalized way to query any filtered lists of authorizations through one simple method List listAuthorizations( MxAuthFilter filter ). This allows a relevant set of authorizations to be filtered on any one or two components of the authorization.

Related Documentation