Copyright © 2011-2014. JoshuaTree. All Rights Reserved.
___________________________________________________________________________________
###################################################################################
README for Fortress EnMasse Web Application Installation
RC29 (BETA RELEASE CANDIDATE)
Last updated: August 29, 2013
___________________________________________________________________________________
###################################################################################
# Prerequisites
###################################################################################
1. Internet access to retrieve dependencies from online Maven repo.

NOTE: The EnMasse maven may run without connection to Internet iff:
- The binary dependencies are already present in M2_HOME

2. Java SDK Version 7 or beyond installed to target environment
3. Maven 3 installed to target environment
4. Fortress/OpenLDAP are installed to target system.
___________________________________________________________________________________
###################################################################################
# Important Notes about EnMasse Web Application
###################################################################################

1. EnMasse is released as Open Source and available for unrestricted use via BSD 3 clause license. (see LICENSE.txt)
  - EnMasse dependencies are Open Source also.

2. This web app was tested using Apache Tomcat 7 but would work inside any current Java Servlet container (with changes to deploy procedure)

3. Maven 'install' target in this package builds EnMasse war file which deploys to Java EE servlet container.

4. This document includes instructions to Compile, Deploy, run Javadoc and Test the EnMasse Web application using Apache Tomcat.

5. Security Measures implemented within this application include:

  - Java EE Security - Confidentiality, Authentication, Session Management
    - requires HTTP Basic Auth header exchange to pass credentials used for security checks.

  - Spring Security - Role-Based Access Control Interceptor
    - Service-level Authorization uses Spring Security.
    - To find out what Roles required to which Services, view the Spring annotations inside this file:
        enmasse-dist-[version]/src//main/java/com/jts/enmasse/FortressServiceImpl.java

  - Fortress Sentry - Java EE security plugin for Identity, Coarse-grained Authorization, and Audit Trail

  - Passwords in Config Files - Encrypted using jasypt.

  - EnMasse - Identity, Administrative, Compliance and Review services.

  - OpenLDAP - Password Hashing, Policies.
___________________________________________________________________________________
###################################################################################
# SECTION 1:  Prerequisites for use of EnMasse Web Application
###################################################################################

Before you can successfully complete the steps to install and run EnMasse, the following steps must be completed:

1. Internet access from your target machine to Maven 2 online repos.

2. Maven 3 installed to target:
http://maven.apache.org/download.html
http://www.sonatype.com/books/mvnref-book/reference/installation-sect-maven-install.html

3. Java SDK Version 7 or beyond installed:
http://www.oracle.com/technetwork/java/javase/downloads/index.html

4. Fortress/OpenLDAP QUICKSTART installed:
instructions: http://www.joshuatreesoftware.us/iamfortress/guides/README-QUICKSTART.html
binaries: https://iamfortress.org/projects

5. Tomcat 7 installed:
http://tomcat.apache.org

6. Fortress Sentry package (a.k.a Realm) installed:
instructions: http://www.jts.us/iamfortress/javadocs/api-sentry/us/jts/sentry/tomcat/package-summary.html
binaries: http://iamfortress.org/download

Note: There is a complete EnMasse demo that handles these prereqs for you located here:
http://iamfortress.org/EnMasse

_________________________________________________________________________________
###################################################################################
# SECTION 2:  Instructions for EnMasse installation using distribution package
###################################################################################

1. Retrieve Fortress EnMasse source code bundle either from iamfortress.org or OpenLDAP.org.

2. Extract contents of openldap-fortress-enmasse.tar.gz to target env.
___________________________________________________________________________________
###################################################################################
# SECTION 3:  Instructions to build EnMasse Web archive file
###################################################################################

1. Open a command prompt on target machine in the root folder of the enmasse-dist package

2. Set java home:
>export JAVA_HOME=/opt/jdk1.7.0_10

3. Set maven home:
>export M2_HOME=/usr/share/maven

4. Run maven install:
>mvn install

###################################################################################
# SECTION 4:  Instructions to Deploy EnMasse Web application to Tomcat
###################################################################################

1. Enable Maven to communicate with Tomcat using settings.xml file.

note: a typical location for this maven configuration file is: ~/.m2/settings.xml

Add to file:

<server>
	<id>local-tomcat</id>
      <username>tcmanager</username>
      <password>m@nager123</password>
</server>

note: If you followed the installation steps of Fortress QUICKSTART your Tomcat Manager creds would be as above.

2. Enter maven command to deploy to Tomcat:
>mvn tomcat:deploy

3. To redeploy:
>mvn tomcat:redeploy
___________________________________________________________________________________
###################################################################################
# SECTION 5:  Instructions to test EnMasse Web application
###################################################################################

1. Run maven test
>mvn test

note1: the EnMasse application must be deployed and running within your servlet container before the unit tests will complete successfully.  If your EnMasse server
 is running on a separate machine, or using port other than 8080, adjust the settings accordingly in EmTest Java module.
note2:  For learning and troubleshooting, it is recommended that you use an HTTP proxy program, like Axis' tpMon to intercept the HTTP/XML request/responses between EnMasse client and server.
note3:  The tests depend on user, 'demoUser4', already provisioned into LDAP assigned necessary role, 'EmSuperUser'.  demoUser4 is created during Fortress' 'init-slapd' Ant target.
note4:  If for any reason these tests should not be run during maven processing, adjust the following setting in project's pom.xml (set to 'true'):

    <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-surefire-plugin</artifactId>
        <version>2.12</version>
        <configuration>
            <skipTests>true</skipTests>
        </configuration>
    </plugin>


2. Another way to test EnMasse is using the Fortress APIs which can be configured as a proxy for EnMasse.  To enable Fortress client to route
API requests through EnMasse server, add these properties to fortress.properties in your Fortress client's /config folder:

# These credentials are used for accessing EnMasse:
http.user=demouser4
http.pw=gX9JbCTxJW5RiH+otQEX0Ja0RIAoPBQf   (note this password was encrypted using the Fortress 'encrypt' target in build.xml)
http.host=localhost
http.port=80

# These will override default and enable client to call REST implementations:
reviewmgr.implementation=us.jts.fortress.rest.ReviewMgrRestImpl
adminmgr.implementation=us.jts.fortress.rest.AdminMgrRestImpl
accessmgr.implementation=us.jts.fortress.rest.AccessMgrRestImpl
delegated.adminmgr.implementation=us.jts.fortress.rest.DelegatedAdminMgrRestImpl
delegated.reviewmgr.implementation=us.jts.fortress.rest.DelegatedReviewMgrRestImpl
policymgr.implementation=us.jts.fortress.rest.PswdPolicyMgrRestImpl
delegated.accessmgr.implementation=us.jts.fortress.rest.DelegatedAccessMgrRestImpl
auditmgr.implementation=us.jts.fortress.rest.AuditMgrRestImpl
configmgr.implementation=us.jts.fortress.rest.ConfigMgrRestImpl

___________________________________________________________________________________
###################################################################################
# SECTION 6:  Instructions to create EnMasse javadoc (optional)
###################################################################################

The service level documentation provides descriptions for each of the EnMasse services + required and optional parameters for service invocations.

1. Enter the following:

$ mvn javadoc:javadoc

2. View the document output here:

openldap-fortress-enmasse/target/site/apidocs

3. To view Service-level documentation, go here:

openldap-fortress-enmasse/target/site/apidocs/com/jts/enmasse/FortressServiceImpl.html