## Please put instances of this page in the appropriate task folder, e.g. Tasks/X/Y/DesignDocumentation
## Headline such as "Design of X.Y Backup Requirements"
= Design of Doms Auth system Task =
This design has been worked out between MV, PDJ, JRG and ABR. JHLJ has been informed of some of the design, but need to sign of on the final version.

The system is based on some fundamental principles:
 1. There is one, and just one, service, that evaluates if the supplied roles are sufficient to access the given resource.
 1. There are numerous ways to determine user roles, and the determination of these are the job of the user interfaces.
 1. Content is only gettable through the permanent URL. You cannot go around the system protecting the permanent url

Notes
 1. Thumbnails will never be stored in DOMS

There are a series of milestones for the DOMS auth system
 1. Bitstorage Permanent URLs are protected. We can only present the user with a downloadable url, nothing more such as thumbnails
 2. A service is build, that generates thumbnails. For collections with protected content, but public thumbnails, the service is meant to bypass the protection on the content.
  This service runs on a specific IP adress. Said IP adress translate to a role, that is POLICY encoded to allow access. So, the service can request the content, even if the user interacting with the service cannot do so.


== Bitstorage protection - Milestone 1 ==

This is the design of the system protecting the permanent urls. 

On the 4. of June, ABR, KFC, and Per and Søren, met and discussed the design. We agreed on this.

We decided not to have the php app stream the file. Instead, the Apache server directly should stream the file. There are at least two ways of achieving this.
A premise for both of them is that the php app runs independently of the apache server.

We discussed timing of the project. Søren reported that any significant effort on their part would be much easier to fit in in Q3 and Q4. We agreed on two milestones
 1. Mockup system
 2. Working system

The mockup system would not have a proper WAYF integration. It would map IP to roles, but not in any helpdesk-maintainable way. The mockup would have as it's purpose to test the integration between the components. Doms Auth service would have to be written for the mockup to work, though, and however Apache communicates with the php script should also work.

A note on WAYF. WAYF can only be enabled on systems that are in production, and with a delay of about 2-3 weeks. As such, we will not be able to play with full WAYF integration.




The design is as follows:

Components:
 * Doms auth checker: Service for checking credentials against the policy in doms. Author IT Digitale Ressourcer
 * IP2RolesMapper: Service for mapping user ip to a set of roles. Auther Unknown.
 * PHP main app: Service for handling the flow between the services. Auther IT Service
 * Apache server: Server for housing the php app, and handling the  perm urls. Use URL_rewrite to  forward requests to php.
 * Apache to Php connector: Some system, like a filter for Apache, that invokes the php app before serving the file

 1. Each file in bitstorage is assigned a permanent URL
 1. An Apache server is set up to handle these URLs

User GETs a perm url
 1. Apache php connector is activated, so execution is forwarded to the php script
 1. Php application
  1. Invoke "IP2RolesMapper" to get user roles.
  1. Invoke Doms Auth Checker(url, roles) to see if the IP roles are enough to get the file
  1. If no:
   1. Extract Wayf credentials from the user, by redirecting him to the WAYF page.
   1. Invoke Doms Auth Checker(url, creds) to see if the file is assesible with the creds
   1. if no:
    1. Send Unauthorized error
  1. Return "yes" to apache
 1. If yes, open the file
 1. Request mime type from fedora
 1. Stream it to the user.

The two designs we have chosen for the apache php connector are:
 1. When the Perm url is invoked, apache check for the existence of some magic cookie. If not, user is redirected to the php app, which checks stuff, and sets the cookie. The php app finishes up by redirecting the user back to the perm url. This time the cookie is set, so the user is allowed through to the file.
  Problems here: We need Apache to validate the magic cookie. It is not very clear how we can achieve this. Thoughts go to a Filter, implemented in Python or Perl. KFC will adress this with JHLJ. Besides, there are quite a number of redirects.
  Fallback: We just need a way for php to tell apache that this specific browser is cleared for this specific resource. There are other ways than cookies.
 2. Mod_cas: If Apache has a CAS module, it could communicate with the php script. The php script can be a server, and will be able to authenticate the user. This will be the more clean design, but it requires that somebody has written a CAS module for apache.
  Problem here: No experience. Found https://source.jasig.org/cas-clients/


=== IP Roles are enough ===

{{attachment:auth2.jpeg}}

=== Wayf creds needed ===

{{attachment:auth1.jpeg}}

=== No creds good enough ===

{{attachment:auth3.jpeg}}


=== Other Auth systems ===
We will have to support other auth systems than WAYF and IP. These must be worked into the design. The design is simple
 1. Get user roles from some system
 1. Check roles against doms
 1. If good:
  1. Stream file
 1. Else:
  1. Try next user role system

The big decision is in which order to check. Since WAYF works by redirecting the user to a login page, WAYF will always be the last way to authenticate. 


== Thumbnail system - Milestone 2 ==

There are four basic kinds of thumbnails
 1. Free thumbnails, where the content is also free
 1. Free thumbnails, protected content
 1. Protected thumbnails, same protection for content
 1. Protection A for thumbnails, protection B for content

We postulate that case 4. will never arise. If it does, we will solve it by putting these thumbnails in DOMS as separate file objects. We can, of course express different rights between file objects.

This leaves us with three cases.

For case 1 and 2, the solution is the same. The thumbnail should always be displayed. The solution is to build some thumbnail generating service, which can take the PERM url as input. This service runs with an approved IP adress, that has been allowed to access the content. The service generates the thumbnails for the user. No user credentials need to be input to the service, as the thumbnails should always be displayed.

It is clear, that there are several components of this service. There is the framework, and there is the actual code that translate the resource to a thumbnail.

Then there is case 3. The same service as above can be used, but in that case, the service should not be invoked if the user should not see the thumbnail. In case 3, the user has equal access to the thumbnail and the content. We already have a service, called DOMS Auth above, which can check credentials for a permanent url. We should have the thumbnail service have privileged IP access to the content, but have this protected by a call to the DOMS auth service. This way, we trust the presentation system, to only generate thumbnails that it is cleared for.

=== Thumbnail discovery ===

There are no good way of communicating which URLs can be thumbnailed, and which cannot. The presentation layer must use best judgement.

=== Components ===
 * Thumbnail service
 * Thumbnail service framework


## Add detailed explanation of the solution to this task. That is, how things are meant to work.

## This may include UML diagrams, schematics describing architecture etc. attached like this:
## Link to original: [http://merkur/svn/doms/trunk/MODULE/docs/MyPackageDiagram.dia]
## png on the wiki page: http://merkur/svn/doms/trunk/MODULE/docs/MyPackageDiagram.png

== Prerequisites and Design Decisions ==
## Describe any prerequisites are important for this design, e.g.:
## Requirements that must be met by other systems, users, etc.
## Description and background/reason for non-trivial design decisions.

=== Required Software and Modules ===
## Describe any required 3rd party software, libraries, other code modules in the project to make this design work.

== Resources ==
## List links to documents, wiki pages etc. that are relevant to this design document.
## * [:LinkToMyRessource:Use class diagram xx]
## * [:LinkToMyVersionControlledDocument:Link to 3rd party library documentation.]