Incapture Technologies

Inside the Cloud

Incapture Technologies Blog

 

Entitlements

Published:
November 19, 2014
Author:

A very important part of any platform environment is the means by which users of the platform are given privileges to perform actions on the platform. Rapture has an entitlements system that provides this function.

Within Rapture everything that takes place is coordinated through an API call – even internally larger “meta” api calls in turn call lower API calls to make their activity happen – nothing in the system bypasses this mechanism. As an example, creating a Reflex script in Rapture actually involves (lower down) saving content to a special internal document repository – and the means by which that takes place is by calling the “putContent” API call for document repositories.

Also every user in Rapture, once logged in, has a concept of a “context” – this is server side state (shared with all Rapture instances) that identify the user associated with a given request in a secure way. This context is always passed (internally) through every API call made in Rapture.

Rapture’s entitlements system works at the API level and by the concept that users can be part of functional entitlement “groups”. The concept of “an entitlement” is a function of the API call being made and the parameters to that API call. It’s best illustrated with an example:

In an earlier post we talked about the API to Rapture and the fact that the API was template based and a process autogenerates both server side and client code. Here is an example of a single call in this template language in all of its glory:

[Store a document in the Rapture system. The new URI name is returned; 
  this allows parts of the new name to be automatically generated]
    @entitle=/data/write/$f(docURI)
    @public String putContent(String docURI, String content);

In this example we are defining the function “putContent” in the document (doc) api. The important line for this discussion is

    @entitle=/data/write/$f(docURI)

This instructs Rapture to check for the “entitlement” that is made up of the prefix /data/write combined with the document URI parameter. So, if we were calling the function like this:

    #doc.putContent("//test/london/one", ...);

The entitlement to check would be:

    /data/write/test/london/one

Rapture now looks for the most specific entitlement that matches that string. By that it checks entitlements in the following order:

/data/write/test/london/one
/data/write/test/london
/data/write/test
/data/write
/data

If it finds a match for that entitlement it looks at which entitlement groups are associated with that entitlement and then sees whether the calling user is a member of any of those groups. If they are the API call can proceed as normal. So in this way the naming of entities and their structure can be important in a Rapture environment if you wish to use this structure to assist in proper partitioning of roles. In the example above the document was named “//test/london/one” with an implication that perhaps an entitlement group called “London” could be part of an entitlement “/data/write/test/london” and only members of that group could write documents below that part of the naming hierarchy.

The final piece of entitlements is how they are created and managed. Rapture provides some User Interfaces to manage these entities but these are simply using the “entitlements” api. Of course the entitlements api is controlled through entitlements as well and there are specific checks in some of these api calls to ensure that a call to an entitlements api doesn’t revoke all access and produce an irreversible outcome! The api is really a “CRUD” api across entitlements and entitlement groups:

[Entitlements are a very important part of the security of Rapture, and the Entitlement api is the way in which information about this entitlements is updated. The api is of course protected by the same entitlements system, so care must be taken to not remove your own entitlement to this api through the \emph{use} of this api.

Entitlements work like this. Users can be members of entitlement groups, and entitlement groups are members of entitlements. Each api call within Rapture is associated with an entitlement path, and when a user wishes to execute that api call they are checked to see if they are a member of that entitlement (by seeing which groups they are members of). Some api calls have dynamic entitlements, where the full name of the entitlement is derived from fundamental concepts such as typename, displayname, queuename etc. If an entitlement with the specific name exists that is used, otherwise the full entitlement path is truncated one part at a time until an entitlement is found.]

api(Entitlement) {
    @entitle=/admin/ent
    @public List(RaptureEntitlement) getEntitlements();

    @entitle=/admin/ent
    @public RaptureEntitlement getEntitlement(String entitlementName);

    @entitle=/admin/ent
    @public RaptureEntitlement getEntitlementByAddress(String entitlementURI);

    @entitle=/admin/ent
    @public RaptureEntitlementGroup getEntitlementGroup(String groupName);

    @entitle=/admin/ent
    @public RaptureEntitlementGroup getEntitlementGroupByAddress(String groupURI);

    @entitle=/admin/ent
    @public List(RaptureEntitlementGroup) getEntitlementGroups();

    @entitle=/admin/ent
    @public RaptureEntitlement addEntitlement(String entitlementName, String initialGroup);

    @entitle=/admin/ent
    @public RaptureEntitlement addGroupToEntitlement(String entitlementName, String groupName);

    @entitle=/admin/ent
    @public RaptureEntitlement removeGroupFromEntitlement(String entitlementName, String groupName);

    @entitle=/admin/ent
    @public Boolean deleteEntitlement(String entitlementName);

    @entitle=/admin/ent
    @public Boolean deleteEntitlementGroup(String groupName);

    @entitle=/admin/ent
    @public RaptureEntitlementGroup addEntitlementGroup(String groupName);

    @entitle=/admin/ent
    @public RaptureEntitlementGroup addUserToEntitlementGroup(String groupName, String userName);

    @entitle=/admin/ent
    @public RaptureEntitlementGroup removeUserFromEntitlementGroup(String groupName, String userName);
}

Rapture also has the concept of dynamic user membership of groups. In this case the membership of groups can be delegated to a user (well, developer!) defined class that can potentially reach out to an external system to determine that. An example of where that is used with our system company Incapture Investments is where we want to be explicitly sure that the user making a request for data that originated from Bloomberg is made by a user that is actually logged into Bloomberg at that point. Other uses could include using an external LDAP directory for group membership.

A simple real world example will help close up on entitlements. The screenshot below shows a number of entitlement groups used in a particular Rapture deployment – with functional groups of users being assigned read rights to parts of the data environment :

Entitlements

As before – if you’d like more information about Incapture or Rapture please drop me a line personally or to our general email address info@incapturetechnologies.com and we will get back to you for a more in depth discussion.


Subscribe for updates