#
#   Licensed to the Apache Software Foundation (ASF) under one
#   or more contributor license agreements.  See the NOTICE file
#   distributed with this work for additional information
#   regarding copyright ownership.  The ASF licenses this file
#   to you under the Apache License, Version 2.0 (the
#   "License"); you may not use this file except in compliance
#   with the License.  You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
#   Unless required by applicable law or agreed to in writing,
#   software distributed under the License is distributed on an
#   "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
#   KIND, either express or implied.  See the License for the
#   specific language governing permissions and limitations
#   under the License.
#
___________________________________________________________________________________
###################################################################################
INSTRUCTIONS TO ENABLE FORTRESS REALM for Tomcat Host
Last updated: February 9, 2015
-----------------------------------------------------------------------------------
###################################################################################
# Guidelines & Tips
###################################################################################
- This document describes how to enable Fortress Realm to provide security for all apps running
  inside a Tomcat server virtual host.

- To target a single web application, and not enable for entire host, follow the Tomcat instructions in the 'REALM-CONTEXT-SETUP.txt'

- In the document that follows, replace "[version]" with Fortress Realm version label.
  For example - if Fortress Realm 1.0 release, change fortress-realm-proxy-[version].jar to fortress-realm-proxy-1.0.jar

- Restart Tomcat server after any changes to Tomcat config, Fortress config or lib files.

- Common misconfiguration issues related to Fortress, LDAP and Tomcat are located at the end of this document.
___________________________________________________________________________________
###################################################################################
# SECTION 0.  Prerequisites for Fortress Realm installation and usage with Tomcat
###################################################################################
a. Internet access to retrieve source code from Apache Fortress Realm GIT and binary dependencies from online Maven repo.

b. Java SDK Version 7 or beyond installed to target environment

c. LDAP server installed and configured for Fortress.  (see README in Apache Fortress Core).

d. Apache Tomcat 7 or greater installed to local machine.
_________________________________________________________________________________
###################################################################################
# SECTION 1:  Prepare Machine
###################################################################################
a. Follow instructions in README.txt to build and install fortress realm component.

b. copy fortress-realm-proxy-[version].jar to TOMCAT_HOME/lib/

# cp [directory-fortress-realm]/proxy/fortress-realm-proxy-[version].jar TOMCAT_HOME/lib

Where [directory-fortress-realm] is base folder of this source package.

c. Configure Fortress Realm for target LDAP server

Copy the fortress.properties, created during [directory-fortress-core] setup, to this package's resource folder.

# cp [directory-fortress-core]/config/fortress.properties [directory-fortress-realm]/src/main/resources

Where [directory-fortress-core] is base folder of the fortress core source package and [directory-fortress-realm] is the current package's home folder.
_________________________________________________________________________________
###################################################################################
# SECTION 2:  Enable Tomcat Realm
###################################################################################
a. edit TOMCAT_HOME/conf/server.xml

b. comment out entry to UserDatabase:

    <!--Resource name="UserDatabase" auth="Container"
              type="org.apache.catalina.UserDatabase"
              description="User database that can be updated and saved"
              factory="org.apache.catalina.users.MemoryUserDatabaseFactory"
              pathname="conf/tomcat-users.xml" /-->

c. add the following:

      <Realm className="org.apache.directory.fortress.realm.tomcat.Tc7AccessMgrProxy"
		debug="0"
        resourceName="UserDatabase"
		containerType="Tomcat7"
        realmClasspath="[directory-fortress-realm]/src/main/resources:[directory-fortress-realm]/impl/target/fortress-realm-impl-uber-[version].jar"
        defaultRoles=""
		/>

Where [directory-fortress-core] is base folder of the fortress core source package.
Where [directory-fortress-realm] is base folder of the fortress realm source package.

d. restart tomcat

e. view the server logs to ensure there are no errors.

f. verify that fortress realm started successfully by viewing following message in catalina.log:

org.apache.directory.fortress.realm.tomcat.Tc7AccessMgrProxy J2EE Tomcat7 policy agent initialization successful
_________________________________________________________________________________
###################################################################################
# SECTION 3:  Test with Tomcat Manager App (Optional)
###################################################################################

Note: this section provides instructions for using the Tomcat Manager application to test Fortress Realm.

