You are viewing a plain text version of this content. The canonical link for it is here.
Posted to jetspeed-dev@portals.apache.org by ta...@apache.org on 2006/01/01 22:58:11 UTC
svn commit: r360567 - in /portals/jetspeed-1/trunk/xdocs: cma.xml
stylesheets/project.xml
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