portals-jetspeed-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From a..@apache.org
Subject svn commit: r725977 [43/48] - in /portals/jetspeed-2/portal/trunk: ./ app-servers/security/jboss/src/java/META-INF/jboss-secsvc/ app-servers/security/jboss/src/java/org/apache/jetspeed/appservers/security/jboss/ applications/jetspeed/src/main/javascrip...
Date Fri, 12 Dec 2008 12:07:04 GMT
Modified: portals/jetspeed-2/portal/trunk/src/site/xdoc/components/jetspeed-security/credentials.xml
URL: http://svn.apache.org/viewvc/portals/jetspeed-2/portal/trunk/src/site/xdoc/components/jetspeed-security/credentials.xml?rev=725977&r1=725976&r2=725977&view=diff
==============================================================================
--- portals/jetspeed-2/portal/trunk/src/site/xdoc/components/jetspeed-security/credentials.xml (original)
+++ portals/jetspeed-2/portal/trunk/src/site/xdoc/components/jetspeed-security/credentials.xml Fri Dec 12 04:06:29 2008
@@ -1,339 +1,339 @@
-<?xml version="1.0"?>
-<!--
-  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.
--->
-<document>
-    <properties>
-        <title>Jetspeed 2 Security - Credentials Management</title>
-        <authors>
-            <person name="David Le Strat" email="dlestrat@apache.org" />
-            <person name="Ate Douma" email="ate@douma.nu" />
-        </authors>
-    </properties>
-    <body>
-        <section name="Credentials Management Overview">
-          <subsection name="DefaultCredentialHandler Features">
-            <p>
-                With the Jetspeed <a href="apidocs/org/apache/jetspeed/security/spi/impl/DefaultCredentialHandler.html">
-                <code>DefaultCredentialHandler</code></a> special management of password credentials can
-                easily be configured. Through the provided 
-                <a href="apidocs/org/apache/jetspeed/security/spi/PasswordCredentialProvider.html">
-                <code>PasswordCredentialProvider</code></a> and 
-                <a href="apidocs/org/apache/jetspeed/security/spi/InternalPasswordCredentialInterceptor.html">
-                <code>InternalPasswordCredentialInterceptor</code></a> components custom logic can be plugged in for:</p>
-            <ul>
-                <li>providing a custom 
-                    <a href="../jetspeed-api/apidocs/org/apache/jetspeed/security/PasswordCredential.html">
-                    <code>PasswordCredential</code></a> implementation</li>
-                <li>password encoding<br/>
-                    If an 
-                    <a href="apidocs/org/apache/jetspeed/security/spi/CredentialPasswordEncoder.html">
-                    <code>CredentialPasswordEncoder</code></a> is available from the 
-                    <code>PasswordCredentialProvider</code> passwords will be encoded with it before they are persisted.
-                    The provided 
-                    <a href="apidocs/org/apache/jetspeed/security/spi/impl/MessageDigestCredentialPasswordEncoder.html">
-                    <code>MessageDigestCredentialPasswordEncoder</code></a> uses 
-                    <a href="http://java.sun.com/j2se/1.4.2/docs/api/java/security/MessageDigest.html">
-                    <code>MessageDigest</code></a> hash algorithms for the password encryption, and can for example be
-                    configured to use <code>SHA-1</code> and <code>Base64</code>.
-                </li>
-                <li>enforcing password value rules<br/>
-                    If an
-                    <a href="apidocs/org/apache/jetspeed/security/spi/CredentialPasswordValidator.html">
-                    <code>CredentialPasswordValidator</code></a> is available from the
-                    <code>PasswordCredentialProvider</code>, passwords will be validated with it before they are persisted.
-                    The 
-                    <a href="apidocs/org/apache/jetspeed/security/spi/impl/DefaultCredentialPasswordValidator.html">
-                    <code>DefaultCredentialPasswordValidator</code></a> for example enforces non-emtpy password. And
-                    with the 
-                    <a href="apidocs/org/apache/jetspeed/security/spi/impl/SimpleCredentialPasswordValidator.html">
-                    <code>SimpleCredentialPasswordValidator</code></a> a minimum length and a minum number of numeric
-                    characters can be enforced.
-                </li>
-                <li>intercepting 
-                    <a href="../jetspeed-api/apidocs/org/apache/jetspeed/security/om/InternalCredential.html">
-                    <code>InternalCredential</code></a> lifecycle events<br/>
-                    If the <code>DefaultCredentialHandler</code> is provided with an
-                    <code>InternalPasswordCredentialInterceptor</code>, it will invoke this interceptor (or an arbirary
-                    set if
-                    <a href="apidocs/org/apache/jetspeed/security/spi/impl/InternalPasswordCredentialInterceptorsProxy.html">
-                    <code>InternalPasswordCredentialInterceptorsProxy</code></a> is used) on:
-                    <ul>
-                      <li>after loading a credential from the persistent store</li>
-                      <li>after authenticating a user</li>
-                      <li>before a new credential is saved to the persistent store</li>
-                      <li>before a new password is save for the credential</li>                      
-                    </ul>
-                    Jetspeed already provides a basic set of interceptors, ready to be used:
-                    <ul>
-                      <li>
-                          <a href="apidocs/org/apache/jetspeed/security/spi/impl/ValidatePasswordOnLoadInterceptor.html">
-                          <code>ValidatePasswordOnLoadInterceptor</code></a><br/>
-                          This interceptor can be used to validate (pre)set passwords in the persistent store and force
-                          a required change by the user if invalid. It uses the configured <code>CredentialPasswordValidator</code>
-                          of the <code>PasswordCredentialProvider</code>, the same as used when a password is changed.
-                      </li>
-                      <li>
-                          <a href="apidocs/org/apache/jetspeed/security/spi/impl/EncodePasswordOnFirstLoadInterceptor.html">
-                          <code>EncodePasswordOnFirstLoadInterceptor</code></a><br/>
-                          This interceptor can be used if passwords needs to be preset in the persistent store or
-                          migrated unencoded from a different store. With this interceptor, these cleartext password
-                          will automatically be encoded the first time they are loaded from the database, using the 
-                          <code>CredentialPasswordEncoder</code> from the <code>PasswordCredentialProvider</code>
-                      </li>
-                      <li>
-                          <a href="apidocs/org/apache/jetspeed/security/spi/impl/PasswordExpirationInterceptor.html">
-                          <code>PasswordExpirationInterceptor</code></a><br/>
-                          This interceptor can be used to enforce a maximum lifespan for passwords.
-                          It manages the <code>expiration_date</code> and <code>is_expired</code> members of the
-                          <code>InternalCredential</code> and sets the expired flag when on authentication of a user
-                          its (valid) password is expired. The authentication will then fail.<br/>
-                          Note: A Jetspeed pipeline Valve, the <code>PasswordCredentialValveImpl</code> can be
-                          used to request or even enforce users to change their password in time to prevent a password
-                          expiration (described further below). 
-                      </li>
-                      <li>
-                          <a href="apidocs/org/apache/jetspeed/security/spi/impl/MaxPasswordAuthenticationFailuresInterceptor.html">
-                          <code>MaxPasswordAuthenticationFailuresInterceptor</code></a><br/>
-                          This interceptor can be used to prevent password hacking by enforcing a maximum number of
-                          invalid password attempts in a row. Once this number of authentication failures is reached,
-                          the credential will be disabled. On a successful authentication though, this count
-                          will automatically be reset to zero again by the <code>DefaultCredentialHandler</code>.
-                      </li>                          
-                      <li>
-                          <a href="apidocs/org/apache/jetspeed/security/spi/impl/PasswordHistoryInterceptor.html">
-                          <code>PasswordHistoryInterceptor</code></a><br/>
-                          This interceptor can be used to enforce usage of unique new passwords in respect to a certain
-                          number of previous used passwords. When a new password is set, the current password is saved
-                          in a FIFO stack of used passwords. When a user itself changes its password, it must be different
-                          from all the onces thus saved, otherwise a 
-                          <a href="../jetspeed-api/apidocs/org/apache/jetspeed/security/PasswordAlreadyUsedException.html">
-                          <code>PasswordAlreadyUsedException</code></a> will be
-                          thrown. But setting a new password through the administrative interface still allows any
-                          password (when otherwise valid) to be set.
-                      </li>
-                    </ul>
-                    <p>
-                    The <code>DefaultCredentialHandler</code> only supports one interceptor to be configured.
-                    But, with the 
-                    <a href="apidocs/org/apache/jetspeed/security/spi/impl/InternalPasswordCredentialInterceptorsProxy.html">
-                    <code>InternalPasswordCredentialInterceptorsProxy</code></a>, a list of interceptors can
-                    be configured which then will be invoked sequentially.</p>
-                    <p>
-                    Jetspeed comes out of the box with several of these interceptors configured, and its very easy to
-                    change and extend.See the <a href="config.html#security-spi-atn_xml">security-spi-atn.xml</a>
-                    section in the <a href="config.html">Security Services Configuration</a> document for a description
-                    of the default configuration. Also provided there is an example how to setup the interceptors to 
-                    restore the "old" (and much more restrict) configuration provided with the 2.0-M3 release and
-                    earlier.</p>
-                </li>
-            </ul>
-          </subsection>
-          <subsection name="Credentials Management Implementation">
-            <p>
-                The class diagram below describes the components used for the
-                <code>DefaultCredentialHandler</code>
-                implementation.
-            </p>
-            <p align="center">
-                <img src="../../images/components/credential-handler-c.gif" border="0" />
-            </p>
-            <p>
-                The OJB mappings for the default credentials implementation are described in 
-                <code>security_repository.xml</code>:
-                <ul>
-                    <li><code>InternalCredential</code>: Maps to the SECURITY_CREDENTIAL table.</li>
-                </ul>
-                The following database schema is used to stored credentials and their associations to principals.
-            </p>
-            <p align="center">
-                <img src="../../images/components/principals-credentials-schema.gif" border="0" />
-            </p>
-          </subsection>
-        </section>
-        <section name="User interaction">
-            <p>
-            Although the <code>DefaultCredentialHandler</code> provides fine-grained management of credentials, it cannot
-            provide direct feedback to the user like presenting a warning that the current password is soon to be expired.
-            But, special request processing pipeline valves provided with jetspeed allow to do just that.</p>
-            <p>
-            The configuration for these valves can be found and set in the <code>pipelines.xml</code> spring
-            configuration file.</p>
-            <subsection name="LoginValidationValveImpl">
-              <p>
-              The <a href="../jetspeed-portal/apidocs/org/apache/jetspeed/security/impl/LoginValidationValveImpl.html">
-              <code>LoginValidationValveImpl</code></a> provides feedback to the user about the cause of an failed login
-              attempt.</p>
-              <p>
-              It retrieves the <code>UserPrincipal</code> and its current <code>PasswordCredential</code> for the 
-              specified user name, and (if found) determines an specific error code based on its state. 
-              This error code is communicated back to through the session so an appropriate error message can be
-              presented to the user.</p>
-              <p>
-              The following possible error codes can be returned (all defined in the
-              <a href="../jetspeed-api/apidocs/org/apache/jetspeed/login/LoginConstants.html">
-              <code>LoginConstants</code></a> interface):</p>
-              <ol>
-                <li>ERROR_UNKNOWN_USER</li>
-                <li>ERROR_INVALID_PASSWORD</li>
-                <li>ERROR_USER_DISABLED</li>
-                <li>ERROR_FINAL_LOGIN_ATTEMPT</li>
-                <li>ERROR_CREDENTIAL_DISABLED</li>
-                <li>ERROR_CREDENTIAL_EXPIRED</li>
-              </ol>
-              <p>
-              Of the above error codes, the <code>ERROR_FINAL_LOGIN_ATTEMPT</code> will only be reported if the valve
-              is configured with the same <code>maxNumberOfAuthenticationFailures</code> value as used for the
-              related <code>MaxPasswordAuthenticationFailuresInterceptor</code> described above:
-              <source><![CDATA[
-  <bean id="loginValidationValve"
-        class="org.apache.jetspeed.security.impl.LoginValidationValveImpl"
-        init-method="initialize">
-    <!-- maxNumberOfAuthenticationFailures
-         This value should be in sync with the value for
-         org.apache.jetspeed.security.spi.impl.MaxPasswordAuthenticationFailuresInterceptor
-         (if used) to make sense.
-         Any value < 2 will suppress the LoginConststants.ERROR_FINAL_LOGIN_ATTEMPT
-         error code when only one last attempt is possible before the credential
-         will be disabled after the next authentication failure.
-    -->
-    <constructor-arg index="0"><value>3</value></constructor-arg>  
-</bean>]]>
-                </source>
-              </p>
-            </subsection>
-            <subsection name="PasswordCredentialValveImpl">
-              <p>
-              The <a href="../jetspeed-portal/apidocs/org/apache/jetspeed/security/impl/PasswordCredentialValveImpl.html">
-              <code>PasswordCredentialValveImpl</code></a> is meant to be used together with a special Portlet on a
-              special Portal Page (PSML) to automatically request or even require a user to change its password.</p>
-              <p>
-              This valve evaluates <code>PasswordCredential.isUpdateRequired()</code> and optionally the 
-              <code>expirationDate</code>, <code>lastAuthenticationDate</code> and <code>previousAuthenticationDate</code>
-              fields to determine if a user is required or just be asked to change its password.</p>
-              <p>
-              This valve can optionally be configured with a list of  <code>expirationWarningDays</code> numbers in
-              its constructor:
-              <source><![CDATA[
-<bean id="passwordCredentialValve"
-      class="org.apache.jetspeed.security.impl.PasswordCredentialValveImpl"
-      init-method="initialize">
- <constructor-arg>
-   <!-- expirationWarningDays -->
-   <list>
-     <value>2</value>
-     <value>3</value>
-     <value>7</value>
-   </list>
- </constructor-arg>
-</bean>]]>
-                </source>
-              These numbers each represent a day before the current <code>expirationDate</code> of the password credential
-              when a user should be warned its password is soon to expire and be asked to change it. The
-              <code>lastAuthenticationDate</code> and the <code>previousAuthenticationDate</code> are used to determine
-              when this should happen. It will be done only once for each configured <code>expirationWarningDay</code>.
-              If a user logs on for the first time (after several days) with the above example configuration, 6 days
-              before the password expires, he or she will be warned about it. And again when 3 or 2 days are left.</p>
-              <p>
-              When a user logs on the last day before the password expires <em>or</em> when <code>updateRequired</code>
-              is <code>true</code>, the user will be required to change the password, regardless if expirationWarningDays
-              are configured or not.</p>
-              <p>
-              To be able to automatically provide the user with this information and allow or require the password to
-              be changed directly after login, a special <code>ProfileLocator</code> 
-              <a href="../jetspeed-api/apidocs/org/apache/jetspeed/profiler/ProfileLocator.html#SECURITY_LOCATOR">
-              <code>SECURITY_LOCATOR</code></a> is used. The <code>PageProfilerValve</code> (which should be configed
-              <em>after</em> this valve in the pipeline) will then use this enforced locator to be used to find the
-              related portal page to present to the user.</p>
-              <p>
-              For this to work, a <code>"security"</code> Profiler rule must have been setup like the default one 
-              provided by Jetspeed:</p>
-              <p align="center">
-                <img src="../../images/components/security-locator.jpg" border="0"/>
-              </p>
-              <p>
-              As can seen from the above image, the default page which will be presented to the user is the
-              <code>/my-account.psml</code> located in the root.</p>
-              <p>
-              This default page contains only one portlet, the <code>ChangePasswordPortlet</code> from the security
-              Portlet Application.</p>
-              <p>
-              The <code>ChangePasswordPortlet</code> works together with the <code>PasswordCredentialValveImpl</code>
-              as it checks for the 
-              <a href="../jetspeed-api/apidocs/org/apache/jetspeed/security/PasswordCredential.html#PASSWORD_CREDENTIAL_DAYS_VALID_REQUEST_ATTR_KEY">
-              <code>PASSWORD_CREDENTIAL_DAYS_VALID_REQUEST_ATTR_KEY</code></a> request parameter which will be set by
-              this valve with the number of days the password is still valid. For a required password change this will
-              be set to Integer(0).</p>
-              <p>
-              The default <code>my-account.psml</code> page contains <em>only</em> the <code>ChangePasswordPortlet</code>
-              to make sure a user which is <em>required</em> to change the password cannot interact with the portal any
-              other way then after the password is changed.</p>
-              <p>
-              Although the user might be attempted to select a link to a different page (from a portal menu for exampl),
-              this valve will make sure only the configured "security" locator page is returned if it is required.
-              But, once the password is changed the then targeted page in the url will be navigated to automatically.
-              </p>
-            </subsection>
-            <subsection name="Managing Password Expiration">
-              <p>
-              If the <code>PasswordExpirationInterceptor</code> is used, password expiration for a certain user can be
-              directly managed through the <code>UserDetailPortlet</code> provided with the <code>security</code>
-              portlet application.</p>
-              <p>
-              If enabled, this portlet can display the current expiration date of a password and also allows to change
-              its value:</p>
-              <p align="center">
-                <img src="../../images/components/password-expiration.jpg" border="0"/>
-              </p>              
-              <p>
-              As you can see, through the radio group, the password expiration date can be changed to:</p>
-              <table>
-                <tr><th>Action</th><th>Expires</th></tr>
-                <tr><td>Expired</td><td>today</td></tr>
-                <tr>
-                  <td>Extend</td>
-                  <td>today + <code>maxLifeSpanInDays</code> as configured for the PasswordExpirationInterceptor</td>
-                </tr>
-                <tr><td>Extend Unlimited</td><td>January 1, 8099 (the maximum value allowed for java.sql.Date)</td></tr>
-              </table>
-              <p>
-              This feature can be enabled through the edit/preferences page of the <code>UserDetailsPortlet</code>:</p>
-              <p align="center">
-                <img src="../../images/components/user-detail-prefs.jpg" border="0"/>
-              </p>
-              <p>
-              Note: when a new password value is specified selected password expiration action <code>Expired</code>
-              will be ignored!</p>
-            </subsection>
-            <subsection name="Setting default 'Change Password required on First Login'">
-              <p>
-              Through the same <code>UserDetailsPortlet</code> preferences as show above, the default
-              <code>updateRequired</code> property of a password credential for a new user can be configured too.</p>
-              <p>
-              And, if you always need the same setting for all users, you can even suppress the selection box normally 
-              displayed on the <code>Add User</code> dialog.</p>
-              <p>
-              With the preferences set as in the example shown above, the <code>Add User</code> dialog will look like this:</p>
-              <p align="center">
-                <img src="../../images/components/add-user.jpg" border="0"/>
-              </p>
-              <p>
-              A user added with the example preferences set, will have the <code>updateRequired</code> property set to
-              true, the <code>User</code> role assigned and use the <code>role-fallback</code> profiling rule.</p>
-            </subsection> 
-        </section>
-    </body>
-</document>
+<?xml version="1.0"?>
+<!--
+  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.
+-->
+<document>
+    <properties>
+        <title>Jetspeed 2 Security - Credentials Management</title>
+        <authors>
+            <person name="David Le Strat" email="dlestrat@apache.org" />
+            <person name="Ate Douma" email="ate@douma.nu" />
+        </authors>
+    </properties>
+    <body>
+        <section name="Credentials Management Overview">
+          <subsection name="DefaultCredentialHandler Features">
+            <p>
+                With the Jetspeed <a href="apidocs/org/apache/jetspeed/security/spi/impl/DefaultCredentialHandler.html">
+                <code>DefaultCredentialHandler</code></a> special management of password credentials can
+                easily be configured. Through the provided 
+                <a href="apidocs/org/apache/jetspeed/security/spi/PasswordCredentialProvider.html">
+                <code>PasswordCredentialProvider</code></a> and 
+                <a href="apidocs/org/apache/jetspeed/security/spi/InternalPasswordCredentialInterceptor.html">
+                <code>InternalPasswordCredentialInterceptor</code></a> components custom logic can be plugged in for:</p>
+            <ul>
+                <li>providing a custom 
+                    <a href="../jetspeed-api/apidocs/org/apache/jetspeed/security/PasswordCredential.html">
+                    <code>PasswordCredential</code></a> implementation</li>
+                <li>password encoding<br/>
+                    If an 
+                    <a href="apidocs/org/apache/jetspeed/security/spi/CredentialPasswordEncoder.html">
+                    <code>CredentialPasswordEncoder</code></a> is available from the 
+                    <code>PasswordCredentialProvider</code> passwords will be encoded with it before they are persisted.
+                    The provided 
+                    <a href="apidocs/org/apache/jetspeed/security/spi/impl/MessageDigestCredentialPasswordEncoder.html">
+                    <code>MessageDigestCredentialPasswordEncoder</code></a> uses 
+                    <a href="http://java.sun.com/j2se/1.4.2/docs/api/java/security/MessageDigest.html">
+                    <code>MessageDigest</code></a> hash algorithms for the password encryption, and can for example be
+                    configured to use <code>SHA-1</code> and <code>Base64</code>.
+                </li>
+                <li>enforcing password value rules<br/>
+                    If an
+                    <a href="apidocs/org/apache/jetspeed/security/spi/CredentialPasswordValidator.html">
+                    <code>CredentialPasswordValidator</code></a> is available from the
+                    <code>PasswordCredentialProvider</code>, passwords will be validated with it before they are persisted.
+                    The 
+                    <a href="apidocs/org/apache/jetspeed/security/spi/impl/DefaultCredentialPasswordValidator.html">
+                    <code>DefaultCredentialPasswordValidator</code></a> for example enforces non-emtpy password. And
+                    with the 
+                    <a href="apidocs/org/apache/jetspeed/security/spi/impl/SimpleCredentialPasswordValidator.html">
+                    <code>SimpleCredentialPasswordValidator</code></a> a minimum length and a minum number of numeric
+                    characters can be enforced.
+                </li>
+                <li>intercepting 
+                    <a href="../jetspeed-api/apidocs/org/apache/jetspeed/security/om/InternalCredential.html">
+                    <code>InternalCredential</code></a> lifecycle events<br/>
+                    If the <code>DefaultCredentialHandler</code> is provided with an
+                    <code>InternalPasswordCredentialInterceptor</code>, it will invoke this interceptor (or an arbirary
+                    set if
+                    <a href="apidocs/org/apache/jetspeed/security/spi/impl/InternalPasswordCredentialInterceptorsProxy.html">
+                    <code>InternalPasswordCredentialInterceptorsProxy</code></a> is used) on:
+                    <ul>
+                      <li>after loading a credential from the persistent store</li>
+                      <li>after authenticating a user</li>
+                      <li>before a new credential is saved to the persistent store</li>
+                      <li>before a new password is save for the credential</li>                      
+                    </ul>
+                    Jetspeed already provides a basic set of interceptors, ready to be used:
+                    <ul>
+                      <li>
+                          <a href="apidocs/org/apache/jetspeed/security/spi/impl/ValidatePasswordOnLoadInterceptor.html">
+                          <code>ValidatePasswordOnLoadInterceptor</code></a><br/>
+                          This interceptor can be used to validate (pre)set passwords in the persistent store and force
+                          a required change by the user if invalid. It uses the configured <code>CredentialPasswordValidator</code>
+                          of the <code>PasswordCredentialProvider</code>, the same as used when a password is changed.
+                      </li>
+                      <li>
+                          <a href="apidocs/org/apache/jetspeed/security/spi/impl/EncodePasswordOnFirstLoadInterceptor.html">
+                          <code>EncodePasswordOnFirstLoadInterceptor</code></a><br/>
+                          This interceptor can be used if passwords needs to be preset in the persistent store or
+                          migrated unencoded from a different store. With this interceptor, these cleartext password
+                          will automatically be encoded the first time they are loaded from the database, using the 
+                          <code>CredentialPasswordEncoder</code> from the <code>PasswordCredentialProvider</code>
+                      </li>
+                      <li>
+                          <a href="apidocs/org/apache/jetspeed/security/spi/impl/PasswordExpirationInterceptor.html">
+                          <code>PasswordExpirationInterceptor</code></a><br/>
+                          This interceptor can be used to enforce a maximum lifespan for passwords.
+                          It manages the <code>expiration_date</code> and <code>is_expired</code> members of the
+                          <code>InternalCredential</code> and sets the expired flag when on authentication of a user
+                          its (valid) password is expired. The authentication will then fail.<br/>
+                          Note: A Jetspeed pipeline Valve, the <code>PasswordCredentialValveImpl</code> can be
+                          used to request or even enforce users to change their password in time to prevent a password
+                          expiration (described further below). 
+                      </li>
+                      <li>
+                          <a href="apidocs/org/apache/jetspeed/security/spi/impl/MaxPasswordAuthenticationFailuresInterceptor.html">
+                          <code>MaxPasswordAuthenticationFailuresInterceptor</code></a><br/>
+                          This interceptor can be used to prevent password hacking by enforcing a maximum number of
+                          invalid password attempts in a row. Once this number of authentication failures is reached,
+                          the credential will be disabled. On a successful authentication though, this count
+                          will automatically be reset to zero again by the <code>DefaultCredentialHandler</code>.
+                      </li>                          
+                      <li>
+                          <a href="apidocs/org/apache/jetspeed/security/spi/impl/PasswordHistoryInterceptor.html">
+                          <code>PasswordHistoryInterceptor</code></a><br/>
+                          This interceptor can be used to enforce usage of unique new passwords in respect to a certain
+                          number of previous used passwords. When a new password is set, the current password is saved
+                          in a FIFO stack of used passwords. When a user itself changes its password, it must be different
+                          from all the onces thus saved, otherwise a 
+                          <a href="../jetspeed-api/apidocs/org/apache/jetspeed/security/PasswordAlreadyUsedException.html">
+                          <code>PasswordAlreadyUsedException</code></a> will be
+                          thrown. But setting a new password through the administrative interface still allows any
+                          password (when otherwise valid) to be set.
+                      </li>
+                    </ul>
+                    <p>
+                    The <code>DefaultCredentialHandler</code> only supports one interceptor to be configured.
+                    But, with the 
+                    <a href="apidocs/org/apache/jetspeed/security/spi/impl/InternalPasswordCredentialInterceptorsProxy.html">
+                    <code>InternalPasswordCredentialInterceptorsProxy</code></a>, a list of interceptors can
+                    be configured which then will be invoked sequentially.</p>
+                    <p>
+                    Jetspeed comes out of the box with several of these interceptors configured, and its very easy to
+                    change and extend.See the <a href="config.html#security-spi-atn_xml">security-spi-atn.xml</a>
+                    section in the <a href="config.html">Security Services Configuration</a> document for a description
+                    of the default configuration. Also provided there is an example how to setup the interceptors to 
+                    restore the "old" (and much more restrict) configuration provided with the 2.0-M3 release and
+                    earlier.</p>
+                </li>
+            </ul>
+          </subsection>
+          <subsection name="Credentials Management Implementation">
+            <p>
+                The class diagram below describes the components used for the
+                <code>DefaultCredentialHandler</code>
+                implementation.
+            </p>
+            <p align="center">
+                <img src="../../images/components/credential-handler-c.gif" border="0" />
+            </p>
+            <p>
+                The OJB mappings for the default credentials implementation are described in 
+                <code>security_repository.xml</code>:
+                <ul>
+                    <li><code>InternalCredential</code>: Maps to the SECURITY_CREDENTIAL table.</li>
+                </ul>
+                The following database schema is used to stored credentials and their associations to principals.
+            </p>
+            <p align="center">
+                <img src="../../images/components/principals-credentials-schema.gif" border="0" />
+            </p>
+          </subsection>
+        </section>
+        <section name="User interaction">
+            <p>
+            Although the <code>DefaultCredentialHandler</code> provides fine-grained management of credentials, it cannot
+            provide direct feedback to the user like presenting a warning that the current password is soon to be expired.
+            But, special request processing pipeline valves provided with jetspeed allow to do just that.</p>
+            <p>
+            The configuration for these valves can be found and set in the <code>pipelines.xml</code> spring
+            configuration file.</p>
+            <subsection name="LoginValidationValveImpl">
+              <p>
+              The <a href="../jetspeed-portal/apidocs/org/apache/jetspeed/security/impl/LoginValidationValveImpl.html">
+              <code>LoginValidationValveImpl</code></a> provides feedback to the user about the cause of an failed login
+              attempt.</p>
+              <p>
+              It retrieves the <code>UserPrincipal</code> and its current <code>PasswordCredential</code> for the 
+              specified user name, and (if found) determines an specific error code based on its state. 
+              This error code is communicated back to through the session so an appropriate error message can be
+              presented to the user.</p>
+              <p>
+              The following possible error codes can be returned (all defined in the
+              <a href="../jetspeed-api/apidocs/org/apache/jetspeed/login/LoginConstants.html">
+              <code>LoginConstants</code></a> interface):</p>
+              <ol>
+                <li>ERROR_UNKNOWN_USER</li>
+                <li>ERROR_INVALID_PASSWORD</li>
+                <li>ERROR_USER_DISABLED</li>
+                <li>ERROR_FINAL_LOGIN_ATTEMPT</li>
+                <li>ERROR_CREDENTIAL_DISABLED</li>
+                <li>ERROR_CREDENTIAL_EXPIRED</li>
+              </ol>
+              <p>
+              Of the above error codes, the <code>ERROR_FINAL_LOGIN_ATTEMPT</code> will only be reported if the valve
+              is configured with the same <code>maxNumberOfAuthenticationFailures</code> value as used for the
+              related <code>MaxPasswordAuthenticationFailuresInterceptor</code> described above:
+              <source><![CDATA[
+  <bean id="loginValidationValve"
+        class="org.apache.jetspeed.security.impl.LoginValidationValveImpl"
+        init-method="initialize">
+    <!-- maxNumberOfAuthenticationFailures
+         This value should be in sync with the value for
+         org.apache.jetspeed.security.spi.impl.MaxPasswordAuthenticationFailuresInterceptor
+         (if used) to make sense.
+         Any value < 2 will suppress the LoginConststants.ERROR_FINAL_LOGIN_ATTEMPT
+         error code when only one last attempt is possible before the credential
+         will be disabled after the next authentication failure.
+    -->
+    <constructor-arg index="0"><value>3</value></constructor-arg>  
+</bean>]]>
+                </source>
+              </p>
+            </subsection>
+            <subsection name="PasswordCredentialValveImpl">
+              <p>
+              The <a href="../jetspeed-portal/apidocs/org/apache/jetspeed/security/impl/PasswordCredentialValveImpl.html">
+              <code>PasswordCredentialValveImpl</code></a> is meant to be used together with a special Portlet on a
+              special Portal Page (PSML) to automatically request or even require a user to change its password.</p>
+              <p>
+              This valve evaluates <code>PasswordCredential.isUpdateRequired()</code> and optionally the 
+              <code>expirationDate</code>, <code>lastAuthenticationDate</code> and <code>previousAuthenticationDate</code>
+              fields to determine if a user is required or just be asked to change its password.</p>
+              <p>
+              This valve can optionally be configured with a list of  <code>expirationWarningDays</code> numbers in
+              its constructor:
+              <source><![CDATA[
+<bean id="passwordCredentialValve"
+      class="org.apache.jetspeed.security.impl.PasswordCredentialValveImpl"
+      init-method="initialize">
+ <constructor-arg>
+   <!-- expirationWarningDays -->
+   <list>
+     <value>2</value>
+     <value>3</value>
+     <value>7</value>
+   </list>
+ </constructor-arg>
+</bean>]]>
+                </source>
+              These numbers each represent a day before the current <code>expirationDate</code> of the password credential
+              when a user should be warned its password is soon to expire and be asked to change it. The
+              <code>lastAuthenticationDate</code> and the <code>previousAuthenticationDate</code> are used to determine
+              when this should happen. It will be done only once for each configured <code>expirationWarningDay</code>.
+              If a user logs on for the first time (after several days) with the above example configuration, 6 days
+              before the password expires, he or she will be warned about it. And again when 3 or 2 days are left.</p>
+              <p>
+              When a user logs on the last day before the password expires <em>or</em> when <code>updateRequired</code>
+              is <code>true</code>, the user will be required to change the password, regardless if expirationWarningDays
+              are configured or not.</p>
+              <p>
+              To be able to automatically provide the user with this information and allow or require the password to
+              be changed directly after login, a special <code>ProfileLocator</code> 
+              <a href="../jetspeed-api/apidocs/org/apache/jetspeed/profiler/ProfileLocator.html#SECURITY_LOCATOR">
+              <code>SECURITY_LOCATOR</code></a> is used. The <code>PageProfilerValve</code> (which should be configed
+              <em>after</em> this valve in the pipeline) will then use this enforced locator to be used to find the
+              related portal page to present to the user.</p>
+              <p>
+              For this to work, a <code>"security"</code> Profiler rule must have been setup like the default one 
+              provided by Jetspeed:</p>
+              <p align="center">
+                <img src="../../images/components/security-locator.jpg" border="0"/>
+              </p>
+              <p>
+              As can seen from the above image, the default page which will be presented to the user is the
+              <code>/my-account.psml</code> located in the root.</p>
+              <p>
+              This default page contains only one portlet, the <code>ChangePasswordPortlet</code> from the security
+              Portlet Application.</p>
+              <p>
+              The <code>ChangePasswordPortlet</code> works together with the <code>PasswordCredentialValveImpl</code>
+              as it checks for the 
+              <a href="../jetspeed-api/apidocs/org/apache/jetspeed/security/PasswordCredential.html#PASSWORD_CREDENTIAL_DAYS_VALID_REQUEST_ATTR_KEY">
+              <code>PASSWORD_CREDENTIAL_DAYS_VALID_REQUEST_ATTR_KEY</code></a> request parameter which will be set by
+              this valve with the number of days the password is still valid. For a required password change this will
+              be set to Integer(0).</p>
+              <p>
+              The default <code>my-account.psml</code> page contains <em>only</em> the <code>ChangePasswordPortlet</code>
+              to make sure a user which is <em>required</em> to change the password cannot interact with the portal any
+              other way then after the password is changed.</p>
+              <p>
+              Although the user might be attempted to select a link to a different page (from a portal menu for exampl),
+              this valve will make sure only the configured "security" locator page is returned if it is required.
+              But, once the password is changed the then targeted page in the url will be navigated to automatically.
+              </p>
+            </subsection>
+            <subsection name="Managing Password Expiration">
+              <p>
+              If the <code>PasswordExpirationInterceptor</code> is used, password expiration for a certain user can be
+              directly managed through the <code>UserDetailPortlet</code> provided with the <code>security</code>
+              portlet application.</p>
+              <p>
+              If enabled, this portlet can display the current expiration date of a password and also allows to change
+              its value:</p>
+              <p align="center">
+                <img src="../../images/components/password-expiration.jpg" border="0"/>
+              </p>              
+              <p>
+              As you can see, through the radio group, the password expiration date can be changed to:</p>
+              <table>
+                <tr><th>Action</th><th>Expires</th></tr>
+                <tr><td>Expired</td><td>today</td></tr>
+                <tr>
+                  <td>Extend</td>
+                  <td>today + <code>maxLifeSpanInDays</code> as configured for the PasswordExpirationInterceptor</td>
+                </tr>
+                <tr><td>Extend Unlimited</td><td>January 1, 8099 (the maximum value allowed for java.sql.Date)</td></tr>
+              </table>
+              <p>
+              This feature can be enabled through the edit/preferences page of the <code>UserDetailsPortlet</code>:</p>
+              <p align="center">
+                <img src="../../images/components/user-detail-prefs.jpg" border="0"/>
+              </p>
+              <p>
+              Note: when a new password value is specified selected password expiration action <code>Expired</code>
+              will be ignored!</p>
+            </subsection>
+            <subsection name="Setting default 'Change Password required on First Login'">
+              <p>
+              Through the same <code>UserDetailsPortlet</code> preferences as show above, the default
+              <code>updateRequired</code> property of a password credential for a new user can be configured too.</p>
+              <p>
+              And, if you always need the same setting for all users, you can even suppress the selection box normally 
+              displayed on the <code>Add User</code> dialog.</p>
+              <p>
+              With the preferences set as in the example shown above, the <code>Add User</code> dialog will look like this:</p>
+              <p align="center">
+                <img src="../../images/components/add-user.jpg" border="0"/>
+              </p>
+              <p>
+              A user added with the example preferences set, will have the <code>updateRequired</code> property set to
+              true, the <code>User</code> role assigned and use the <code>role-fallback</code> profiling rule.</p>
+            </subsection> 
+        </section>
+    </body>
+</document>

