File	Date	Author	Commit
.settings	2013-09-16	Mateusz	[434439] needed before merge
forges_tags	2014-03-21	Mateusz	[133e9e] Prefix and syn search is working based on the d...
markos-registration-ejb	2014-11-04	Simon Hohberg	[eb3ce3] changing version numbers, removing old projects
stackoverflow_tags	2014-03-28	Mateusz	[aba700] fixed pom slf4j bug
token-generator	2014-11-04	Simon Hohberg	[eb3ce3] changing version numbers, removing old projects
.gitignore	2014-05-12	Simon Hohberg	[6bb289] Refactoring Token Generator:
.project	2013-09-16	Mateusz	[434439] needed before merge
LICENSE	2014-07-10	Simon Hohberg	[fe0fb4] Adding google plus sign in support
Markos-soapui-project.xml	2014-02-26	Mateusz	[cf8648] soapui tests updated
README.html	2014-10-13	Simon Hohberg	[d8a630] updating readme
README.md	2014-10-13	Simon Hohberg	[d8a630] updating readme
Token-Generator.html	2014-05-26	Simon Hohberg	[2b2df2] Updating token generator documentation, adding ...
Token-Generator.md	2014-05-26	Simon Hohberg	[2b2df2] Updating token generator documentation, adding ...
pom.xml	2014-11-04	Simon Hohberg	[eb3ce3] changing version numbers, removing old projects

Read Me

<h1>MARKOS Registration</h1>

<h2>What is it?</h2>

<p>This is the back-end component of the MARKOS project that is responsible for 
user management (registration, authentication, project manager authentication).
There are two mechanisms for authentication: Simple user name and password 
authentication and authentication using Open ID, which means that any of the 
Open ID providers like Google, Yahoo, etc. can be used to create/sign in to an 
account.
This component is ment to be integrated into a Google Web Toolkit (GWT) 
application (see <a href="#GWTIntegration">How to integrate into a GWT Application</a>)</p>

<h2>System requirements</h2>

<p>All you need to build this project is Java 6.0 (Java SDK 1.6) or better, Maven 
3.0 or better.
For deployment Tomee 1.6.0, Hibernate and PostgreSQL are required.</p>

<h2><a name="TomeeSetup">How to Setup Tomee</a></h2>

<h3>Get TomEE Plus</h3>

