You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@directory.apache.org by sm...@apache.org on 2015/02/09 17:42:48 UTC
directory-fortress-realm git commit: FC-56 - refine and cleanup realm
setup
Repository: directory-fortress-realm
Updated Branches:
refs/heads/master fb1f512ab -> 20f332bf3
FC-56 - refine and cleanup realm setup
Project: http://git-wip-us.apache.org/repos/asf/directory-fortress-realm/repo
Commit: http://git-wip-us.apache.org/repos/asf/directory-fortress-realm/commit/20f332bf
Tree: http://git-wip-us.apache.org/repos/asf/directory-fortress-realm/tree/20f332bf
Diff: http://git-wip-us.apache.org/repos/asf/directory-fortress-realm/diff/20f332bf
Branch: refs/heads/master
Commit: 20f332bf39d2976ab2134034a0e2a861591c4da3
Parents: fb1f512
Author: Shawn McKinney <sm...@apache.org>
Authored: Mon Feb 9 10:42:35 2015 -0600
Committer: Shawn McKinney <sm...@apache.org>
Committed: Mon Feb 9 10:42:35 2015 -0600
----------------------------------------------------------------------
README.txt | 10 +-
REALM-CONTEXT-SETUP.txt | 131 +++++++++++++++++++
REALM-HOST-SETUP.txt | 230 +++++++++++++++++++++++++++++++++
TOMCAT-GLOBAL-SECURITY-NOTES.txt | 231 ----------------------------------
4 files changed, 370 insertions(+), 232 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/directory-fortress-realm/blob/20f332bf/README.txt
----------------------------------------------------------------------
diff --git a/README.txt b/README.txt
index f10d4ca..a99c3a6 100755
--- a/README.txt
+++ b/README.txt
@@ -63,4 +63,12 @@ e. Build the javadoc:
f. To view Fortress Realm Setup Notes for Tomcat Container point your browser here:
file:///[package home]/target/site/apidocs/org/apache/directory/fortress/realm/tomcat/package-summary.html
-(where [package_home] is location of directory-fortress-realm base package)
\ No newline at end of file
+(where [package_home] is location of directory-fortress-realm base package)
+
+___________________________________________________________________________________
+###################################################################################
+# SECTION 3: Instructions to use Fortress Realm
+###################################################################################
+
+a. For a single web application context under Tomcat: REALM-CONTEXT-SETUP.txt
+b. For all web application contexts under Tomcat: REALM-HOST-SETUP.txt
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/directory-fortress-realm/blob/20f332bf/REALM-CONTEXT-SETUP.txt
----------------------------------------------------------------------
diff --git a/REALM-CONTEXT-SETUP.txt b/REALM-CONTEXT-SETUP.txt
new file mode 100644
index 0000000..ec09488
--- /dev/null
+++ b/REALM-CONTEXT-SETUP.txt
@@ -0,0 +1,131 @@
+#
+# 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 in section III.
+___________________________________________________________________________________
+###################################################################################
+# 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.
+
+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-core] is base folder of the fortress core 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 is compliant with Java EE security semantics. The above is a one simple example.
+For more info:
+http://docs.oracle.com/javaee/6/tutorial/doc/bnbwj.html
+
+d. Redeploy web application.
+
+e. Login to the app. Users that successfully authenticate and have activated at least one role listed in auth-constraints gain access to app resources matching the url-pattern.
+
+f. View the 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
+_________________________________________________________________________________
+###################################################################################
+# Common troubleshooting tips:
+###################################################################################
+
+Found inside REALM-HOST-SETUP.txt
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/directory-fortress-realm/blob/20f332bf/REALM-HOST-SETUP.txt
----------------------------------------------------------------------
diff --git a/REALM-HOST-SETUP.txt b/REALM-HOST-SETUP.txt
new file mode 100644
index 0000000..face84a
--- /dev/null
+++ b/REALM-HOST-SETUP.txt
@@ -0,0 +1,230 @@
+#
+# 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 ALL Web Applications under Tomcat
+Last updated: February 9, 2015
+-----------------------------------------------------------------------------------
+###################################################################################
+# Guidelines & Tips
+###################################################################################
+- This document describes how to enable Fortress Realm to provide security for
+ Tomcat server virtual host. Follow these steps and this component will be default security
+ provider for all applications within a particular Tomcat server instance.
+
+- It is not necessary to enable Fortress Realm in this way to enable web app to use Java EE security.
+ If you want 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 in section III.
+___________________________________________________________________________________
+###################################################################################
+# 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.
+
+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-core] is base folder of the fortress core 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
+###################################################################################
+
+Note: this section provides instructions for using the Tomcat Manager application to test Fortress Realm.
+This is not necessary if you have your own Java EE security enabled web application to test with.
+
+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 fortress-core load file TomcatManagerUser.xml
+
+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.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/directory-fortress-realm/blob/20f332bf/TOMCAT-GLOBAL-SECURITY-NOTES.txt
----------------------------------------------------------------------
diff --git a/TOMCAT-GLOBAL-SECURITY-NOTES.txt b/TOMCAT-GLOBAL-SECURITY-NOTES.txt
deleted file mode 100644
index 7766d95..0000000
--- a/TOMCAT-GLOBAL-SECURITY-NOTES.txt
+++ /dev/null
@@ -1,231 +0,0 @@
-#
-# 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 GLOBAL SECURITY
-Last updated: February 9, 2015
---------------------------------------------------------------
-###################################################################################
-# Guidelines & Tips
-###################################################################################
-
-- This document describes how to enable Fortress Realm to provide global security for
- Tomcat server. Follow these steps and this component will be default security
- provider for all applications within a particular Tomcat server instance.
-
-- It is not necessary to enable Fortress Realm in this way to enable web app to use Java EE security.
- If you want to only target the application, and not enable for entire container, follow the Tomcat instructions in the 'Fortress Ten Minute Guide'
-
-- 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 in section III.
-___________________________________________________________________________________
-###################################################################################
-# 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.
-
-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-core] is base folder of the fortress core 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 sentry 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
-###################################################################################
-
-Note: this section provides instructions for using the Tomcat Manager application to test Fortress Realm.
-This is not necessary if you have your own Java EE security enabled web application to test with.
-
-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 fortress-core load file TomcatManagerUser.xml
-
-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.
\ No newline at end of file