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