Return-Path: X-Original-To: apmail-directory-commits-archive@www.apache.org Delivered-To: apmail-directory-commits-archive@www.apache.org Received: from mail.apache.org (hermes.apache.org [140.211.11.3]) by minotaur.apache.org (Postfix) with SMTP id 18FCB18474 for ; Sat, 23 Jan 2016 21:06:54 +0000 (UTC) Received: (qmail 5481 invoked by uid 500); 23 Jan 2016 21:06:53 -0000 Delivered-To: apmail-directory-commits-archive@directory.apache.org Received: (qmail 5434 invoked by uid 500); 23 Jan 2016 21:06:53 -0000 Mailing-List: contact commits-help@directory.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: dev@directory.apache.org Delivered-To: mailing list commits@directory.apache.org Received: (qmail 5425 invoked by uid 99); 23 Jan 2016 21:06:53 -0000 Received: from git1-us-west.apache.org (HELO git1-us-west.apache.org) (140.211.11.23) by apache.org (qpsmtpd/0.29) with ESMTP; Sat, 23 Jan 2016 21:06:53 +0000 Received: by git1-us-west.apache.org (ASF Mail Server at git1-us-west.apache.org, from userid 33) id 67C21DFF8E; Sat, 23 Jan 2016 21:06:53 +0000 (UTC) Content-Type: text/plain; charset="us-ascii" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit From: smckinney@apache.org To: commits@directory.apache.org Message-Id: X-Mailer: ASF-Git Admin Mailer Subject: directory-fortress-realm git commit: last of the readme cleanup Date: Sat, 23 Jan 2016 21:06:53 +0000 (UTC) Repository: directory-fortress-realm Updated Branches: refs/heads/master 1651b3e68 -> d65b24fb0 last of the readme cleanup 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/d65b24fb Tree: http://git-wip-us.apache.org/repos/asf/directory-fortress-realm/tree/d65b24fb Diff: http://git-wip-us.apache.org/repos/asf/directory-fortress-realm/diff/d65b24fb Branch: refs/heads/master Commit: d65b24fb0b5c3ddd71e93ea15e2e349f0341f50d Parents: 1651b3e Author: Shawn McKinney Authored: Sat Jan 23 14:11:03 2016 -0600 Committer: Shawn McKinney Committed: Sat Jan 23 14:11:03 2016 -0600 ---------------------------------------------------------------------- REALM-CONTEXT-SETUP.md | 60 +++++++++++++++++++++++++-------------------- REALM-HOST-SETUP.md | 9 +++---- 2 files changed, 38 insertions(+), 31 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/directory-fortress-realm/blob/d65b24fb/REALM-CONTEXT-SETUP.md ---------------------------------------------------------------------- diff --git a/REALM-CONTEXT-SETUP.md b/REALM-CONTEXT-SETUP.md index 7dec13e..1aca429 100644 --- a/REALM-CONTEXT-SETUP.md +++ b/REALM-CONTEXT-SETUP.md @@ -26,8 +26,8 @@ * Document Overview * Tips for first-time users. * SECTION 1. Prerequisites. - * SECTION 2. Prepare the Fortress Realm. - * SECTION 3. Enable Fortress Realm for Web context. + * SECTION 2. Prepare Tomcat for the Context Realm. + * SECTION 3. Enable Web App to use the Context Realm. * More on the Realm Proxy ___________________________________________________________________________________ @@ -64,24 +64,25 @@ Minimum software requirements: Everything else covered in steps that follow. Tested on Debian, Centos & Windows machines. ------------------------------------------------------------------------------- -## SECTION 2. Prepare the Fortress Realm +## SECTION 2. Prepare Tomcat for the Context Realm -1. Follow instructions in README.txt to build and install fortress realm component. - -2. copy fortress-realm-proxy-[version].jar to TOMCAT_HOME/lib/ +1. copy fortress-realm-proxy-[version].jar to **TOMCAT_HOME**/lib/ ``` - cp FORTRESS_REALM_HOME/proxy/fortress-realm-proxy-[version].jar TOMCAT_HOME/lib + cp $FORTRESS_REALM_HOME/proxy/fortress-realm-proxy-[version].jar $TOMCAT_HOME/lib ``` -3. Restart tomcat server instance for changes to take effect. +2. Restart Tomcat server for changes to take effect. ------------------------------------------------------------------------------- -## SECTION 3. Enable Fortress Realm for Web context +## SECTION 3. Enable Web App to use the Context Realm 1. Add a context.xml file to the META-INF folder of target web app. + ``` + vi $MY_APP_HOME/src/main/resources/META-INF/conf/context.xml + ``` -2. Add the following: +2. Add to the file: ``` ``` - Where *myappcontext* is the web context for your web application. + Where *myappcontext* is the web context for *your* web application. -3. Add security constraints to target web.xml: +3. Edit the web app's deployment descriptor: + ``` + vi $MY_APP_HOME/src/main/webapp/WEB-INF/web.xml + ``` + +4. Add Java EE security constraint declarations to the file: ``` ... @@ -128,7 +134,7 @@ Everything else covered in steps that follow. Tested on Debian, Centos & Window *Fortress Realm follows standard Java EE security semantics.* -4. Add the maven dependencies to the Web app. +5. Add the maven dependencies to the Web app. ``` @@ -141,10 +147,14 @@ Everything else covered in steps that follow. Tested on Debian, Centos & Window *Where project.version contains target version, e.g. 1.0-RC41* -5. Add the fortress.properties file to the classpath of the Web app. +6. Add the fortress.properties file to the classpath of the Web app. - *It contains the coordinates to the target LDAP server.* + Copy the fortress.properties, created during **FORTRESS_CORE_HOME** setup, to app resource folder. + ``` + cp $FORTRESS_CORE_HOME/config/fortress.properties $MY_APP_HOME/src/main/resources + ``` +7. Verify a match for target LDAP server coordinates. ``` # This param tells fortress what type of ldap server in use: ldap.server.type=apacheds @@ -177,14 +187,14 @@ Everything else covered in steps that follow. Tested on Debian, Centos & Window enable.pool.reconnect=true ``` -6. Add two other config files to classpath. +8. Add two other files to classpath of the Web app. ``` cp $FORTRESS_REALM_HOME/conf/echcache.xml $MY_APP_HOME/src/main/resources cp $FORTRESS_REALM_HOME/conf/log4j.properties $MY_APP_HOME/src/main/resources ``` -7. Verify the configuration artifacts are properly staged to your app. +9. Verify the configuration artifacts are properly staged to your app resource folder. ``` x@machine:~/MY_APP_HOME/src/main/resources$ ls -l ... @@ -193,13 +203,13 @@ Everything else covered in steps that follow. Tested on Debian, Centos & Window -rw-rw-r-- 1 x y 1235 Jan 23 12:41 log4j.properties ... ``` - *Fortress needs all three files.* + *Fortress needs all three files in its classpath.* -8. Redeploy web application to Tomcat. +10. Redeploy web application to Tomcat. -9. 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). +11. 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). -10. Verify that realm is operating properly per Tomcat server log: +12. Verify that realm is operating properly per Tomcat server log: ``` tail -f -n10000 $TOMCAT_HOME/logs/catalina.out @@ -208,14 +218,12 @@ Everything else covered in steps that follow. Tested on Debian, Centos & Window ... ``` -11. You have enabled security for a single Web app running in Tomcat. This will enforce declarative authentication and coarse-gained authorization (isUserInRole) checks. For a look at how to apply more, check out [Apache Fortress Demo End-to-End Security Example](https://github.com/shawnmckinney/apache-fortress-demo). - Realm Usage Notes: -* This automatically enforces authentication and coarse-gained authorization (isUserInRole) checking. -* Repeat steps in this section for each additional app to use Java EE security enforcement. +* This automatically enforces authentication and coarse-gained authorization (isUserInRole) checking for a single web app. +* Repeat steps in this section for each additional app using the Fortress Realm. ## More on the Realm Proxy -The fortress realm proxy jar contains a *shim* that uses a URLClassLoader to reach its implementation libs. It prevents the realm impl libs, pulled in as dependency to your web app, from interfering with Tomcat's system classpath thus providing an error free deployment process w/out classloader issues. The realm proxy offers the flexibility for each web app to determine its own version/type of security realm to use, satisfying a variety of requirements related to web hosting and multitenancy. +The fortress realm proxy jar contains a *shim* that uses a URLClassLoader to reach its implementation libs. It prevents the realm impl libs, pulled in as dependency to your web app, from interfering with Tomcat's system classpath thus providing an error free deployment process w/out classloader issues. This satisfies requirements related to web hosting and multitenancy. ___________________________________________________________________________________ #### END OF README-CONTEXT-SETUP.md \ No newline at end of file http://git-wip-us.apache.org/repos/asf/directory-fortress-realm/blob/d65b24fb/REALM-HOST-SETUP.md ---------------------------------------------------------------------- diff --git a/REALM-HOST-SETUP.md b/REALM-HOST-SETUP.md index 0775ff0..6dd4c13 100644 --- a/REALM-HOST-SETUP.md +++ b/REALM-HOST-SETUP.md @@ -27,9 +27,9 @@ * Document Overview * Tips for first-time users. * SECTION 1. Prerequisites. - * SECTION 2. Prepare the Fortress Realm. + * SECTION 2. Prepare Tomcat for the Global Realm. * SECTION 3. Enable Tomcat Global Security. - * SECTION 4. Enable Web Application to use Apache Fortress Realm + * SECTION 4. Enable Web App to use the Global Realm. * SECTION 5. Test with Tomcat Manager App (Optional). * SECTION 6. Common troubleshooting tips. * More on the Realm Proxy @@ -68,7 +68,7 @@ Minimum software requirements: Everything else covered in steps that follow. Tested on Debian, Centos & Windows machines. ------------------------------------------------------------------------------- -## SECTION 2. Prepare the Fortress Realm. +## SECTION 2. Prepare Tomcat for the Global Realm 1. Stage the Fortress Realm Proxy jar. @@ -134,7 +134,6 @@ ________________________________________________________________________________ ## SECTION 3. Enable Tomcat Global Security 1. Edit **TOMCAT_HOME**/conf/server.xml: - ``` vi $TOMCAT_HOME/conf/server.xml ``` @@ -175,7 +174,7 @@ ________________________________________________________________________________ ``` _________________________________________________________________________________ -## SECTION 4. Enable Web Application to use Apache Fortress Realm +## SECTION 4. Enable Web App to use the Global Realm 1. Add security constraints to the target web.xml deployment descriptor: ```