| -------------------------------------------------------------- |
| JoshuaTree Fortress Java Sentry Setup Notes for Tomcat App Sever |
| created: October 8, 2010 |
| last updated: February 18, 2012 |
| -------------------------------------------------------------- |
| ################################################################################### |
| # Guidelines & Tips |
| ################################################################################### |
| |
| - In the document that follows, replace "[version]" with Fortress version label. |
| For example - if Fortress 1.0 release, change fortressProxyTomcat-[version].jar to fortressProxyTomcat-1.0.jar |
| |
| - Restart Tomcat server after any changes to Tomcat config, Fortress config or lib files. |
| |
| - You (usually) do NOT need to restart Tomcat after changes to the LDAP data, i.e. users, passwords, roles. |
| |
| - Steps I - III below are mandatory. |
| |
| - Step IV is optional, for testing purposes. |
| |
| - Common misconfiguration issues related to Fortress, LDAP and Tomcat are located in section III. |
| |
| - Tomcat 7 and beyond uses a different proxy jar. Take special note of this difference in Step I.C. |
| |
| ################################################################################### |
| # Summary of installation steps to be completed before Tomcat can use Fortress LDAP |
| ################################################################################### |
| I. Extract Fortress Java Sentry binaries and config to target server |
| a. copy tar or zip to server |
| b. unzip tar or zip package |
| c. copy fortressProxyTomcat[version].jar to TOMCAT_HOME/lib/ |
| |
| II. Configure Fortress Java Sentry for target LDAP server |
| a. edit Fortress properties file located in FORTRESS_HOME/conf folder |
| b. update ldap host info |
| c. update ldap dn info |
| d. update ldap admin creds |
| e. update ldap connection pool levels |
| |
| III. Configure Tomcat to use Fortress Java Sentry |
| a. edit TOMCAT_HOME/conf/server.xml |
| b. comment out old UserDatabase config |
| c. add Sentry Proxy |
| d. restart Tomcat |
| e. Verify success |
| |
| IV. Test Tomcat Security (Optional) |
| a. Enable Tomcat Manager Web app |
| b. Verify/enable role constraint |
| c. Add role to LDAP |
| d. Add test user to LDAP |
| e. Assign test user the Manager role |
| f. logon Manager app |
| |
| ################################################################################### |
| # I. Instructions to extract Fortress Java Sentry Package to Target System |
| ################################################################################### |
| |
| a. Copy fortressSentryDist-1.0.0[version].zip to hard drive on target server |
| env. |
| |
| b. Extract the zip. The location for archive can vary according to requirements. The location |
| for package will be referred to as "FORTRESS_HOME" later in these instructions. |
| |
| ################################################################################### |
| # II. Instructions to configure Fortress Java Sentry to use Target System LDAP |
| ################################################################################### |
| |
| Note: the 'dist' ant target on this project will set these properties using build.properties settings. |
| |
| a. Edit the FORTRESS_HOME properties file located in $FORTRESS_HOME/conf/fortress.properties |
| |
| b. Set the LDAP Host and port properties: |
| |
| host=localhost (host or ip) |
| port=389 |
| |
| c. Set the LDAP admin creds: |
| |
| admin=cn=Manager\,dc=jts\,dc=com |
| adminPw=secret |
| |
| d. Set the LDAP connection pool info: |
| |
| note: the min/max will vary according to anticipated load on your Tomcat server. For busy systems, the max number of |
| ldap connections may be much higher. |
| |
| minUserConn=1 |
| maxUserConn=10 |
| minConn=1 |
| maxConn=10 |
| |
| ################################################################################### |
| # III. Instructions to configure Tomcat to use Fortress Java Sentry |
| ################################################################################### |
| |
| a. Load the Proxy jar onto server classpath. |
| |
| if Tomcat 7 and beyond: |
| Copy the proxy jar located, FORTRESS_HOME/proxy/fortressProxyTomcat7-[version].jar to the Tomcat Server's lib folder. |
| /opt/apache-tomcat-7.0.21/lib$ sudo cp /home/smckinn/JavaTools/sentry/fortressSentry[version]/proxy/fortressProxyTomcat7-[version].jar . |
| |
| else |
| Copy the proxy jar located, FORTRESS_HOME/proxy/fortressProxyTomcat-[version].jar to the Tomcat Server's lib folder. |
| /opt/apache-tomcat-6.0.24/lib$ sudo cp /home/smckinn/JavaTools/sentry/fortressSentry-[version]/proxy/fortressProxyTomcat-[version].jar . |
| |
| note: This is the only Fortress binary or configuration artifact that will reside directly on Tomcat's server classpath. |
| |
| b. Edit the Tomcat server.xml in the /conf. |
| c. Comment out existing "UserDatabase" config (if present) |
| d. Add the following to Tomcat's server.xml file: |
| |
| <sentry className="us.jts.sentry.tomcat.TcAccessMgrProxy" |
| debug="0" |
| resourceName="UserDatabase" |
| containerType="Tomcat6" |
| realmClasspath="/FORTRESS_HOME/conf:/FORTRESS_HOME/lib/fortressSentry-[version].jar" |
| /> |
| |
| note: "FORTRESS_HOME" will point to root folder of Fortress Java sentry package. i.e. /home/user/fortressSentry-1.0.0 or /usr/local/fortressSentry-1.0.0. These |
| packages will remain off the Tomcat server classpath but must be correct or server will fail to initialize. |
| |
| save and exit. |
| |
| e. Restart Tomcat server |
| |
| smckinn@smckinnlt-lr01:/opt/apache-tomcat-6.0.24/bin$ sudo ./startup.sh |
| |
| f. verify that sentry started successfully by viewing following message in catalina.log: |
| |
| smckinn@smckinnlt-lr01:/opt/apache-tomcat-6.0.24/bin$ tail -f -n10000 ../logs/catalina.out |
| |
| ... |
| INFO: us.jts.sentry.tomcat.TcAccessMgrProxy J2EE policy agent initialization successful |
| |
| If Tomcat 7 and beyond: |
| |
| INFO: us.jts.sentry.tomcat.Tc7AccessMgrProxy J2EE Tomcat7 policy agent initialization successful |
| |
| ------------------------------------------- |
| 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 3c points to Fortress sentry configuration folder. |
| |
| ------------------------------------------------------------------------------------------- |
| 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 1c copied the Fortress sentry 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 3c configuration points fortressSentry jar, i.e. FORTRESS_HOME/lib/fortressProxyTomcat[version].jar. |
| |
| ------------------------------------------------------------------------------------------- |
| iv. - Incompatible Tomcat Proxy jar loaded for Tomcat 7 and beyond |
| ------------------------------------------------------------------------------------------- |
| |
| The Tomcat realm base class changed between Tomcat version's 6 and 7. If you are running Tomcat7 and see error that looks like this: |
| |
| Jun 4, 2011 3:01:41 PM org.apache.tomcat.util.digester.Digester startElement |
| SEVERE: Begin event threw error |
| java.lang.VerifyError: class us.jts.sentry.tomcat.TcAccessMgrProxy overrides final method start.()V |
| at java.lang.ClassLoader.defineClass1(Native Method) |
| at java.lang.ClassLoader.defineClassCond(ClassLoader.java:632) |
| at java.lang.ClassLoader.defineClass(ClassLoader.java:616) |
| at java.security.SecureClassLoader.defineClass(SecureClassLoader.java:141) |
| at java.net.URLClassLoader.defineClass(URLClassLoader.java:283) |
| at java.net.URLClassLoader.access$000(URLClassLoader.java:58) |
| at java.net.URLClassLoader$1.run(URLClassLoader.java:197) |
| at java.security.AccessController.doPrivileged(Native Method) |
| at java.net.URLClassLoader.findClass(URLClassLoader.java:190) |
| at java.lang.ClassLoader.loadClass(ClassLoader.java:307) |
| at java.lang.ClassLoader.loadClass(ClassLoader.java:248) |
| at org.apache.tomcat.util.digester.ObjectCreateRule.begin(ObjectCreateRule.java:144) |
| at org.apache.tomcat.util.digester.Digester.startElement(Digester.java:1282) |
| at com.sun.org.apache.xerces.internal.parsers.AbstractSAXParser.startElement(AbstractSAXParser.java:501) |
| at com.sun.org.apache.xerces.internal.parsers.AbstractXMLDocumentParser.emptyElement(AbstractXMLDocumentParser.java:179) |
| at com.sun.org.apache.xerces.internal.impl.XMLDocumentFragmentScannerImpl.scanStartElement(XMLDocumentFragmentScannerImpl.java:1343) |
| at com.sun.org.apache.xerces.internal.impl.XMLDocumentFragmentScannerImpl$FragmentContentDriver.next(XMLDocumentFragmentScannerImpl.java:2755) |
| at com.sun.org.apache.xerces.internal.impl.XMLDocumentScannerImpl.next(XMLDocumentScannerImpl.java:648) |
| at com.sun.org.apache.xerces.internal.impl.XMLDocumentFragmentScannerImpl.scanDocument(XMLDocumentFragmentScannerImpl.java:511) |
| at com.sun.org.apache.xerces.internal.parsers.XML11Configuration.parse(XML11Configuration.java:808) |
| at com.sun.org.apache.xerces.internal.parsers.XML11Configuration.parse(XML11Configuration.java:737) |
| at com.sun.org.apache.xerces.internal.parsers.XMLParser.parse(XMLParser.java:119) |
| at com.sun.org.apache.xerces.internal.parsers.AbstractSAXParser.parse(AbstractSAXParser.java:1205) |
| at com.sun.org.apache.xerces.internal.jaxp.SAXParserImpl$JAXPSAXParser.parse(SAXParserImpl.java:522) |
| at org.apache.tomcat.util.digester.Digester.parse(Digester.java:1543) |
| at org.apache.catalina.startup.Catalina.load(Catalina.java:554) |
| at org.apache.catalina.startup.Catalina.load(Catalina.java:595) |
| 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.load(Bootstrap.java:262) |
| at org.apache.catalina.startup.Bootstrap.main(Bootstrap.java:430) |
| |
| ACTION: |
| |
| You have the wrong Tomcat Proxy jar on the server's classpath. You need to get the proxy jar that is compatible with Tomcat version 7 and beyond. |
| Ensure step 3c configuration points fortressProxyTomcat7-[version].jar, i.e. FORTRESS_HOME/lib/fortressProxyTomcat7-[version].jar. |
| |
| ------------------------------------------------------------------------------------------- |
| v. - Incompatible Tomcat Proxy jar loaded for Tomcat 6 and before |
| ------------------------------------------------------------------------------------------- |
| |
| The Tomcat realm base class changed between Tomcat version's 6 and 7. 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: |
| |
| You have the wrong Tomcat Proxy jar on the server's classpath. You need to get the proxy jar that is compatible with Tomcat version 6 and before: |
| Ensure step 3c configuration points fortressProxyTomcat-[version].jar, i.e. FORTRESS_HOME/lib/fortressProxyTomcat-[version].jar. |
| |
| |
| ################################################################################### |
| # IV. Instructions to test Tomcat Security |
| ################################################################################### |
| |
| 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. Add Role to access Tomcat Manager application: |
| |
| Note: If Fortress 'init-slapd' ant task was run this data will already be loaded into the directory. |
| |
| If Tomcat 7 and beyond: |
| Add Role named "manager-gui": |
| else if Tomcat 6 and before: |
| Add Role named "manager": |
| |
| d. Add User named "tcmanager": (or whatever you want to nanme it) |
| |
| e. Assign Test User "tcmanager" Role "manager", (if Tomcat 7 this role is "manager-gui") |
| |
| f. Test logon onto the Tomcat Manager app. |
| |
| i. Enter URL to manager web app: |
| http://localhost:8080/manager/html |
| ii. enter creds (tcmanager, password) into basic logon form |
| iii. verify authentication/authorization success to web app. |