Page Comparison

\- 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).

h2. Straw man design


h3. 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 'Location' permission to the location field of the Layer entity.  To control download ability on a Layer, we control whether a user has the "Location' permission on the Layer.






h3. Workflow Model


h4. Design Assumptions


h5. Things the client should not 'know'

\- what requirements need to be met to access a Layer's location (e.g. you need to sign a EULA)

\- what requirements have/have not been met by a User (e.g. whether a EULA has been signed)


h5. Things the client SHOULD 'know'

\- 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)

\-

h4. Design Approach

The permissions-requirements service


\- Add a new service 'permissionRequirements'. E.g. GET /permissionRequirements/101, where '101' is an entity ID, would return a response of the form

{code}
{

    Location:[ {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}]
}
{code}

The response lists the unmet requirements for each permission associated with the object, in the form <permission>:<requirement-list>.

(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"} 


\- The response to a request for any entity may omit fields for which a user lacks permission.  In this case, or if the entire entity is denied (e.g. a 401 is returned), and if there is some *way* to obtain access, then the response's header has the URI for a /permissionsRequirements request.

\- To make queries fast, we can omit this header info from query responses, just include it in responses to CRUD requests on individual objects.





h4. Tier 1 Approval Process

Here the user signs the Tier 1 agreement upon account creation and is added to a "Tier 1 group".&nbsp; The group has the Download role for all Tier 1 data layers.

"WF" refers to an envisioned workflow system which knows the approval workflows and can tell each participant what its next step is.
|| Version 1: Synapse interacts with User.&nbsp; This is not feasible since the User-Synapse interaction is synchronous while the Synapse-WF interaction is meant to be asynchronous (at least for the SWF workflow system). \\ || Version 2: Synapse starts workflow; Worker interacts with User via email \\ ||
| !tier 1.png|border=1!\\ | !tier 1 with worker.png|border=1!\\ |


Below we see an alternative for synchronous user interaction.


h4. 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.&nbsp; Upon approval Synapse adds the User to the Access Control List for the Layer.

The following variation has the properties that (1) interaction between Synapse and the User is synchronous, (2) there is no representation of the required workflow in the client, (3) there is no representation of the workflow \*state\* in the back end: !synchronous approval.png|border=1!
This approach is based on the pattern used by "Basic Authentication", e.g. [http://httpd.apache.org/docs/1.3/howto/auth.html#basicworks

]
in which a request can be denied, the denial containing information about what's required for the request to be approved.

Note:

  the "/accessRequest"

 service  'knows' to check that eula 456 is signed before adding user to group 789

changed services:

    GET /layer: has to check whether there is an approval process and, if so, include the final step in the rejection

new services:

    /accessRequest: checks precondition; can (1) add user to group or (2) add Role to

 User
    POST /approvalProcess: creates an approvalProcess object whose parent is a Layer

 and
        whose content is the sequence of requests that need to be fulfilled (specific to the layer)
    POST /accessRequirements: creates an object containing the requirements for adding a User
        to the ACL for an entity (e.g. the user must have signed a certain EULA)

Design considerations:

    System does not track the 'state' of the approval process. That's left to the client.

  The risk  is that the process might have to start over if it fails partway, but the benefit is in simplifying  the server.


How do you set up an approval process?
    POST /accessRequirements
    POST /approvalProcess

How do you revoke approval?
&nbsp;&nbsp; &nbsp;1) remove the <User, Role> from the layer's ACL (or the <Group, Role> if all the users were added to a group)
&nbsp;&nbsp; &nbsp;2) delete the approvalProcess and accessRequirements objects


h4. Tier 3 Approval Process

Here we have the added complexity of an external IRB.&nbsp; An "IRB daemon" is added to send approval requests to the IRB and to listen for replies.&nbsp; The interaction with the user is asynchronous:&nbsp; While waiting for approval the user may do other things (though not access the requested layer).&nbsp; Finally she receives an email saying the request was approved.


!tier 3.png|border=1!


h4. Some open questions:

\- How does Synapse know not to wait for any more steps, once it gets the final reply from WF (the workflow is not yet done)?

\- When Synapse asks "next step" can it refer to a specifc workflow instance (and avoid getting an approval step for some other user)?



h3. New/Modified Synapse Services

Request account (initiates tier 1 workflow as a side effect)

Download access request (initiates tier 2 or tier 2 workflow as a side effect, depending on the layer)

Sign tier 1 agreement

Sign tier 2 agreement

IRB approval of submitted request