UVOS Web Registration Extension Manual
======================================
UNICORE Team <unicore-support@lists.sourceforge.net>
:revnumber: 1.5.1
:numbered:

UNICORE VO Service (UVOS) is a client-server system, developed to be used as an additional tool for large
distributed systems, providing a solution for grid users management. 
Grid systems, especially UNICORE grid middleware, are the mainspring of the UVOS system. 
UVOS can be used with different systems, however is designed primarily to support UNICORE grid middleware. 

For more information about UVOS visit http://uvos.chemomentum.org[http://uvos.chemomentum.org].


Introduction
------------

VO authentication web component provides a login user WWW interface
for the UVOS system. It used to provide SAML HTTP POST or HTTP Redirect 
binding implementation: other web components may redirect authentication requests 
to this component which authenticates the presenter and 
returns a well-formated, signed document certifying this fact.

The main features are:

 - support for interactive email+password authentication
 - support for authentication via web browser supplied certificate (i.e. 
 client-authenticated TLS/SSL). In this case user is authenticated as UVOS
 DN identity or UVOS X.509 identity (anyone which will succeed).
 - test mode: you can invoke the login servlet simply with HTTP GET. 
 The authentication will be performed but no SAML response will be generated.

Compatibility
-------------

This release is compatible with UVOS 1.4.0 and 1.4.1 (future versions might be
supported too).


Installation
------------

UVOS web authentication extension is distributed either as a 
platform independent archive or as an installable, platform dependent package 
such as RPM. Depending on the installation source used, installation method and paths 
after installation are different. 


Installation from RPM package (RedHat distributions) 
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The preferred way is to use Yum  to install (and subsequently update) UVOS webauth.

To perform the Yum installation, EMI Yum repository must be installed first. 
Refer to the EMI release documentation (available at the EMI website http://www.eu-emi.eu/releases ) 
for detailed instructions. Typically installation of the EMI repository requires to 
download a single RPM file and install it. 

After the EMI repository is configured, the following command installs UVOS webauth:
 
 $> yum install unicore-uvos-webauth

The installed extension will be placed in the directory 
+/var/lib/unicore/uvos-server/webapps/+

You have to restart UVOS server to complete the installation.

Installation from the DEB package (Debian distributions) 
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
	
The preferred installation way is to use apt to install and subsequently update UVOS webauth.
	 
To perform the apt installation, EMI apt repository must be installed first. 
Refer to the EMI release documentation (available at the EMI website http://www.eu-emi.eu/releases ) 
for detailed instructions. Typically installation of the EMI repository requires to 
download a single DEB file and install it. 

After the EMI repository is configured, the following command installs UVOS webauth:

 $> apt-get install unicore-uvos-webauth

The installed extension will be placed in the directory 
+/var/lib/unicore/uvos-server/webapps/+

You have to restart UVOS server to complete the installation.


Installation from the archive
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
If installing using a portable archive you have:

 1. Download the archive from the UNICORE download site and unpack it.
 
 2. In the unpacked archive you can find a file with a .war extension. 
 Copy it to the webapps/ directory of UVOS server. This directory is 
 placed directly under installation root folder which was
 used when installing UVOS server from portable archive.  


You have to restart UVOS server to complete the installation.
[[path]]
Web browser path
----------------

The name of the war file is important as it is reflected in the 
URL by which web application is available. By default it is 
uvos-webauth-VERSION.war, where VERSION is e.g. "1.2". You can freely
change the name of the war file. From now we will use label
WAR_FILE_NAME to refer to actual base name of your war file.

You should be able to reach the web UI indirectly (via redirect) 
at the address:

	<UVOS server base address>/WAR_FILE_NAME

or directly at:

	<UVOS server base address>/WAR_FILE_NAME/VOauthentication.do

Example for the default server configuration and war named 'uvos-webauth-1.0.war':

	https://localhost:2443/uvos-webauth-1.0
	
	
Configuration
-------------

It is possible to change the default HTML page used for the logging the user.
To do so:

 - create a new directory in UVOS server's +webapps+ folder with desired name
 and unpack war archive into it.
 - remove the unpacked war file from the +webapps+ directory.
 - modify CSS styles in template files located in +WEB-INF/templates+. Most of them
 are located in +headerTop.ftl+ file.
 - restart the UVOS server.



Developer howto
---------------

For the high level understanding how the authentication works see documents:

 - SAML 2.0 core specification by OASIS - sec. 3.4 Authentication Request Protocol
 - SAML 2.0 bindings specification by OASIS - sec. 3.4 HTTP Redirect Binding
 - SAML 2.0 bindings specification by OASIS - sec. 3.5 HTTP POST Binding

To implement authentication in your servlet you have to:

 - Create and return a XHTML document to the user (which should be authenticated).
 The document must contain POSTable form, with action equal to address of the 
 web-auth servlet (contained in this package) installed at UVOS server. Check
 the xref:path[Web Path] section to see what URL you should use. Most often JavaScript
 is used to submit the form automatically to the web-auth servlet.
 - (and (hopefully) after while) Serve POST response with SAML response in it.

You can match request and response by so called 'RelayState' data which can 
be assigned to the initial form and should be returned in the 2nd form.

UVOS client library offers a class that implements all the logic to 
perform the above pattern. 
The class is +pl.edu.icm.unicore.uvos.wsclient.samlapi.SAMLVOAuthnClientPOST+
See its javadocs. Also there is a mostly complete servlet example in this package
however note that it won't compile (that's why it isn't in sources) as it depends
on uvos-client package which is not available (and needed) for the uvos-webauthn package.
This example is located in the documentation directory and is called +TestLoginServlet.java+.
