| # |
| # 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. |