portals-jetspeed-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From tay...@apache.org
Subject svn commit: r360567 - in /portals/jetspeed-1/trunk/xdocs: cma.xml stylesheets/project.xml
Date Sun, 01 Jan 2006 21:58:11 GMT
Author: taylor
Date: Sun Jan  1 13:58:10 2006
New Revision: 360567

URL: http://svn.apache.org/viewcvs?rev=360567&view=rev
Log:
documentation for container managed authentication

Added:
    portals/jetspeed-1/trunk/xdocs/cma.xml
Modified:
    portals/jetspeed-1/trunk/xdocs/stylesheets/project.xml

Added: portals/jetspeed-1/trunk/xdocs/cma.xml
URL: http://svn.apache.org/viewcvs/portals/jetspeed-1/trunk/xdocs/cma.xml?rev=360567&view=auto
==============================================================================
--- portals/jetspeed-1/trunk/xdocs/cma.xml (added)
+++ portals/jetspeed-1/trunk/xdocs/cma.xml Sun Jan  1 13:58:10 2006
@@ -0,0 +1,344 @@
+<?xml version="1.0" encoding="iso-8859-1"?>
+<!--
+Copyright 2004 The Apache Software Foundation
+
+Licensed 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.
+-->
+<document>
+<properties>
+  <title>Container Manager Authentication</title>
+  <authors>
+    <person name="David Sean Taylor" email="taylor@apache.org"/>
+  </authors>
+</properties>
+<body>
+  <section name="Container Managed Authentication">
+    <p>
+	This documentation provides an example of integrating Jetspeed 1.6 with an application server's
+container managed security. In particular, with container managed user authentication.
+(The application server is the container). 		
+	</p>
+	<p>
+We demonstrate how to get an authenticated user in a standard manner, via the Servlet API,

+and integrate those authenticated users with Jetspeed-1 Security. Our custom session validator
+gets the user principal from the servlet API:
+	</p>
+<source><![CDATA[				
+            //String userName = data.getRequest().getRemoteUser();            
+            Principal principal = data.getRequest().getUserPrincipal();
+]]></source>			
+	<p>
+	and then makes this user principal available to Jetspeed and portlets running inside
+	Jetspeed from RunData:		
+	</p>
+<source><![CDATA[				
+	JetspeedUser user = rundata.getJetspeedUser();	  
+]]></source>			
+	<p>
+This kind of authentication is often accomplished using the application
+server's authentication mechanisms, which are often based (but not always) on the JAAS 
+(Java Authentication and Authorization Service) standard.
+	</p>
+	</section>
+	<section name='Tomcat Realms'>
+	<p>
+In this example, we integrate with the Apache Tomcat application server container.
+Tomcat has the concept of "realms":		
+	</p>
+	<p><a href='http://tomcat.apache.org/tomcat-5.5-doc/realm-howto.html'>Tomcat
5 Realms</a></p>
+	<p>
+For the clearest and simplest demonstration, we will integrate with Tomcat's memory realm:
+	</p>
+	<p><a href='http://tomcat.apache.org/tomcat-5.5-doc/realm-howto.html#MemoryRealm'>Memory
Realms</a></p>				
+	<p>
+MemoryRealm is a simple demonstration implementation of the Tomcat 5 Realm interface. 
+It is not designed for production use. At startup time, MemoryRealm loads information about
all users, 
+and their corresponding roles, from an XML document (by default, this document is loaded
from 
+$CATALINA_HOME/conf/tomcat-users.xml). Changes to the data in this file are not recognized

+until Tomcat is restarted.		
+	</p>
+	<p>
+Additionally, we will integrate with roles defined in the Tomcat 5 realm.
+Although this example only works with Tomcat 5, the same approach can be taken 
+with other application servers. The Jetspeed JAAS Session Validator will plugin
+to any Java Servlet container that implements the Servlet Spec 2.2 or higher.		
+	</p>
+	</section>
+	<section name='Jetspeed JAAS Session Validator'>
+	<p>
+The Jetspeed JAAS Session Validator plugs into the Jetspeed module architecture.
+It replaces the default session validator with a Servlet API-aware implementation.
+The default session validator gets the authenticated Jetspeed(Turbine)User from 
+the Turbine rundata, a non-standard implementation of Java web application security.		
+	</p>
+	<P>
+The JAAS Session validator populates the Jetspeed User via the servlet.getUserPrincipal()
call.
+ When using this session validator, authentication is delegated to the Application Server.
	