a. Enable Tomcat Manager application. note: check the Tomcat documentation on how to do this.

b. Verify/enable role name. Edit TOMCAT_HOME/webapps/manager/WEB-INF/web.xml

    <!-- Security roles referenced by this web application --/>
                    <security-role/>
                      <description/>
                        The role that is required to log in to the Manager Application
                      </description/>
                      <role-name/>manager</role-name/>
                    </security-role/>

c. Run TomcatManagerUser.xml located in [directory-fortress-core]/ldap/setup/ folder.
    See 'SECTION 10. Instructions to load policy data using maven fortress-load.' from directory-fortress-core README.txt.

d. Test logon onto the Tomcat Manager app.

    Enter URL to manager web app:
    http://localhost:8080/manager/html

    Enter creds (tcmanager, password) into basic logon form
    Verify authentication/authorization success to web app.

_________________________________________________________________________________
###################################################################################
# SECTION 4:  Common troubleshooting tips:
###################################################################################

-------------------------------------------------------------------------------------------
i. - Server can't find config files (realmClasspath="/fortressSentry-1.0.0/conf/")
-------------------------------------------------------------------------------------------
Jul 15, 2011 8:21:16 PM us.jts.sentry.tomcat.Tc7AccessMgrProxy initialize
INFO: us.jts.sentry.tomcat.Tc7AccessMgrProxy.initialize - instantiate policy agent name: us.jts.sentry.tomcat.TcAccessMgrImpl
2011-07-15 20:21:17,053 (FATAL) us.jts.configuration.Config static init: Error, null configuration file: fortress.properties
Jul 15, 2011 8:21:17 PM us.jts.sentry.tomcat.Tc7AccessMgrProxy startInternal
SEVERE: us.jts.sentry.tomcat.Tc7AccessMgrProxy.startInternal caught Throwable=java.lang.ExceptionInInitializerError
java.lang.ExceptionInInitializerError
        at us.jts.sentry.J2eePolicyMgrFactory.<clinit>(J2eePolicyMgrFactory.java:32)
        at us.jts.sentry.tomcat.TcAccessMgrImpl.<init>(TcAccessMgrImpl.java:35)
        at sun.reflect.NativeConstructorAccessorImpl.newInstance0(Native Method)
        at sun.reflect.NativeConstructorAccessorImpl.newInstance(NativeConstructorAccessorImpl.java:39)
        at sun.reflect.DelegatingConstructorAccessorImpl.newInstance(DelegatingConstructorAccessorImpl.java:27)
        at java.lang.reflect.Constructor.newInstance(Constructor.java:513)
        at java.lang.Class.newInstance0(Class.java:355)
        at java.lang.Class.newInstance(Class.java:308)
        at us.jts.sentry.tomcat.Tc7AccessMgrProxy.initialize(Tc7AccessMgrProxy.java:112)
        at us.jts.sentry.tomcat.Tc7AccessMgrProxy.startInternal(Tc7AccessMgrProxy.java:236)
        at org.apache.catalina.util.LifecycleBase.start(LifecycleBase.java:145)
        at org.apache.catalina.core.ContainerBase.startInternal(ContainerBase.java:1026)
        at org.apache.catalina.core.StandardEngine.startInternal(StandardEngine.java:291)
        at org.apache.catalina.util.LifecycleBase.start(LifecycleBase.java:145)
        at org.apache.catalina.core.StandardService.startInternal(StandardService.java:443)
        at org.apache.catalina.util.LifecycleBase.start(LifecycleBase.java:145)
        at org.apache.catalina.core.StandardServer.startInternal(StandardServer.java:727)
        at org.apache.catalina.util.LifecycleBase.start(LifecycleBase.java:145)
        at org.apache.catalina.startup.Catalina.start(Catalina.java:620)
        at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
        at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:39)
        at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:25)
        at java.lang.reflect.Method.invoke(Method.java:597)
        at org.apache.catalina.startup.Bootstrap.start(Bootstrap.java:303)
        at org.apache.catalina.startup.Bootstrap.main(Bootstrap.java:431)
Caused by: java.lang.RuntimeException: us.jts.configuration.Config static init: Error, null configuration file: fortress.properties
        at us.jts.configuration.Config.<clinit>(Config.java:51)
        ... 25 more

ACTION:

