Results API - Access Control

This document describes a proposed solution to implementing Access Control for the Results API. Note the description aims to be generic, referring to result sets as a single collection of various data and information of interest and users as simply an actor accessing the 'result set'. The primary core concern is the connection of Dashboard to the Results API to produce the Survey Dashboard, however the following discussion is devoid and independent of the Dashboard.

Tier System

Using an ACL, each user can belong to 1 group only. A user accessing a result set can come from a more diverse background, he may be an anonymous user, he may belong to various Assignment Groups, and he may be a co-admin of as survey. Access to results based on the security group would be unsuitable. Users and Assignment Groups are in a many-to-many relationship, which cannot be modelled using ACL trees.

The proposed Tier System works as follows. Any human on this world will belong to exactly one Tier with respect to a given result set. These Tiers would be:

Tier 1: Anonymous users
Tier 2: Invited participants who have not yet completed the survey
Tier 3: Invited participants who completed
Tier 4: Users with given access to the result set, (e.g. having "allow" for "read" operation of "sSurveyResults::$survey_id")
Tier 5: Result set owners / superusers

Each Tier then contains a setting (Tier Number), which is an integer acts as a bitfield (= set of boolean flags), which define the access. Note that each Tier only describes the category of users and how to classify them, it does not dictate what or how the results can be accessed. That is up to the Tier Number.

The advantage of this is that because the number of tiers is fixed, we can simply attach an array of 4 integers (Tier 5 assumes full access) to the result set, describing the settings for each in a concise way.

Some scenarios to clarify (these use real LS2 objects):

Scenario 1:

1. An outside user would like to view results of a specific survey, through the Survey Dashboard
2. He points his browser to the desired URL
3. The dashboard, using a provided function, determines that the user is anonymous (e.g. he's not logged on) and hence Tier 1
4. Dashboard now contacts the Result API, asking for information available for Tier 1 users related to the survey in question
5. Result API looks at the survey and retrieves the Tier 1 Number. Say it's 13 = 8 + 4 + 1. This can for example mean that access is given to information denoted by 1, 4 and 8.
6. The dashboard displays only those widgets, that display the above information

Scenario 2:

1. A registered user would like to view results of the same survey, through the same Dashboard
2. He points his browser to the same URL
3. The dashboard, again with the help of a helper function, notices that this user has been granted access to the Survey results (through ACL), by the survey owner
4. the helper function also finds the user is not the survey owner and concludes this user belongs to Tier 4
5. Results API looks up the Tier 4 Number and say it's 15 = 8 + 4 + 2 + 1.
6. This user can thus view the same things as an anonymous user, plus some extra bits denoted by the 2 flag.

Scenario 3:

1. A participant, belonging to the Assignment group X, would like to also view these results
2. He is classified as Tier 3, as he has been assigned this survey and he has completed it. (He also does not have ACL access to the survey results, so he can't be Tier 4)
3. Tier 3 Number may enforce the user only to view results of his own Assignment group only
4. Appropriate data is displayed.

Note that in Scenario 3, different users from Tier 3 may see different information (depending on what Assignment Group they belong to), though they come from the same Tier. This if implemented as proper ACL, would take lots of ARO and ACO entries and would slow down the system

Conclusion

The main idea is: fixed number of Tiers; use bitfields to store settings for each Tier; An array of 4 integers per result set.

---