== Authentication and Authorization module ==

The AuthModule is setup to provide
* user registration and login 
* an adminstration panel to group users and set user/group permissions (a.k.a class level security).
* enable users to specify per object if they want to share (a.k.a. row-level security)
== User stories ==

[[TOC(AuthModule/UserStories,notitle,inline,noheading)]]

In tickets:

[[TicketQuery(component=auth&group=status&type=enhancement)]]
== Requirements list ==
=== Authentication ===
 * Forms of Authentication:
  * Database (user-pass) (must)
  * OpenID (could)
  * IP-based (could)
  * LDAP-based + specific flavors like RUG and UMCG login (should)
 * Registration of users includes email verification (must)
 * Users should be able to login and logout (must)
 * Users should be able to change their passwords (must)
 * Make implementations of Login singletons so that they can be accessed everywhere (must)
=== Authorization ===
 * Resources are tables, rows, columns, query-sets (e.g. only the Lengths in rows where Length > 1.80m), files (for pipelines)
 * Subjects are users, groups, public users (unauthenticated) and exactly one administrator
 * Permissions include read, write (also implies delete), execute (for pipelines) and ownership
 * Modifying (insert, delete, alter) a column is not supported.
 * Modifying a row needs write rights on the row.
 * Resources must have exactly one owner; this can either be a user (must) or a group (should). The latter option is not preferable for us and needs to be set explicitly by the administrator.
 * Permissions are provided for resources x subjects. (must)
 * The administrator has all permissions excluding ownership on all resources. (must)
 * Authenticated users can request permissions for resources. Requests are sent to the user or group with ownership rights of the resource. (must)
 * Groups can be created by users who have write rights on the MolgenisGroup table. The administrator is the owner of the MolgenisGroup table and can delegate rights to other users. (must)
 * In case of an UpdateDatabase all permissions are reset (except for administrator).
 * The public user has by default no reading permissions on any resource, unless explicitly set by the administrator. (should)
 * Administrator can pass on permissions from parent tables to child tables and between xref-linked tables with a toggle button. (should)

=== Example ===

''Table: !ObservedValue''

|| || read || write || execute || ownership ||
|| User1 || x || x || x || x ||
|| User2 || x || || x || -(?) ||
|| Group1 || || x || || -(?) ||
|| Group2 || x || x || x || -(?) ||
|| ... || || || || ||
|| Admin || x || x || x || - ||

== Low-level specifications for the Authorization module ==
Goal: to have a first version of the Authorization module that fulfills at least the 'must' requirements.

=== Static permissions: entity and field level ===

The expected user interface is a switch board were the admin can tick which entities, fields or screens the user has permissions on.
For example: 
{{{
Role: lab worker

Permission:
Entity             Read     Write   Execute  Ownership
Investigation      [x]      [ ]     [ ]      [ ]
Sample             [x]      [x]     [ ]      [x]
etc
}}}

Proposed solution:
 * Users will be stored in the !MolgenisUser table. Furthermore, there will be one Administrator and one Public User.
 * Table rights: these will be managed through a new bridge table in which each row links to a !MolgenisEntity (through its name) and a !MolgenisUser. There will also be a field 'rights' that details the kind of authorization (an enum consisting of read, write, execute and owner). This way we can achieve many-to-many relationships.
 * Column rights: these we can achieve through an extra, optional field in the Table rights table. This field can contain a name of a field (column) in the table in question. If none is supplied, the entry is supposed to hold for all fields in the table. If one is supplied, the entry is supposed to hold only for the specified field. There can be multiple entries in the bridge table for a certain table. In that case, the more detailed entries (about columns) take precedence over the more general ones (about tables as a whole).

Proposed solution (rewritten to see if we understand each other):
* !MogenisEntity and !MolgenisField and !MolgenisScreen are subclasses of !MolgenisElement. [[BR]]Thus we have an extensible way to define elements we want to set permissions on.
> Q: Do we really need to distinguish between !MogenisEntity and !MolgenisField and !MolgenisScreen? Why not simply add further fields to MolgenisEntity?
>> A: Yes, use !MogenisEntity and !MolgenisField and !MolgenisScreen because we have them anyway as part of Molgenis.
* !MolgenisRole can have zero or more !MolgenisPermission, with each permission being a tuple [role: xref->MolgenisRole, element:xref->MolgenisModelElement, permission: enum[read,write,execute,ownership]]. [[BR]]Thus we can assign permissions to role
* !MolgenisUser extends !MolgenisRole with password to enable authentication. [[BR]]Thus we can easily assign permissions to an individual.
* !MolgenisUser can have multiple !MolgenisRole and !MolgenisRole can have multiple !MolgenisUser. [[BR]]Thus we can easily assign a set of permissions to multiple individuals.
> Q: Why could !MolgenisUser's have multiple !MolgenisRole's, i.e. why is the relation between !MolgenisUser and !MolgenisGroup not enough?
>> A: For the beginning rename MolgenisRole to MolgenisGroup. Extend MolgenisUser from MolgenisGroup. Make mref from MolgenisUser to MolgenisGroup.
* there will be one Administrator and one Public User.
* For each individual the total set of permissions is calculated and narrower permissions overrule broader permissions (e.g. entity permission implies permissions on all fields, ownership implies read and write]