Ensure step 2c points to Fortress sentry configuration folder that contains fortress.properties config file.

-------------------------------------------------------------------------------------------
ii. - Server can't find proxy jar (Realm className="us.jts.sentry.tomcat.TcAccessMgrProxy")
-------------------------------------------------------------------------------------------
INFO: The APR based Apache Tomcat Native library which allows optimal performance in production environments was not found on the java.library.path: /usr/lib/jvm/java-6-sun-1.6.0.22/jre/lib/i386/server:/usr/lib/jvm/java-6-sun-1.6.0.22/jre/lib/i386:/usr/lib/jvm/java-6-sun-1.6.0.22/jre/../lib/i386:/usr/java/packages/lib/i386:/lib:/usr/lib
Apr 22, 2011 10:24:04 PM org.apache.tomcat.util.digester.Digester startElement
SEVERE: Begin event threw exception
java.lang.ClassNotFoundException: us.jts.sentry.tomcat.TcAccessMgrProxy

ACTION:

Ensure step 1b copied the fortress-realm-proxy jar to TOMCAT_HOME/lib folder.

-------------------------------------------------------------------------------------------
iii. - Server can't find binaries (realmClasspath="...FORTRESS_HOME/lib/fortressSentry-[version].jar")
-------------------------------------------------------------------------------------------
Apr 22, 2011 10:22:25 PM us.jts.sentry.tomcat.TcAccessMgrProxy initialize
SEVERE: Fortress Tomcat Realm.initialize java.lang.ClassNotFoundException=java.lang.ClassNotFoundException: us.jts.sentry.tomcat.TcAccessMgrImpl
Apr 22, 2011 10:22:25 PM us.jts.sentry.tomcat.TcAccessMgrProxy start
SEVERE: Fortress Tomcat Realm.start caught Exception=java.lang.RuntimeException: Fortress Tomcat Realm.initialize java.lang.ClassNotFoundException=java.lang.ClassNotFoundException: us.jts.sentry.tomcat.TcAccessMgrImpl
java.lang.RuntimeException: Fortress Tomcat Realm.initialize java.lang.ClassNotFoundException=java.lang.ClassNotFoundException: us.jts.sentry.tomcat.TcAccessMgrImpl
        at us.jts.sentry.tomcat.TcAccessMgrProxy.initialize(TcAccessMgrProxy.java:118)

ACTION:

Ensure step 2c configuration points fortress-realm-impl-uber jar, i.e. [fortress-realm]/proxy/target/fortress-realm-impl-uber-[version].jar.

-------------------------------------------------------------------------------------------
iv. - Incompatible Tomcat Proxy jar loaded for Tomcat 6 and before
-------------------------------------------------------------------------------------------

The Fortress Realm requires Tomcat version's 7 and beyond.  If you are running Tomcat 4, 5 or 6 and see error that looks like this:

SEVERE: An exception or error occurred in the container during the request processing
java.lang.RuntimeException: us.jts.sentry.tomcat.Tc7AccessMgrProxyauthenticate detected Fortress Tomcat7 Realm not initialized correctly.  Check your Fortress Realm configuration
        at us.jts.sentry.tomcat.Tc7AccessMgrProxy.authenticate(Tc7AccessMgrProxy.java:161)
        at org.apache.catalina.authenticator.FormAuthenticator.authenticate(FormAuthenticator.java:259)
        at org.apache.catalina.authenticator.AuthenticatorBase.invoke(AuthenticatorBase.java:449)
        at org.apache.catalina.core.StandardHostValve.invoke(StandardHostValve.java:127)
        at org.apache.catalina.valves.ErrorReportValve.invoke(ErrorReportValve.java:102)
        at org.apache.catalina.core.StandardEngineValve.invoke(StandardEngineValve.java:109)
        at org.apache.catalina.connector.CoyoteAdapter.service(CoyoteAdapter.java:298)
        at org.apache.coyote.http11.Http11Processor.process(Http11Processor.java:852)
        at org.apache.coyote.http11.Http11Protocol$Http11ConnectionHandler.process(Http11Protocol.java:588)
        at org.apache.tomcat.util.net.JIoEndpoint$Worker.run(JIoEndpoint.java:489)
        at java.lang.Thread.run(Thread.java:662)


ACTION:

Install and use Tomcat version 7 and later in your target machine.