= Installation Guide = [[Since(1.0)]] This Installation Guide is a plan for installing the OpenASelect Server at a target system, including prerequisites and preparations. [[TOC(depth=2)]] == Scope == The OA Server (OAS) is the main part of the OpenASelect product line. Its purpose is to authenticate users and to perform single sign-on on behalf of web-based applications. The authentication itself is performed by extendable and pluggable authentication methods. === Relationship to other guides === This guide focuses on the installation of a minimal OpenASelect Server deployment. OpenASelect offers a wide range of pluggable components which allow more advanced Server deployments. These deployments and components are described in separate guides (see [wiki:ServerGuides] for more information). == Installation overview == This paragraph provides a general description of the installation process to provide a frame of reference for the remainder of the guide. The OpenASelect server is a J2EE web application and should be deployed on a [http://jcp.org/aboutJava/communityprocess/final/jsr154/index.html Java Servlet Specification 2.4] and [http://jcp.org/aboutJava/communityprocess/final/jsr152/ JavaServer Pages 2.0] compliant servlet container. The OpenASelect server distribution can be obtained in several download formats. This guide focuses on the deployment of the web application archive (WAR) distribution. The following tasks should be performed during the software installation: 1 Preparation:: Install OS, Java Runtime, and Servlet container. 2 Download distribution:: Download the OpenASelect Server distribution from the openaselect.org site. 3 Deploy WAR:: Deploy the web application archive (WAR) in the servlet container 4 Configure Server:: Basic Server configuration 5 Start OA Server:: Start the servlet container and the application 6 Verify the installation:: Verify the installation by performing some simple tests == Preparation == Some preparation is necessary before installing the Server distribution. The OpenASelect Server requires a Servlet container and Java Virtual Machine in order to operate. Details on assembling a hardware system, Installing the Operating system, Java, and the servlet container is out of the scope. === Software requirements === The following table indicates which (sub)systems are required to run: {{{ #!html
(sub)system Notes
Operating System OpenASelect should be capable of running on any operating system which supports Java SDK.
Java Virtual Machine OpenASelect requires Java SDK 1.5 or higher.
(see http://java.sun.com)
Servlet Engine OpenASelect requires a Java Servlet Specification 2.4 and JavaServer Pages 2.0 compliant servlet container.
OpenAselect recommends Tomcat 5.5 or higher ( http://tomcat.apache.org)
SQL Database OpenASelect requires a database which supports SQL.
PostgreSQL ( http://www.postgresql.org) is recommended and database creation scripts for PostgreSQL are shipped with the full distribution.
}}} [[BR]] == Download distribution == The latest war distribution can be downloaded from the [wiki:Downloads download section]. The downloaded `zip` file should be extracted to a temporary directory on your target file system. == Deploy WAR == A Web archive (WAR) file is a single file that contains all the components of the standard OpenASelect distribution. WAR files allow simple deployment in a target environment where the application is intended to run. Most Servlet engine have tools available for the deployment of WAR files. These deployment tools will unpack the WAR file and place the application components according to the hierarchy specified by the WAR file structure. Please refer to your Servlet Engine documentation for more information on how to deploy a web archive. The procedure for Apache Tomcat is outlined below. === WAR Deployment on Tomcat === 1. Stop Tomcat. 2. If you have previously deployed "openaselect.war" in `TOMCAT_HOME/webapps`, then it has been unpacked. Make sure you have a copy of the configuration files located in the openaselect webapps directory before proceeding to step 3. 3. If you have previously deployed "openaselect.war" in `TOMCAT_HOME/webapps`, delete the existing deployment. You must delete this directory and all its contents: {{{ # rm -r /webapps/openaselect }}} 3. Copy the WAR file to ''/webapps''. When restarting Tomcat the WAR file will be extracted. {{{ # cp openaselect.war /webapps }}} 4. Start Tomcat. {{{ # /etc/init.d/tomcat start }}} See [http://tomcat.apache.org/tomcat-5.5-doc/deployer-howto.html Tomcat Web Application Deployment] for more information. '''Note:''' Tomcat 5 and newer includes a web application that supports, among other things, the deployment of WAR files without restarting server. See the [http://tomcat.apache.org/tomcat-5.5-doc/manager-howto.html Manager App HOW-TO] or more information. == Configure Server == After deploying the OpenASelect Server distribution it is now time to configure the server to act as a secure Single Sign-On (SSO) authentication system. The Server consists of three major configuration files: Deployment descriptor:: The web application deployment descriptor (`/webapps/openaselect/WEB-INF/web.xml`) contains deployment configuration. Logging properties:: The Logging configuration is located in a log4j properties file (`/webapps/openaselect/WEB-INF/classes/log4j.properties`). Server configuration:: The OAS main configuration file (default located in the `/webapps/openaselect/WEB-INF/conf/oa.xml`). '''Note:''' The backup of the configuration files as described in step 2 of the [#WAR Deployment on Tomcat] description can optionally be restored in the extracted `openaselect` directory. === Deployment desciptor (web.xml) === The deployment descriptor describes how the OpenASelect Server web application should be deployed. The following components are deployed: OAContextListener:: The OA context listener deals with the application life cycle and starts and stops all low level components. OAServlet:: The main entrance for server requests (`/profiles`, `/helpers`) !AxisServlet:: The [http://ws.apache.org/axis2/ Apache Axis2] servlet which distributes the web service requests (`/services`) WebSSO:: The web-based single sign-on functionality (including user interface: `/sso/web`). !ManagerServlet:: Entrance for management events (soft start, stop, and restart) OpenASelect access filters:: The access filters can be used to restrict access to the !ManagerServlet (see [#ManagerServlet ManagerServlet ]). The default descriptor contains all the necessary components for the application to run and is almost suitable for a production environment as is. ==== !ManagerServlet ==== The manager servlet is used to receive soft start, restart, and stop API calls to the OpenASelect Server. This manager should be protected in a way that it can only be called by authorized system administrators. The default deployment descriptor contains two access filters for the !ManagerServlet: !RemoteAddrFilter:: Denies access based on the remote address of the caller. !SharedSecretFilter:: Allows access based on a shared_secret sent in the API request. '''Make sure the IP adress is configured properly and a safe shared secret is chosen.''' '''Note:''' If the manager functionality is not used in a production environment at all, it is recommended to remove the manager servlet from the deployment. === Logging properties (log4j.properties) === By default the OpenASelect Server logs to system out. This can be adjusted by editing the following file: {{{ # vim /webapps/openaselect/WEB-INF/classes/log4j.properties }}} For more information on configuring the OpenASelect Server logging settings, please refer to the [wiki:1.2/LoggingAndAuditing Logging and Auditing Guide]. === Server configuration (oa.xml) === The main configuration of the OpenASelect Server is located in an XML file. The configuration file is located at `WEB-INF/conf/oa.xml` by default: {{{ # vim /webapps/openaselect/WEB-INF/conf/oa.xml }}} OpenASelect distributions may contain example configuration files. The OpenASelect Server distribution ships with the following example configurations: `WEB-INF/conf/oa-minimal.xml`:: Minimal configuration which is used as default `oa.xml` `WEB-INF/conf/oa-example.xml`:: Contains examples off all optional and mandatory configuration items and there syntax `WEB-INF/conf/oa-redundant.xml`:: Configuration for a redundant server environment '''Note:''' The `attributes-example.xml` and `users-example.xml` files contain example users and attributes which are not suitable for production environments. See [wiki:1.3/conf/UserFactorySection#FileExternalStorage User Factory Reference] for more information. '''Note:''' You should enable at least one IDP profile e.g. [wiki:1.4/conf/ASelectProfileSection A-Select]. See the [wiki:ServerConfigurationReference Server Configuration Reference] for more information on configuring your OpenASelect server. == (Re)start the server == After modifying the configuration (re)start Tomcat once again. {{{ # /etc/init.d/tomcat restart }}} == Verify the installation == #verification To verify the installation some simple checks can be performed. The OAS should be installed and configured properly. The application server which contains the OAS should be started by now. All OAS back-end systems are up and running. View the OAS system log (by default logged to the console) which is placed in the following directory: {{{ /logs/ }}} Validate the log entries. There should be no `ERROR` or `FATAL` log entries since the last start up. The successful start up of at least the following components is logged to the system log: * !ConfigurationManager * !EngineLauncher * OAContextListener * SSO Service * WebSSO In addition to the OA System logging, there should be no new error entries in the logging of the application server: {{{ /logs/catalina.out }}} === Check the main page of the Open ASelect Server === The root of the web application contains a default page with some server information. Access this page using a web browser: {{{ http://[host][:port]/openaselect/ }}} The main page is displayed. A welcome message is displayed in the language of the browser. '''Note:''' It is recommended to perform at least one successful authentication after a new installation or update.