Decisions:
* permission field in MolgenisPermission could be xref instead of enum. Advantage: open ended. Drawback: harder to program.
> R: Enum will be used, because set of permissions is static.
* !MolgenisElement could be made generic so you don't need subclasses. Advantage: easier to program. Drawback: loose information that we may want to use in other places.
> R: Not generic.

Discussion:
> Q: What if I have readpermissions on 'A' and A has an xref to B. Do I than automatically get readpermission on 'B'?
>> A: We could make a special exception for the 'xref_label' of the entity. That should ALWAYS be readable. But without read permissions, users cannot choose other fields of 'B'.
>>> A: None of the fields of 'B' will be visible. If they should, permissions have to be set.

=== Dynamic permissions: row level security or 'sharing' ===

Expected user interface during editing:
{{{
> Sharing details [hide]

Owner:     me
Can view:  Maggie (user) [-][+]
Can edit:  John (user) [-] 
           My best friends (group) [-][+]
}}}

Proposed solution1: big helper table
 * Row rights: for this we introduce another optional field in the Table rights table, namely an xref to a row in the table in question. Every row already has an (autogenerated) id field so this is easily done. With this extra field in place we can have very specific entries detailing what rights a certain user has on a combination of a column and a row in a certain table (so we can in fact have "cell rights"). The remark about precedence for the column rights also holds for this.
 * So we end up with one extra bridge table having entries for combinations of tables, columns, rows, users and kinds of rights. All queries should involve joins with this table to restrict the result set based on what the current user is allowed to see/edit/execute. We have to find out what this will do with the performance of our applications! Maybe it turns out that this "big table" approach is not feasible.
 * We will add a plug-in to the Auth module where authenticated users can request rights on tables, columns and/or rows. The requests will be sent to the owners.
 * We will add a plug-in to the Auth module where users can manage the rights on tables, columns and/or rows of which they are owners. Here they can see the current requests and act on them.

Proposed solution 2: attach permissions to any 'Identifiable'
* There is an interface !RowLevelSecurity that contains fields [owner: xref->!MolgenisUser, shareRead: xref->!MolgenisGroup, shareWrite: xref->!MolgenisGroup]. [[BR]]Thus a user can choose to share data with the selected groups or individuals. 
> R: We use an abstract entity Authorizable with these three xref's. If users want to use row level security on certain entities, these have to implement Authorizable.
* Only the owner can change shareRead and shareWrite properties.
* For sharing one can only choose !MolgenisRole that the owner is member of, i.e. you can only choose groups you are part of or individuals you can find (i.e. that have given you read permission on their profiles).
> R: We won't deal with that idea in v1.

Discussion:
* We need a way to define that entities inherit permissions from its 'container'. For example: 'Investigation' could be a container and all !InvestigationElement have by default the same permissions.
> R: In v1 we start with this specific user story and implement a more generic way in following versions.
* We want to be able to locally override permissions. For example, Data is an InvestigationElement that we may want to limit edit permissions to a subgroup. 
* This data model depends on the capability to choose what type to search (groups or users); we need to make 'xref' select boxes smarter for this!

[[BR]]
[[BR]]

----

[[BR]]
[[BR]]

== Needs of the PhenoFlow module (lifelines, bbmri, gids2.0, col7a1, xgap) ==
PhenoFlow is the user interface for searching, browsing and extracting phenotype data from the Pheno model. This browsing module will be central in most of our applications.

The systems (that will be) using this module are

 * LifeLines (datawarehouse)
 * BBMRI-NL (biobank catalog) and
 * gids (2.0).
 * COL7A1 Phenotype/Patient browser (here one gene == one investigation)
 * XGAP data browser

Requirements:

 * Users need to be able to login
 * All registered users have edit permissions to create new investigations
 * All existing investigations can only be listed (names) but no other values
 * All investigations are owned by one or more persons
 * If not yet owned, users can request to become manager of an investigation.
 * Otherwise users can request read access to the investigation
 * Users can create groups of themselves (except for lifelines)
 * Users can share an investigation and all its components to [public, groups, whitelists of users) for viewing
 * The sharing rules can be read or write (so that means they can transfer management of an investigation)
 * All InvestigationElement inherit the sharing rules set on an investigation (hence, if the investigation is public so are all its elements)
 * Individual investigation elements, and the dataelements that refer to them can have different permissions (lifelines)

Issues:

 * What about data that is not an Investigation/InvestigationElement?

See www.myexperiment.org for some inspiration on how this 'sharing' model can work. See www.myexperiment.org for some inspiration on how this 'sharing' model can work.

== Needs of the xQTL Workbench ==
Requirements:

General:

 * All data input/output needs to be closed / secured
 * Unregistered users can still view public datasets

User:

 * Users need to be able to register (as users)
 * Confirmation email to the registrar
 * Users need to be able to register/confirm their email
 * Users need to be able to login
 * When loged in users are able to view public datasets and their own datasets

Admin:

 * Administrators need to be able to: Authenticate users, Ban users, Delete unused accounts
 * Administrators are not able to register, view all,execute all
 * Users cannot be promoted to admin, admins cannot be demoted to users
 * Admins donnot register, but are 'hardcoded' into the application