+	</P>
+	<p>To configure the JAAS session validator, we override the TurbineResources.properties
and
+	set Jetspeed's session validator in the property file found in the Jetspeed source under:
+<source><![CDATA[						
+cma/WEB-INF/conf/TurbineResources.properties.merge
+]]></source>			
+<p>Here is the actual property override:</p>		
+<source><![CDATA[						
+action.sessionvalidator=JAASSessionValidator
+]]></source>						
+	</p>		
+	</section>
+	<section name='Building the Example'>
+	<p>
+We provide an example of using Tomcat container managed authentication with Jetspeed.
+You can run this example directly from the Jetspeed distribution, however it requires
+having Tomcat 5 installed on your computer.		
+	</p>
+	<p>
+Required Properties:
+	</p>
+<source><![CDATA[						
+# your app server home (tomcat)
+maven.war.appserver.home = /home/jetspeed/jakarta-tomcat-5.0.30
+]]></source>			
+<p>
+To build, simply type from the jetspeed root directory:
+</p>
+<source><![CDATA[							
+maven cma
+]]></source>					
+	<p>
+	The "cma" goal will build a modified version of Jetspeed 1.6 that requires logging in 
+	with Tomcat, not with Jetspeed. It also tries to deploy the jetspeed.war file directly
+	into Tomcat using the "maven.war.appserver.home" property to locate Tomcat.
+	When you navigate to the Jetspeed 1.6 portal from you browser,
+    Tomcat will challenge you for a username and password. You will
+	not be allowed to enter the portal until you type in the correct username
+	and password. The same users and credentials are required as in the default
+	system: 
+	<table>
+		<tr>
+		<th>Username</th>
+		<th>Password</th>
+		</tr>
+		<tr>
+		<td>admin</td>
+		<td>jetspeed</td>
+		</tr>
+		<tr>
+		<td>turbine</td>
+		<td>turbine</td>
+		</tr>		
+	</table>
+	</p>
+	</section>
+	<section name='Implementation: modifying the web.xml'>
+<p>
+  JAAS Session validator populates the Jetspeed User via the servlet.getUserPrincipal() call
+  When using this session validator, Authentication is delegated to the Application Server.
+  Recommend disabling all user login functionality via Jetspeed, and using your web.xml
+  to protect access to all Jetspeed resources.
+</p>				
+<p>
+In the web.xml, we place some additional security settings after resource-ref or welcome-file-list:
+<source><![CDATA[		
+  <security-constraint>
+    <display-name>Jetspeed Security</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>
+  
+      <!-- If you list http methods, only those methods are protected -->
+      <http-method>DELETE</http-method>
+      <http-method>GET</http-method>
+      <http-method>POST</http-method>
+      <http-method>PUT</http-method>
+    </web-resource-collection>
+    <auth-constraint>
+      <!-- Anyone with one of the listed roles may access this area -->
+      <role-name>user</role-name>
+      <role-name>admin</role-name>
+    </auth-constraint>
+  
+    <!--
+      <user-data-constraint>
+        <transport-guarantee>CONFIDENTIAL</transport-guarantee>
+      </user-data-constraint>
+    -->
+  </security-constraint>
+
+  <login-config>
+    <auth-method>BASIC</auth-method>
+    <realm-name>Jetspeed BASIC Authentication</realm-name>
+  </login-config>
+  
+  <!-- Default login configuration uses form-based authentication -->
+  <!--
+    <login-config>
+      <auth-method>FORM</auth-method>
+      <realm-name>Example Form-Based Authentication Area</realm-name>
+      <form-login-config>
+        <form-login-page>/jsp/security/protected/login.jsp</form-login-page>
+        <form-error-page>/jsp/security/protected/error.jsp</form-error-page>
+      </form-login-config>
+    </login-config>
+  -->
+  
+  <!-- Security roles referenced by this web application -->
+  <security-role>
+    <role-name>admin</role-name>
+  </security-role>
+  <security-role>
+    <role-name>user</role-name>
+  </security-role>
+  <security-role>
+    <role-name>guest</role-name>
+  </security-role>				
+]]></source>			
+</p>		
+<subsection name='Securing the Jetspeed Application'>
+<p>The Jetspeed application is secured in its entirety using the security constraint
element
+	of the web.xml. Here we secure the entire application with the url-pattern of "/*". The
wildcard
+	secures the entire Jetspeed webapp for all http-methods listed below. Note that we additionally
+	add an authorization constraint on this security constraint, requiring that authenticated
users
+	also have one of the listed roles (admin or user).
+</p>
+<source><![CDATA[						
+  <security-constraint>
+    <display-name>Jetspeed Security</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>
+  
+      <!-- If you list http methods, only those methods are protected -->
+      <http-method>DELETE</http-method>
+      <http-method>GET</http-method>
+      <http-method>POST</http-method>
+      <http-method>PUT</http-method>
+    </web-resource-collection>
+    <auth-constraint>
+      <!-- Anyone with one of the listed roles may access this area -->
+      <role-name>user</role-name>
+      <role-name>admin</role-name>
+    </auth-constraint>
+  
+  </security-constraint>
+]]></source>					
+</subsection>
+<subsection name='Defining the Login Method in the web.xml'>
+<p>In the web.xml, we also define the login method. For our example here, we define
+a "BASIC" HTTP authentication method often known as 'challenge' authentication. When
+the browser navigates to the jetspeed webapp, a dialog box is displayed asking for a 
+username and password. Optionally, we could have also used form-based authentication as 
+shown below in comments:
+</p>
+<source><![CDATA[						
+  <login-config>
+    <auth-method>BASIC</auth-method>
+    <realm-name>Jetspeed BASIC Authentication</realm-name>
+  </login-config>
+  
+  <!-- Default login configuration uses form-based authentication -->
+  <!--
+    <login-config>
+      <auth-method>FORM</auth-method>
+      <realm-name>Example Form-Based Authentication Area</realm-name>
+      <form-login-config>
+        <form-login-page>/jsp/security/protected/login.jsp</form-login-page>
+        <form-error-page>/jsp/security/protected/error.jsp</form-error-page>
+      </form-login-config>
+    </login-config>
+  -->
+]]></source>					
+</subsection>
+<subsection name='Defining Application Roles in the web.xml'>
+<p>In the web.xml, we define the required roles by this application. In our example,
+the roles are admin, user and guest. This is somewhat limiting, as Jetspeed 1.6 allows
+for the roles to be added/updated/removed at runtime. 
+</p>
+<source><![CDATA[						
+  <!-- Security roles referenced by this web application -->
+  <security-role>
+    <role-name>admin</role-name>
+  </security-role>
+  <security-role>
+    <role-name>user</role-name>
+  </security-role>
+  <security-role>
+    <role-name>guest</role-name>
+  </security-role>				
+]]></source>					
+</subsection>
+
+<subsection name='Defining Role Links in the web.xml'>
+<p>Role links (references) are placed in the servlet element where the Turbine servlet
is defined:
+</p>
+<source><![CDATA[						
+  <security-role-ref>
+   <role-name>user</role-name>  <!--passed to isUserInRole()-->
+   <role-link>user</role-link>  <!--Jetspeed role name-->
+  </security-role-ref>
+ 
+  <security-role-ref>
+    <role-name>admin</role-name>
+    <role-link>admin</role-link>
+  </security-role-ref>
+ 
+  <security-role-ref>
+    <role-name>guest</role-name>
+    <role-link>guest</role-link>
+  </security-role-ref>
+]]></source>					
+</subsection>
+			
+			
+<p>You can find the complete, modified version of our web.xml in the Jetspeed source
under:</p>
+<source><![CDATA[						
+cma/WEB-INF/web.xml
+]]></source>			
+		
+</section>
+<section name='Adding Users and Roles to the Tomcat Memory Realm'>
+<p>
+Lastly, for our demonstration, we add the default Jetspeed users and roles to the Tomcat
Memory Realm.
+An example tomcat-users.xml can be found in the Jetspeed source under:
+<source><![CDATA[						
+cma/tomcat-conf/tomcat-users.xml
+]]></source>				
+Here we add three jetspeed roles (admin, user, guest) and two jetspeed users (admin, turbine):
+</p>
+<source><![CDATA[						
+<?xml version='1.0' encoding='utf-8'?>
+<tomcat-users>
+
+  <!-- Tomcat Roles -->
+  <role rolename="tomcat"/>
+  <role rolename="manager"/>
+
+  <!-- Jetspeed Roles -->
+  <role rolename="admin"/>
+  <role rolename="user"/>
+  <role rolename="guest"/>
+
+  <!-- Tomcat Users -->  
+  <user username="tomcat" password="tomcat" roles="tomcat"/>
+
+  <!-- Jetspeed Users -->
+  <user username="admin" password="jetspeed" roles="admin,user,manager"/>
+  <user username="turbine" password="turbine" roles="user"/>
+
+</tomcat-users>
+]]></source>				
+</section>	
+</body>
+</document>

Modified: portals/jetspeed-1/trunk/xdocs/stylesheets/project.xml
URL: http://svn.apache.org/viewcvs/portals/jetspeed-1/trunk/xdocs/stylesheets/project.xml?rev=360567&r1=360566&r2=360567&view=diff
==============================================================================
--- portals/jetspeed-1/trunk/xdocs/stylesheets/project.xml (original)
+++ portals/jetspeed-1/trunk/xdocs/stylesheets/project.xml Sun Jan  1 13:58:10 2006
@@ -55,6 +55,7 @@
 			<item name="PSML" href="/psml.html"/>
 			<item name="Forwards" href="/forwards.html"/>
 			<item name="Database" href="/database.html"/>
+			<item name="Container Authentication" href="/cma.html"/>						
 			<item name="Jetspeed Cluster (JMS)" href="/messaging.html"/>
 		</menu>
 		<menu name="Translated">



---------------------------------------------------------------------
To unsubscribe, e-mail: jetspeed-dev-unsubscribe@portals.apache.org
For additional commands, e-mail: jetspeed-dev-help@portals.apache.org


Mime
View raw message