#
# Content
#
1. About & Requirements
2. Frontends
3. Configuration & Start-up
4. Clients
5. Usage



#
# 1. About & Requirements
#

1.1 About

A Single Sign-On (SSO) Server instance provides a single point of authentication for your services and applications.
Additionally, it supports trust delegation by allowing for storage and retrieval of so-called credentials (see 1.2).

Essentially, it consists of three components:

- SSO Server
- SSO Database: stores SSO accounts, can be used embedded within SSO Server or as a separate instance being accessed by SSO Server via TCP
- SSO Agent

[TODO: Interaction Diagram]




1.2 Requirements

You need a Java 1.6 Runtime Environment and
- two open TCP ports (see 2.) to run SSO Server with embedded SSO Database
- three open TCP ports (see 2.) to run SSO Server with SSO Database running separately



#
# 2. Frontends
#

SSO Server consists of both an HTML and a REST frontend.


2.1 HTML frontend

URI: http(s)://$host:$web_port/sso-server

Use cases:
- Redirection-based SSO login / logout
- SSO account management

Offers:
- User registration
- User login
- SSO account management
- Contact / troubleshooting notification
- User logout


2.2 SSO Service

URI: http(s)://$host:$rest_port/sso-service

Provides RESTful access to SSO Server.

Use cases:
- Direct SSO login / logout
- User credential management

Offers:
- Login
- Rich Login
- Logout
- Login State Validation
- Login Refresh
- User Role(s) Retrieval
- Add User Credential
- Get User Credential(s)
- Remove User Credential
- Retrieve Session Lifetime

Please refer to 'http(s)://$host:$rest_port/sso-service' for a detailed interface description.



#
# 3. Configuration
#  


3.1 Customize Web application name (optional)

Usually, the SSO Server frontend can be reached at http(s)://$host:$web_port/sso-server.
If you want to replace 'sso-server' with a custom name, you need to rename the $YOUR_DESIRED_APPLICATION_NAME
parameter in 'conf/web.xml' (it occurs twice):

<filter>
	<filter-name>$YOUR_DESIRED_APPLICATION_NAME</filter-name>
	<filter-class>org.apache.wicket.protocol.http.WicketFilter</filter-class>
	<init-param>
		<param-name>applicationFactoryClassName</param-name>
		<param-value>org.apache.wicket.spring.SpringWebApplicationFactory</param-value>
	</init-param>       
</filter>

<filter-mapping>
	<filter-name>$YOUR_DESIRED_APPLICATION_NAME</filter-name>
	<url-pattern>/*</url-pattern>
</filter-mapping>


3.2 Server configuration

Set the appropriate parameter values.
Below, you'll find a short description for each parameter:

- host: external domain name / IP address of the server node hosting 'sso-server'
- ssl: "false" (SSL active) or "true" (SSL inactive; provides no real security, since HTTP/plaintext)
- port: HTTP port of hosting server node
- restPort: REST port of hosting server node
- keyStore: file system path to Java keystore (JKS) file (needed for SSL)
- keyStorePass: password for 'keystore' (needed for SSL)
- trustStore: file system path to Java truststore (JKS) file (needed for SSL: needs to store X.509
			  certificates of all applications participating in this SSO domain)			  
- trustStorePass: password for 'trustStore' (needed for SSL)
- contactName: person to turn to for organisational/technical issues
- contactEMail: e-mail address of 'contactName'
- credentialManagerURL: URL to external credential management application (optional: you might need this
						if you're using an external Web application that users need to interact with to store
						credentials to 'sso-server')						
- tmpDir: temporary directory this Web application is extracted to (optional, but strongly encouraged to avoid
		  clashes in the default OS temporary directory that is used as a fallback value)		  
- sessionLifetime: specifies how long (in ms) a session is allowed to idle before being deleted
- sessionValidationInterval: specifies the session validation rate (in ms)


This is a what a configuration might look like:

<bean id="configuration" class="wisnetgrid.security.sso.Configuration" factory-method="get">
	<property name="host" value="127.0.0.1" /> <!-- use *EXTERNAL* name / IP address -->
	<property name="ssl" value="true" />
	<property name="port" value="9999" />
	<property name="restPort" value="8183"/>
	<property name="keyStore" value="conf/keystore_sso-server.jks" />
	<property name="keyStorePass" value="sso-server" />
	<property name="trustStore" value="conf/keystore_sso-server.jks" />
	<property name="trustStorePass" value="sso-server" />		
	<property name="contactName" value="Al Admin" />
	<property name="contactEMail" value="a.admin@sso-provider.com" />
	<property name="tmpDir" value="./tmp" />
	<property name="sessionLifetime" value="1800000" /> <! -- [ms]; optional, default value is 1800000 -->
	<property name="sessionValidationInterval" value="30000" /> <! -- [ms] optional, default value is 30000 -->
</bean>


2.3 Persistence configuration
'sso-server' needs a JDBC database for persisting user and session data.


a) embedded database
If an embedded database is to be used, use this configuration:

<bean id="dataSource" class="org.h2.jdbcx.JdbcDataSource">		
	<property name="URL" value="jdbc:h2:$DATABASE_STORAGE_PATH"/>
</bean>

For example (Unix, Linux), using $DATABASE_STORAGE_PATH=./sso-db

<bean id="dataSource" class="org.h2.jdbcx.JdbcDataSource">		
	<property name="URL" value="jdbc:h2:./sso-db"/>
</bean>

or (Windows), using $DATABASE_STORAGE_PATH=sso-db

<bean id="dataSource" class="org.h2.jdbcx.JdbcDataSource">		
	<property name="URL" value="jdbc:h2:sso-db"/>
</bean>



b) external database
Alternatively - and this increases security quality - you can use an external JDBC database reachable via TCP ('sso-db').
This approach assumes there is already a SSO Database instance running at the following location:

<bean id="dataSource" class="org.h2.jdbcx.JdbcDataSource">		
	<property name="URL" value="jdbc:h2:tcp://$DATABASE_HOST:$DATABASE_TCP_PORT/$DATABASE_NAME"/>
	<property name="user" value="[DATABASE_USER]"/>
	<property name="password" value="[DATABASE_USER_PASSWORD]"/>
</bean>


e.g., using $DATABASE_HOST=127.0.0.1, $DATABASE_TCP_PORT=3309, $DATABASE_NAME=wisnetgrid

<bean id="dataSource" class="org.h2.jdbcx.JdbcDataSource">		
	<property name="URL" value="jdbc:h2:tcp://127.0.0.1:3309/wisnetgrid"/>
	<property name="user" value="wisnetgrid"/>
	<property name="password" value="wisnetgrid"/>
</bean>


Once configured, you can run SSO Server.
To facilitate operation, SSO Server provides start/stop scripts that use default parameter values (that can
be modified within the respective script files).
These scripts are located in the 'bin' directory.


#
# 4. SSO Service clients
#

Being RESTful, you don't need proprietary clients to consume sso-service, but to facilitate interfacing
with SSO Server, this project comes with a small client library called 'sso-agent'
(wisnetgrid.security.sso.client).
A PHP port is also available.


#
# 5. Usage
#

To use SSO Server, a user needs to register (http(s)://$host:$web_port/sso-server/register) for a SSO account containing:
- username
- password
- user details (first and last names, e-mail address, organization)
- roles (1..m)
- credentials (1..n); a credential	
	- encapulates authentication/authorization data needed by services/applications delegating authentication to SSO Server
		- password
		- X.509 certificate
		- SAML assertion
		- etc.
	- can be encrypted using the user's private key  
	
	
	