Propchange: portals/jetspeed-2/portal/trunk/src/site/xdoc/components/jetspeed-security/credentials.xml
------------------------------------------------------------------------------
    svn:eol-style = native

Modified: portals/jetspeed-2/portal/trunk/src/site/xdoc/components/jetspeed-security/hierarchy.xml
URL: http://svn.apache.org/viewvc/portals/jetspeed-2/portal/trunk/src/site/xdoc/components/jetspeed-security/hierarchy.xml?rev=725977&r1=725976&r2=725977&view=diff
==============================================================================
--- portals/jetspeed-2/portal/trunk/src/site/xdoc/components/jetspeed-security/hierarchy.xml (original)
+++ portals/jetspeed-2/portal/trunk/src/site/xdoc/components/jetspeed-security/hierarchy.xml Fri Dec 12 04:06:29 2008
@@ -1,172 +1,172 @@
-<?xml version="1.0"?>
-<!--
-    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.
--->
-<document>
-    <properties>
-        <title>Jetspeed 2 Security - Hierarchy Management</title>
-        <authors>
-            <person name="David Le Strat" email="dlestrat@apache.org" />
-        </authors>
-    </properties>
-    <body>
-        <section name="Hierarchy Management Overview">
-            <p>
-                Two hierarchy resolution strategies are supported for authorization decisions:
-                <ul>
-                    <li>
-                        Hierarchy resolution by Generalization: This is the default hierarchy resolution in Jetspeed. If a hierarchy uses a generalization
-                        strategy, each role is more general than the previous one. For instance, if a user has the role [roleA.roleB.roleC] then
-                        <code>user.getSubject().getPrincipals()</code>
-                        returns:
-                        <ul>
-                            <li>/role/roleA</li>
-                            <li>/role/roleA/roleB</li>
-                            <li>/role/roleA/roleB/roleC</li>
-                        </ul>
-                    </li>
-                    <li>
-                        Hierarchy resolution by Aggregation: If a hierarchy uses a aggregation strategy, the higher role is responsible for a superset of the
-                        activities of the lower role. For instance, if the following roles are available:
-                        <ul>
-                            <li>roleA</li>
-                            <li>roleA.roleB</li>
-                            <li>roleA.roleB.roleC</li>
-                        </ul>
-                        If a user has the role [roleA] then,
-                        <code>user.getSubject().getPrincipals()</code>
-                        returns:
-                        <ul>
-                            <li>/role/roleA</li>
-                            <li>/role/roleA/roleB</li>
-                            <li>/role/roleA/roleB/roleC</li>
-                        </ul>
-                    </li>
-                </ul>
-            </p>
-            <p>
-                As described in the
-                <a href="atz-spi.html">authorization SPI section</a>
-                , the
-                <code>SecurityMappingHandler</code>
-                is configured with a specific hierarchy strategy for group and role hierarchy management. See the
-                <a href="config.html#security-spi-atz_xml">authorization SPI configuration</a>
-                for a configuration example.
-            </p>
-        </section>
-        <section name="Leveraging Preferences to Manage Hierarchies">
-            <p>
-                The default hierarchy management implementation resolves the hierarchy strategy by leveraging Jetspeed 2's
-                <a href="http://java.sun.com/j2se/1.4.2/docs/api/java/util/prefs/Preferences.html">java.util.prefs.Preferences</a>
-                implementation. The
-                <code>Preferences</code>
-                implementation provides the underlying structure in Jetspeed to store user attributes, and roles and groups definitions. The
-                <code>Preferences</code>
-                model provides a hierarchy model that is leveraged to store the base roles and groups hierarchy upon which various resolving strategies can be
-                applied (resolution by generalization or aggregation).
-            </p>
-            <p>
-                See Jetspeed 2
-                <a href="../../multiproject/jetspeed-prefs/index.html">Preferences implementation section</a>
-                for more information.
-            </p>
-            <subsection name="How does this work?">
-                <p>
-                    The
-                    <code>SecurityMappingHandler</code>
-                    implementation resolves the mappings between roles and groups. Let's say that we want to find out the roles mapping to a specific group
-                    name. To do so, the
-                    <code>SecurityMappingHandler</code>
-                    implements a
-                    <code>getRolePrincipalsInGroup(String groupFullPathName)</code>
-                    method. In this method, the group name is mapped to a specific
-                    <code>Preferences</code>
-                    node. According to a given hierarchy resolution strategy (see
-                    <a href="#Hierarchy_Management_Overview">overview section</a>
-                    ), being in [group A] may mean belonging to a set of groups; the HierarchyResolver is used to do so as illustrated below:
-                    <source>
-                        <![CDATA[
-public Set getRolePrincipalsInGroup(String groupFullPathName)
-{
-   ...
-   Preferences preferences = Preferences.userRoot().node(
-       GroupPrincipalImpl.getFullPathFromPrincipalName(groupFullPathName));
-   String[] fullPaths = groupHierarchyResolver.resolve(preferences);
-   ...
-}]]>
-                    </source>
-                    The resulting groups are then used to find all associated roles.
-                </p>
-                <p>
-                    As a result of this implementation, the name of a role principal (<code>Principal</code> 
-                    <a href="http://java.sun.com/j2se/1.4.2/docs/api/java/security/Principal.html#getName()">getName()</a>) 
-                    in the security layer should match the full path of that user preferences
-                    root in the preferences layer (<code>Preference</code> 
-                    <a href="http://java.sun.com/j2se/1.4.2/docs/api/java/util/prefs/Preferences.html#absolutePath()">absolutePath()</a>; e.g:
-                    <code>/role/theRolePrincipal</code>
-                    ).
-                </p>
-                <p>
-                    Group and roles hierarchy are stored in the
-                    <code>Preferences</code>
-                    layer as follow (the output of <a href="http://java.sun.com/j2se/1.4.2/docs/api/java/util/prefs/Preferences.html#exportNode(java.io.OutputStream)">
-                    exportNode()</a> for <a href="../../multiproject/jetspeed-prefs/index.html">Jetspeed's RBMS Preferences</a> implementation):
-                    <source>
-                        <![CDATA[
-<preferences EXTERNAL_XML_VERSION="1.0">
-<root type="user">
-<map />
-    <node name="group1">
-    <map />
-        <node name="groupid1.1">
-        <map />
-	    <node name="groupid1.1.1">
-            <map />
-            </node>
-        </node>
-    </node>
-
-    <node name="role1">
-    <map />
-        <node name="roleid1.1">
-        <map />
-	    <node name="roleid1.1.1">
-            <map />
-            </node>
-        </node>
-    </node>
-</root>]]>
-                    </source>
-                    This structure would define the following group and role hierarchy:
-                    <ul>
-                        <li>
-                            <code>/group1/groupid1.1/groupid1.1.1</code>
-                        </li>
-                        <li>
-                            <code>/role1/roleid1.1/roleid1.1.1</code>
-                        </li>
-                    </ul>
-                    Additionally, in this model, the
-                    <code>map</code>
-                    element can define groups or roles custom properties. For instance, a role could have a rule custom property (or a pointer to a rule) that
-                    allow rule based role definition tied to some rule engine (Drools for instance) and is validated when the isInRole method is invoked. For
-                    groups, a portal could use group to describe organization and have custom property such as address, city, etc. associated with the
-                    organization/group.
-                </p>
-            </subsection>
-        </section>
-    </body>
-</document>
+<?xml version="1.0"?>
+<!--
+    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.
+-->
+<document>
+    <properties>
+        <title>Jetspeed 2 Security - Hierarchy Management</title>
+        <authors>
+            <person name="David Le Strat" email="dlestrat@apache.org" />
+        </authors>
+    </properties>
+    <body>
+        <section name="Hierarchy Management Overview">
+            <p>
+                Two hierarchy resolution strategies are supported for authorization decisions:
+                <ul>
+                    <li>
+                        Hierarchy resolution by Generalization: This is the default hierarchy resolution in Jetspeed. If a hierarchy uses a generalization
+                        strategy, each role is more general than the previous one. For instance, if a user has the role [roleA.roleB.roleC] then
+                        <code>user.getSubject().getPrincipals()</code>
+                        returns:
+                        <ul>
+                            <li>/role/roleA</li>
+                            <li>/role/roleA/roleB</li>
+                            <li>/role/roleA/roleB/roleC</li>
+                        </ul>
+                    </li>
+                    <li>
+                        Hierarchy resolution by Aggregation: If a hierarchy uses a aggregation strategy, the higher role is responsible for a superset of the
+                        activities of the lower role. For instance, if the following roles are available:
+                        <ul>
+                            <li>roleA</li>
+                            <li>roleA.roleB</li>
+                            <li>roleA.roleB.roleC</li>
+                        </ul>
+                        If a user has the role [roleA] then,
+                        <code>user.getSubject().getPrincipals()</code>
+                        returns:
+                        <ul>
+                            <li>/role/roleA</li>
+                            <li>/role/roleA/roleB</li>
+                            <li>/role/roleA/roleB/roleC</li>
+                        </ul>
+                    </li>
+                </ul>
+            </p>
+            <p>
+                As described in the
+                <a href="atz-spi.html">authorization SPI section</a>
+                , the
+                <code>SecurityMappingHandler</code>
+                is configured with a specific hierarchy strategy for group and role hierarchy management. See the
+                <a href="config.html#security-spi-atz_xml">authorization SPI configuration</a>
+                for a configuration example.
+            </p>
+        </section>
+        <section name="Leveraging Preferences to Manage Hierarchies">
+            <p>
+                The default hierarchy management implementation resolves the hierarchy strategy by leveraging Jetspeed 2's
+                <a href="http://java.sun.com/j2se/1.4.2/docs/api/java/util/prefs/Preferences.html">java.util.prefs.Preferences</a>
+                implementation. The
+                <code>Preferences</code>
+                implementation provides the underlying structure in Jetspeed to store user attributes, and roles and groups definitions. The
+                <code>Preferences</code>
+                model provides a hierarchy model that is leveraged to store the base roles and groups hierarchy upon which various resolving strategies can be
+                applied (resolution by generalization or aggregation).
+            </p>
+            <p>
+                See Jetspeed 2
+                <a href="../../multiproject/jetspeed-prefs/index.html">Preferences implementation section</a>
+                for more information.
+            </p>
+            <subsection name="How does this work?">
+                <p>
+                    The
+                    <code>SecurityMappingHandler</code>
+                    implementation resolves the mappings between roles and groups. Let's say that we want to find out the roles mapping to a specific group
+                    name. To do so, the
+                    <code>SecurityMappingHandler</code>
+                    implements a
+                    <code>getRolePrincipalsInGroup(String groupFullPathName)</code>
+                    method. In this method, the group name is mapped to a specific
+                    <code>Preferences</code>
+                    node. According to a given hierarchy resolution strategy (see
+                    <a href="#Hierarchy_Management_Overview">overview section</a>
+                    ), being in [group A] may mean belonging to a set of groups; the HierarchyResolver is used to do so as illustrated below:
+                    <source>
+                        <![CDATA[
+public Set getRolePrincipalsInGroup(String groupFullPathName)
+{
+   ...
+   Preferences preferences = Preferences.userRoot().node(
+       GroupPrincipalImpl.getFullPathFromPrincipalName(groupFullPathName));
+   String[] fullPaths = groupHierarchyResolver.resolve(preferences);
+   ...
+}]]>
+                    </source>
+                    The resulting groups are then used to find all associated roles.
+                </p>
+                <p>
+                    As a result of this implementation, the name of a role principal (<code>Principal</code> 
+                    <a href="http://java.sun.com/j2se/1.4.2/docs/api/java/security/Principal.html#getName()">getName()</a>) 
+                    in the security layer should match the full path of that user preferences
+                    root in the preferences layer (<code>Preference</code> 
+                    <a href="http://java.sun.com/j2se/1.4.2/docs/api/java/util/prefs/Preferences.html#absolutePath()">absolutePath()</a>; e.g:
+                    <code>/role/theRolePrincipal</code>
+                    ).
+                </p>
+                <p>
+                    Group and roles hierarchy are stored in the
+                    <code>Preferences</code>
+                    layer as follow (the output of <a href="http://java.sun.com/j2se/1.4.2/docs/api/java/util/prefs/Preferences.html#exportNode(java.io.OutputStream)">
+                    exportNode()</a> for <a href="../../multiproject/jetspeed-prefs/index.html">Jetspeed's RBMS Preferences</a> implementation):
+                    <source>
+                        <![CDATA[
+<preferences EXTERNAL_XML_VERSION="1.0">
+<root type="user">
+<map />
+    <node name="group1">
+    <map />
+        <node name="groupid1.1">
+        <map />
+	    <node name="groupid1.1.1">
+            <map />
+            </node>
+        </node>
+    </node>
+
+    <node name="role1">
+    <map />
+        <node name="roleid1.1">
+        <map />
+	    <node name="roleid1.1.1">
+            <map />
+            </node>
+        </node>
+    </node>
+</root>]]>
+                    </source>
+                    This structure would define the following group and role hierarchy:
+                    <ul>
+                        <li>
+                            <code>/group1/groupid1.1/groupid1.1.1</code>
+                        </li>
+                        <li>
+                            <code>/role1/roleid1.1/roleid1.1.1</code>
+                        </li>
+                    </ul>
+                    Additionally, in this model, the
+                    <code>map</code>
+                    element can define groups or roles custom properties. For instance, a role could have a rule custom property (or a pointer to a rule) that
+                    allow rule based role definition tied to some rule engine (Drools for instance) and is validated when the isInRole method is invoked. For
+                    groups, a portal could use group to describe organization and have custom property such as address, city, etc. associated with the
+                    organization/group.
+                </p>
+            </subsection>
+        </section>
+    </body>
+</document>

Propchange: portals/jetspeed-2/portal/trunk/src/site/xdoc/components/jetspeed-security/hierarchy.xml
------------------------------------------------------------------------------
    svn:eol-style = native

Modified: portals/jetspeed-2/portal/trunk/src/site/xdoc/components/jetspeed-security/high-level-services.xml
URL: http://svn.apache.org/viewvc/portals/jetspeed-2/portal/trunk/src/site/xdoc/components/jetspeed-security/high-level-services.xml?rev=725977&r1=725976&r2=725977&view=diff
==============================================================================
--- portals/jetspeed-2/portal/trunk/src/site/xdoc/components/jetspeed-security/high-level-services.xml (original)
+++ portals/jetspeed-2/portal/trunk/src/site/xdoc/components/jetspeed-security/high-level-services.xml Fri Dec 12 04:06:29 2008
@@ -1,98 +1,98 @@
-<?xml version="1.0" ?>
-<!--
-    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.
--->
-<document>
-    <properties>
-        <title>Jetspeed 2 Security - High Level Security Services</title>
-    </properties>
-    <body>
-        <section name="High Level Security Services Overview">
-            <p>
-                Jetspeed 2 provides the four following high level security services:
-                <ul>
-                    <li>
-                        <code>UserManager</code>
-                        : Service providing user management capabilities.
-                    </li>
-                    <li>
-                        <code>GroupManager</code>
-                        : Service providing group management capabilities.
-                    </li>
-                    <li>
-                        <code>RoleManager</code>
-                        : Service providing role management capabilities.
-                    </li>
-                    <li>
-                        <code>PermissionManager</code>
-                        : Service providing permission management capabilities.
-                    </li>
-                </ul>
-            </p>
-        </section>
-        <section name="Using High Level Security Services in Portlets">
-            <p>
-                In order to access Jetspeed high level security services in your portlets, Jetspeed provide a custom
-                extension to the <code>portlet.xml</code> metadata.  All Jetspeed custom metadata is located in the 
-                <code>jetspeed-portlet.xml</code> configuration file in the <code>WEB-INF</code> folder of the portlet
-                application.  The custom <code>js:services</code> tag provides the ability to expose portal services
-                to a portlet through the <code>javax.portlet.PortletContext</code>.
-            </p>
-            <p>
-                Jetspeed portal services are configured in the spring assembly file located in the portal 
-                <code>WEB-INF/assembly/jetspeed-services</code> configuration file.  The UserManager for instance
-                is configured as follow:
-                <source><![CDATA[
-<!-- Portlet Services  -->
-<bean id="PortalServices" 
-  	 class="org.apache.jetspeed.services.JetspeedPortletServices" >
-   <constructor-arg>
-      <map>
-  	     ...
-  	     <entry key="UserManager">
-  	   	    <ref bean="org.apache.jetspeed.security.UserManager"/>
-  	   	 </entry>
-  	   	 ...
-      </map>
-   </constructor-arg>
-</bean>]]>
-                </source>
-            </p>
-            <p>
-                The <code>UserManager</code> services is then available to be loaded in a specific portlet
-                <code>PortletContext</code>.  Portlet developers need to specify the portal services they
-                would like to use.  The following example shows how to expose the portal <code>UserManager</code> 
-                to a portlet application:
-                <source><![CDATA[
-<js:services>
-   <js:service name='UserManager'/>
-</js:services>]]>
-                </source>   
-            </p>
-            <p>
-                Once a portal service is loaded in the portlet context, the portlet implementation (which typically
-                extends <code>javax.portlet.GenericPortlet</code>) can access the service as follow:
-                <source><![CDATA[
-PortletContext context = getPortletContext();
-userManager = (UserManager) context.getAttribute(CommonPortletServices.CPS_USER_MANAGER_COMPONENT);
-]]>
-                </source>
-                where <code>CommonPortletServices.CPS_USER_MANAGER_COMPONENT = "cps:UserManager"</code>
-            </p>
-        </section>
-    </body>
-</document>
-
+<?xml version="1.0" ?>
+<!--
+    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.
+-->
+<document>
+    <properties>
+        <title>Jetspeed 2 Security - High Level Security Services</title>
+    </properties>
+    <body>
+        <section name="High Level Security Services Overview">
+            <p>
+                Jetspeed 2 provides the four following high level security services:
+                <ul>
+                    <li>
+                        <code>UserManager</code>
+                        : Service providing user management capabilities.
+                    </li>
+                    <li>
+                        <code>GroupManager</code>
+                        : Service providing group management capabilities.
+                    </li>
+                    <li>
+                        <code>RoleManager</code>
+                        : Service providing role management capabilities.
+                    </li>
+                    <li>
+                        <code>PermissionManager</code>
+                        : Service providing permission management capabilities.
+                    </li>
+                </ul>
+            </p>
+        </section>
+        <section name="Using High Level Security Services in Portlets">
+            <p>
+                In order to access Jetspeed high level security services in your portlets, Jetspeed provide a custom
+                extension to the <code>portlet.xml</code> metadata.  All Jetspeed custom metadata is located in the 
+                <code>jetspeed-portlet.xml</code> configuration file in the <code>WEB-INF</code> folder of the portlet
+                application.  The custom <code>js:services</code> tag provides the ability to expose portal services
+                to a portlet through the <code>javax.portlet.PortletContext</code>.
+            </p>
+            <p>
+                Jetspeed portal services are configured in the spring assembly file located in the portal 
+                <code>WEB-INF/assembly/jetspeed-services</code> configuration file.  The UserManager for instance
+                is configured as follow:
+                <source><![CDATA[
+<!-- Portlet Services  -->
+<bean id="PortalServices" 
+  	 class="org.apache.jetspeed.services.JetspeedPortletServices" >
+   <constructor-arg>
+      <map>
+  	     ...
+  	     <entry key="UserManager">
+  	   	    <ref bean="org.apache.jetspeed.security.UserManager"/>
+  	   	 </entry>
+  	   	 ...
+      </map>
+   </constructor-arg>
+</bean>]]>
+                </source>
+            </p>
+            <p>
+                The <code>UserManager</code> services is then available to be loaded in a specific portlet
+                <code>PortletContext</code>.  Portlet developers need to specify the portal services they
+                would like to use.  The following example shows how to expose the portal <code>UserManager</code> 
+                to a portlet application:
+                <source><![CDATA[
+<js:services>
+   <js:service name='UserManager'/>
+</js:services>]]>
+                </source>   
+            </p>
+            <p>
+                Once a portal service is loaded in the portlet context, the portlet implementation (which typically
+                extends <code>javax.portlet.GenericPortlet</code>) can access the service as follow:
+                <source><![CDATA[
+PortletContext context = getPortletContext();
+userManager = (UserManager) context.getAttribute(CommonPortletServices.CPS_USER_MANAGER_COMPONENT);
+]]>
+                </source>
+                where <code>CommonPortletServices.CPS_USER_MANAGER_COMPONENT = "cps:UserManager"</code>
+            </p>
+        </section>
+    </body>
+</document>
+

Propchange: portals/jetspeed-2/portal/trunk/src/site/xdoc/components/jetspeed-security/high-level-services.xml
------------------------------------------------------------------------------
    svn:eol-style = native

Modified: portals/jetspeed-2/portal/trunk/src/site/xdoc/components/jetspeed-security/index.xml
URL: http://svn.apache.org/viewvc/portals/jetspeed-2/portal/trunk/src/site/xdoc/components/jetspeed-security/index.xml?rev=725977&r1=725976&r2=725977&view=diff
==============================================================================
--- portals/jetspeed-2/portal/trunk/src/site/xdoc/components/jetspeed-security/index.xml (original)
+++ portals/jetspeed-2/portal/trunk/src/site/xdoc/components/jetspeed-security/index.xml Fri Dec 12 04:06:29 2008
@@ -1,90 +1,90 @@
-<?xml version="1.0"?>
-<!--
-    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.
--->
-<document>
-    <properties>
-        <title>Jetspeed 2 Security Architecture</title>
-        <authors>
-            <person name="David Le Strat" email="dlestrat@apache.org" />
-        </authors>
-    </properties>
-    <body>
-        <section name="Overview">
-            <p>
-                Jetspeed 2 security architecture provides a comprehensive suite of security services that can be used to protect a wide ranging type of portal
-                resources. The security service implementation is fairly independent of the other portal services and 
-                can be reused outside of the portal application.  At its core, Jetspeed 2 security services rely entirely 
-                on JAAS to provide authentication and authorization services to the portal:
-            </p>
-            <ul>
-                <li>Authentication services are implemented through the use of JAAS login modules.</li>
-                <li>Authorization services are implemented through the use of custom JAAS policies.</li>
-            </ul>
-            <p>
-                Both authentication and authorization services have been implemented with the goal of providing a direct plugin to the underlying application
-                server security framework. Jetspeed 2 can leverage the underlying application server login module as well as through the use of JACC, the
-                application server policy management capabilities available in J2EE 1.4 (see
-                <a href="http://java.sun.com/j2ee/javaacc/">API Specifications</a>
-                ).
-            </p>
-        </section>
-        <section name="Jetspeed 2 Security Services">
-            <p>
-                JAAS defines the contract for authentication and authorization but does not specify any guidelines for the management of the security resources.
-                Jetspeed 2 provide a modular set of components aims at providing management functionality for the portal security components.
-            </p>
-            <p>
-                Leveraging Jetspeed 2 component, architecture, the security services provide a set of loosely coupled components providing specialized services:
-            </p>
-            <ul>
-                <li>UserManager: Service providing user management capabilities.</li>
-                <li>GroupManager: Service providing group management capabilities.</li>
-                <li>RoleManager: Service providing role management capabilities.</li>
-                <li>PermissionManager: Service providing permission management capabilities.</li>
-            </ul>
-        </section>
-        <section name="A Modular and Pluggable Architecture">
-            <p>
-                Jetspeed 2 security components are assembled using
-                <a href="http://martinfowler.com/articles/injection.html">Dependency Injection</a>
-                . By default, Jetspeed uses the
-                <a href="http://www.springframework.org">Spring Framework</a>
-                as its default IoC container.
-            </p>
-            <p>
-                <img src="../../images/components/components.jpg" align="right" border="0" hspace="1" vspace="2" />
-                Jetspeed 2 security services are founded on a set of modular and extensible security modules exposed through an SPI model. The SPI model
-                provides the ability to modify the behavior of the Jetspeed coarsed security services (UserManager, RoleManager, GroupManager)
-                through the modification and configuration of specialized handlers. For
-                instance, Jetspeed security services can be configured to retrieve user security principals through the default Jetspeed store or through an
-                LDAP store or both.
-                <br />
-                A
-                <code>SecurityProvider</code>
-                exposes the configured SPI handlers to the security services. Jetspeed component assembly (based on Spring) architecture provides an easy way to
-                reconfigure the security services to satisfy the needs of a specific implementation.
-            </p>
-        </section>
-        <section name="Role Based Access Control">
-            <p>
-                Role based access control (RBAC) in Jetspeed 2 support multiple hierarchy resolution strategies as defined in
-                <a href="http://www.doc.ic.ac.uk/~ecl1/wiki/lib/exe/fetch.php?id=emil%3Aresearchthemes%3Apubbytheme&amp;cache=cache&amp;media=research:papers:1999rbac.pdf">The Uses of Hierarchy in Access Control</a>
-                . See <a href="hierarchy.html">Hierarchy Management Overview</a> for more information.
-            </p>
-        </section>
-    </body>
-</document>
+<?xml version="1.0"?>
+<!--
+    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.
+-->
+<document>
+    <properties>
+        <title>Jetspeed 2 Security Architecture</title>
+        <authors>
+            <person name="David Le Strat" email="dlestrat@apache.org" />
+        </authors>
+    </properties>
+    <body>
+        <section name="Overview">
+            <p>
+                Jetspeed 2 security architecture provides a comprehensive suite of security services that can be used to protect a wide ranging type of portal
+                resources. The security service implementation is fairly independent of the other portal services and 
+                can be reused outside of the portal application.  At its core, Jetspeed 2 security services rely entirely 
+                on JAAS to provide authentication and authorization services to the portal:
+            </p>
+            <ul>
+                <li>Authentication services are implemented through the use of JAAS login modules.</li>
+                <li>Authorization services are implemented through the use of custom JAAS policies.</li>
+            </ul>
+            <p>
+                Both authentication and authorization services have been implemented with the goal of providing a direct plugin to the underlying application
+                server security framework. Jetspeed 2 can leverage the underlying application server login module as well as through the use of JACC, the
+                application server policy management capabilities available in J2EE 1.4 (see
+                <a href="http://java.sun.com/j2ee/javaacc/">API Specifications</a>
+                ).
+            </p>
+        </section>
+        <section name="Jetspeed 2 Security Services">
+            <p>
+                JAAS defines the contract for authentication and authorization but does not specify any guidelines for the management of the security resources.
+                Jetspeed 2 provide a modular set of components aims at providing management functionality for the portal security components.
+            </p>
+            <p>
+                Leveraging Jetspeed 2 component, architecture, the security services provide a set of loosely coupled components providing specialized services:
+            </p>
+            <ul>
+                <li>UserManager: Service providing user management capabilities.</li>
+                <li>GroupManager: Service providing group management capabilities.</li>
+                <li>RoleManager: Service providing role management capabilities.</li>
+                <li>PermissionManager: Service providing permission management capabilities.</li>
+            </ul>
+        </section>
+        <section name="A Modular and Pluggable Architecture">
+            <p>
+                Jetspeed 2 security components are assembled using
+                <a href="http://martinfowler.com/articles/injection.html">Dependency Injection</a>
+                . By default, Jetspeed uses the
+                <a href="http://www.springframework.org">Spring Framework</a>
+                as its default IoC container.
+            </p>
+            <p>
+                <img src="../../images/components/components.jpg" align="right" border="0" hspace="1" vspace="2" />
+                Jetspeed 2 security services are founded on a set of modular and extensible security modules exposed through an SPI model. The SPI model
+                provides the ability to modify the behavior of the Jetspeed coarsed security services (UserManager, RoleManager, GroupManager)
+                through the modification and configuration of specialized handlers. For
+                instance, Jetspeed security services can be configured to retrieve user security principals through the default Jetspeed store or through an
+                LDAP store or both.
+                <br />
+                A
+                <code>SecurityProvider</code>
+                exposes the configured SPI handlers to the security services. Jetspeed component assembly (based on Spring) architecture provides an easy way to
+                reconfigure the security services to satisfy the needs of a specific implementation.
+            </p>
+        </section>
+        <section name="Role Based Access Control">
+            <p>
+                Role based access control (RBAC) in Jetspeed 2 support multiple hierarchy resolution strategies as defined in
+                <a href="http://www.doc.ic.ac.uk/~ecl1/wiki/lib/exe/fetch.php?id=emil%3Aresearchthemes%3Apubbytheme&amp;cache=cache&amp;media=research:papers:1999rbac.pdf">The Uses of Hierarchy in Access Control</a>
+                . See <a href="hierarchy.html">Hierarchy Management Overview</a> for more information.
+            </p>
+        </section>
+    </body>
+</document>

Propchange: portals/jetspeed-2/portal/trunk/src/site/xdoc/components/jetspeed-security/index.xml
------------------------------------------------------------------------------
    svn:eol-style = native



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