#
#   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 a SINGLE Web Context under Tomcat
Last updated: February 9, 2015
-----------------------------------------------------------------------------------
###################################################################################
# Guidelines & Tips
###################################################################################
- This document describes how to enable Fortress Realm to provide security for
  a single context within a Tomcat server host.  Follow these steps and this component will be security
  provider for a single application within a particular Tomcat server instance.

- It is possible to enable Fortress Realm to provide security for all applications within a Tomcat server host.
  Follow the instructions in REALM-HOST-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 REALM-HOST-SETUP.txt.
___________________________________________________________________________________
###################################################################################
# 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. Restart tomcat server instance for changes to take effect.
_________________________________________________________________________________
###################################################################################
# SECTION 2:  Enable Tomcat Realm for Web context
###################################################################################
a. Add a context.xml file to the META-INF folder of target web app.

b. Add the following:

<Context path="/commander" reloadable="true">

    <Realm className="org.apache.directory.fortress.realm.tomcat.Tc7AccessMgrProxy"
           debug="0"
           resourceName="UserDatabase"
           defaultRoles=""
           containerType="TomcatContext"
           realmClasspath=""
            />
</Context>

c. Add security constraints to target web.xml:

        ...
        <security-constraint>
            <display-name>Commander Security Constraint</display-name>
            <web-resource-collection>
                <web-resource-name>Protected Area</web-resource-name>
                <!-- Define the context-relative URL(s) to be protected -->
                <url-pattern>/*</url-pattern>
            </web-resource-collection>
            <auth-constraint>
                <!-- Anyone with one of the listed roles may access this area -->
                <role-name>MY_ROLE_NAME</role-name>
                ...

            </auth-constraint>
        </security-constraint>

    <!-- Example of HTTP Basic Authentication Setup. -->
    <login-config>
		<auth-method>BASIC</auth-method>
        <realm-name>FortressSecurityRealm</realm-name>
    </login-config>

    <!-- Security roles referenced by this web application -->
    <security-role>
        <role-name>MY_ROLE_NAME</role-name>
    </security-role>
    ...

Note:  Fortress Realm follows standard Java EE security semantics.  The above is a very simple example.
For more info on how Java EE security is used:
http://docs.oracle.com/javaee/6/tutorial/doc/bnbwj.html

d. Redeploy web application to Tomcat.

e. Login to the web application.  Users that successfully authenticate and have activated role(s) listed in auth-constraints have access to all resources matching the url-pattern(s).

f. View the Tomcat server logs to ensure there are no errors.

g. Verify that fortress realm is operating properly by viewing the following in catalina.log:

org.apache.directory.fortress.realm.tomcat.Tc7AccessMgrProxy J2EE Tomcat7 policy agent initialization successful