Background
- Data layer access in Synapse requires one or more approval steps.
- In Synapse granting data access is synonymous with providing the URL to the stored data.
(This URL may have an embedded access token.)
- Currently (i.e. as of Jan. 2012), the backend has a representation of EULAs and of Agreements (i.e. that a particular user agrees to a EULA)
- The work flow logic for creating the agreement is embedded in the Web client, so other clients would have to maintain duplicate logic.
- There is no provision in our permissions scheme for an "IRB role" which can grant or revoke 'download permission' to a user.
- If the approval process changes, a user who has already been approved needs to go through the approval process again.
- Currently we've identified three tiers of access restriction/approval:
Tier 1: User agrees to a generic EULA that applies to all data layers available through Synapse.
Tier 2: (Tier 1) + User agrees to a second EULA specific to certain data layers.
Tier 3: (Tier 1) + (Tier 2) + User access must be requested/approved through an institutional review board (IRB).
Design
Security Model
- In the entity schema we allow a field to have a (some?) permission(s) which a user need to have before the field can be accessed.
- We add a 'Download' permission to the location field of the Layer entity. To control download ability on a Layer, we control whether a user has the "Download' permission.
Workflow Model
Design Assumptions
Things the client should NOT 'know'
- what requirements need to be met to obtain a permission (e.g. you need to sign a EULA to access a Layer's location)
- what requirements have/have not been met by a User (e.g. whether a EULA has been signed)
Things the client SHOULD 'know'
- how to determine, from an entity's schema and from the repository authorization services, that a permission is needed to access a certain field of a certain entity. (The alternative is to add a service to do this.)
- how to fulfill a requirement (e.g. if a EULA needs to be signed, knows how to retrieve and display the EULA, get it signed, and submit the appropriate request to the repo service)
Design Approach
The permission service
- Add a new 'permission' service which (1) grants permissions if requirements are met or (2) otherwise reports what requirements need to be met. E.g. POST /layer/101/permission/Download, where '101' is an entity ID, would either (1) grant the requested permission (Download) if the user meets the requirements or (2) return a (401) response with a body of the form
{
[ {type:EULA, params:{uri:/eula/987}, msg:status-msg}, {type:EULA, params:{uri:/eula/654}, msg:status-msg}, {type:ACT, params:{uri:/act/321}, msg:status-msg}]
}
listing the unmet requirements.
(Optionally, just one of multiple unmet requirements could be returned, allowing the server to control the order in which requirements are considered by the client.)
There are three parts to a requirement:
- type: from an ENUM, e.g. 'EULA', 'ACT'.
- params: a map of parameters used by the given 'type'. The client needs to know what to do for each enum, and how to use its parameters. This will be documented in the developers' API.
- msg: An optional status message, suitable for display to the user.
If a requirement has no type or params but has a message, then there is nothing for the user to do and the message helps explain why, e.g. {msg:"ACT approval pending"}
Permission Manager
The repository service will have a Permission Manager, which computes the response to the permission request from a given user for a given entity. E.g. if a Layer required EULA 987 to be signed for a user to access it, and EULA 987 is not yet signed by the user, then the Permission Manager adds this requirement to the response to thepermissions request. The unmet requirements are stored *implicitly* in the state of the repository services, and the PM determines the unment requirements upon request.
Object Model for Permission Requirements
An entity may have Requirement child entities (or should these be properties of an entity?). These entities (properties?) contain the details of what is required to obtain specific permissions on the object (e.g. <Download,EULA,/eula/987>). The PM refers to these entities (properties?) to make its assessment.
Additional Services
- requirements CRUD services: allows the owner of an object to craft requirements for an object (or should this be rolled into the current permissions management?)
Tier 1 Approval Process
Here the user signs the Tier 1 agreement upon account creation. (Omitted are the steps in which the client retrieves the schema and the current ACL to determine that the user doesn't have the necessary permissions.)
Tier 2 Approval Process
This approval requires two hurdles, the Tier 1 agreement plus a new agreement which may be specific to the requested layer. 
How do you revoke approval?
1) remove the <User, Permission> from the layer's ACL.
2) delete the permission requirement from the entity.
Tier 3 Approval Process
Here we have the added complexity of an external ACT. An "ACT daemon" is added to send approval requests to the ACTand to listen for replies. The interaction with the user is asynchronous: While waiting for approval the user may do other things (though not access the requested layer). Finally she receives an email saying the request was approved.