<p>Install TomEE Plus 1.6.0 from 
[http://archive.apache.org/dist/tomee/tomee-1.6.0/apache-tomee-1.6.0-plus.tar.gz]
(http://archive.apache.org/dist/tomee/tomee-1.6.0/apache-tomee-1.6.0-plus.tar.gz).</p>

<p>Or install TomEE Plus 1.7.1 from
[http://www.apache.org/dyn/closer.cgi/tomee/tomee-1.7.1/apache-tomee-1.7.1-plus.tar.gz]
(http://www.apache.org/dyn/closer.cgi/tomee/tomee-1.7.1/apache-tomee-1.7.1-plus.tar.gz).</p>

<h3>Hibernate</h3>

<p>The MARKOS registration component uses Hibernate for persistence. Therefore we
setup Tomee to use Hibernate.
In the file <code>&lt;tomee-home&gt;/conf/system.properties</code> add/change the 
line to match the following:</p>

<pre><code>javax.persistence.provider = org.hibernate.ejb.HibernatePersistence
</code></pre>

<h4>TomEE Plus 1.6.0</h4>

<p>Add hibernate libraries to <code>&lt;tomee-home&gt;/lib</code>. Following jars are
required:</p>

<ul>
<li>hibernate-commons-annotations-4.0.1.Final.jar</li>
<li>hibernate-core-4.1.4.Final.jar</li>
<li>hibernate-entitymanager-4.1.4.Final.jar</li>
<li>hibernate-validator-4.2.0.Final.jar</li>
</ul>

<h4>TomEE Plus 1.7.1</h4>

<p>Add hibernate libraries to <code>&lt;tomee-home&gt;/lib</code>. Following jars are
required:</p>

<ul>
<li>hibernate-commons-annotations-4.0.2.Final.jar</li>
<li>hibernate-core-4.2.15.Final.jar</li>
<li>hibernate-entitymanager-4.2.15.Final.jar</li>
<li>hibernate-validator-4.2.0.Final.jar</li>
</ul>

<h3>PostgreSQL</h3>

<p>For storing user accounts and profiles MARKOS registration uses a PostgreSQL
database. Therefore PostgreSQL has to be installed and setup choosing a 
<code>UserName</code> and <code>Password</code> which will be used later when configuring the data 
source for the MARKOS registration component.</p>

<h4>JDBC Driver</h4>

<p>Install the JDBC PostgreSQL driver by dowloading it from 
<a href="http://jdbc.postgresql.org/">http://jdbc.postgresql.org/</a> and copying it to 
<code>&lt;tomee-home&gt;/lib</code> (choose JDBC4).</p>

<h3>Database</h3>

<p>Create a PostgreSQL database with name <code>markos</code>.</p>

<h4>Data Source</h4>

<p>In <code>&lt;tomee-home&gt;/conf/tomee.xml</code> add:</p>

<pre><code>&lt;tomee&gt;
  &lt;Resource id="markos-registrationDS" type="DataSource"&gt;
    JdbcDriver   org.postgresql.Driver
    JdbcUrl      jdbc:postgresql://localhost:5432/markos
    UserName     &gt;user&lt;
    Password     &gt;password&lt;
  &lt;/Resource&gt;
&lt;/tomee&gt;
</code></pre>

<p>Where <code>UserName</code> and <code>Password</code> should be set according to your configuration.</p>

<h3>Other Dependencies</h3>

<p>The following libraries also have to be added to the 
<code>&lt;tomee-home&gt;/lib</code> directory:</p>

<h4>TomEE Plus 1.6.0</h4>

<ul>
<li>antlr-2.7.7.jar</li>
<li>dom4j-1.6.1.jar</li>
<li>jandex-1.1.0.Final.jar</li>
<li>javassist-3.12.1.GA.jar</li>
<li>jboss-logging-3.1.0.GA.jar</li>
<li>validation-api-1.1.0.Final.jar</li>
</ul>

<h4>TomEE Plus 1.7.1</h4>

<ul>
<li>antlr-2.7.7.jar</li>
<li>dom4j-1.6.1.jar</li>
<li>javassist-3.18.1.GA.jar</li>
<li>jboss-logging-3.1.0.GA.jar</li>
</ul>

<h3>Deployment</h3>

<p>Running <code>mvn install</code> creates both a jar and war file in the targets directory.
To deploy the MARKOS registration component just copy the war file to the 
<code>&lt;tomee-home&gt;/webapps</code> directory. This will deploy the following
web-services:</p>

<ul>
<li>AuthenticationManager</li>
<li>PolicyEnforcement</li>
<li>UserManager</li>
<li>CorrectionManager</li>
</ul>

<p>The resulting endpoints are (for the 1.3 verison):</p>

<ul>
<li>http://localhost:8080/markos-registration-ejb-1.0-SNAPSHOT/webservices/AuthenticationManagerBean?wsdl</li>
<li>http://localhost:8080/markos-registration-ejb-1.0-SNAPSHOT/webservices/PolicyEnforcementBean?wsdl</li>
<li>http://localhost:8080/markos-registration-ejb-1.0-SNAPSHOT/webservices/UserManagerBean?wsdl</li>
<li>http://localhost:8080/markos-registration-ejb-1.0-SNAPSHOT/webservices/CorrectionManagerBean?wsdl</li>
</ul>

<h3>Webservice Authentication</h3>

<p>All web services require HTTP basic authentication. Therefore open 
<code>&lt;tommee-home&gt;/conf/tomcat-users.xml</code> and add the lines</p>

<pre><code>&lt;role rolename="markos-component" /&gt;
&lt;user username="markos" password="fokus" roles="markos-component" /&gt;
</code></pre>

<p>This adds a new role named "markos-component" and a new user with name "markos"
and password "fokus". Username and password should be changed of course!</p>

<h4>Web Service Factories</h4>

<p>There are two factories in MARKOS commons to easily create bindings for the 
deployed web services: <code>AuthenticationManagerfactory</code> and 
<code>CorrectionManagerFactory</code>.</p>

<p>There are two ways to obtain a binding with regard to authentication. The first
is to use the factory method where username and password can be passed as 
arguments. Username and Password should match those in 
<code>&lt;tommee-home&gt;/conf/tomcat-users.xml</code>.
The second option is to configure the 
username and password in the <code>security.properties</code> file located in MARKOS 
commons. In this case this file should contain the following two lines:</p>

<pre><code>ws_username=markos
ws_password=fokus
</code></pre>

<p>Again, username and password should be changed according to the values in 
<code>&lt;tommee-home&gt;/conf/tomcat-users.xml</code>. When the credentials are configured this
way, it is possible to use the factory methods withoud username and password
arguments since these values will be read from the properties configuration 
file.</p>

<h2><a name="GWTIntegration">How to integrate into a GWT Application</a></h2>

<p>When included in a GWT application it is necessary to include the sources of
the data transfer objects (DTOs) and exceptions from the commons component.
Therefore an authentication GWT module has to be created.</p>

<h3>GWT Authentication Module</h3>

<p>In your GWT application create a new package <code>eu.markosproject.authentication</code>.
In this package create a Module description by creating a file called 
<code>Authentication.gwt.xml</code>. Open the file and add the following lines:</p>

<pre><code>&lt;module&gt;
    &lt;source path="model" /&gt;
    &lt;source path="exceptions" /&gt;
&lt;/module&gt;
</code></pre>

<p>Finally add in your application's GWT module description:</p>

<pre><code>&lt;inherits name="eu.markosproject.authentication.Authentication" /&gt;
</code></pre>

<h3>Creating GWT Services</h3>

<p>The deployed MARKOS registration web services can now be used in your GWT
application. To call one of these services just use the 
<code>AuthenticationManagerfactory</code> to create a new instance of the service you woul 
like to use. Make sure that the factory is properly configured to match the 
endpoints where the services have been deployed.</p>

<h2><a name="UnitTests">Unit Tests</a></h2>

<p>A number of automated unit tests can be run using the testing framework 
Arquillian. To do so a Tomee+ instance has to be set up as described above and
has to be running on port 8080. Also the registration component has to be 
undeployed before running the tests, because the same web 
services will be deployed.</p>

<ul>
<li>webservice authentication, username password</li>
<li>data source configuration</li>
</ul>

<h4>Sources:</h4>

<ul>
<li>https://tomee.apache.org/tomee-and-hibernate.html</li>
<li>http://mojo.codehaus.org/gwt-maven-plugin/user-guide/project.html#Multi-project_setup</li>
<li>http://mojo.codehaus.org/gwt-maven-plugin/user-guide/library.html</li>
</ul>