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 at...@apache.org on 2005/09/22 23:42:00 UTC
svn commit: r291020 - in
/portals/jetspeed-2/trunk/components/security/xdocs: config.xml
credentials.xml images/add-user.jpg images/password-expiration.jpg
images/security-locator.jpg images/user-detail-prefs.jpg
Author: ate
Date: Thu Sep 22 14:41:47 2005
New Revision: 291020
URL: http://svn.apache.org/viewcvs?rev=291020&view=rev
Log:
Much improved and extended online documentation for the new features and security configuration provided by:
http://issues.apache.org/jira/browse/JS2-359
http://issues.apache.org/jira/browse/JS2-371
http://issues.apache.org/jira/browse/JS2-372
Added:
portals/jetspeed-2/trunk/components/security/xdocs/images/add-user.jpg (with props)
portals/jetspeed-2/trunk/components/security/xdocs/images/password-expiration.jpg (with props)
portals/jetspeed-2/trunk/components/security/xdocs/images/security-locator.jpg (with props)
portals/jetspeed-2/trunk/components/security/xdocs/images/user-detail-prefs.jpg (with props)
Modified:
portals/jetspeed-2/trunk/components/security/xdocs/config.xml
portals/jetspeed-2/trunk/components/security/xdocs/credentials.xml
Modified: portals/jetspeed-2/trunk/components/security/xdocs/config.xml
URL: http://svn.apache.org/viewcvs/portals/jetspeed-2/trunk/components/security/xdocs/config.xml?rev=291020&r1=291019&r2=291020&view=diff
==============================================================================
--- portals/jetspeed-2/trunk/components/security/xdocs/config.xml (original)
+++ portals/jetspeed-2/trunk/components/security/xdocs/config.xml Thu Sep 22 14:41:47 2005
@@ -19,6 +19,7 @@
<title>Jetspeed 2 Security Services Configuration</title>
<authors>
<person name="David Le Strat" email="dlestrat@apache.org" />
+ <person name="Ate Douma" email="ate@douma.nu" />
</authors>
</properties>
<body>
@@ -125,8 +126,9 @@
<i>PasswordCredentialProvider</i>
; as well as lifecycle management of credentials through
<i>InternalPasswordCredentialInterceptor</i>
- which manages parameters such as maximum number of authentication failures, maximum life span of a credential in days and how much
- history to retain for a given credential.
+ which can be configured to manages parameters such as maximum number of authentication
+ failures, maximum life span of a credential in days and how much history to retain for a
+ given credential.
</td>
</tr>
<tr>
@@ -139,40 +141,148 @@
</tr>
</table>
<p>
- A sample
- <code>CredentialHandler</code>
- configuration could be:
- <source>
- <![CDATA[
+ The following simple <code>CredentialHandler</code> configuration is currently provided
+ by default with Jetspeed:</p>
+ <source><![CDATA[
+<!-- require a non-empty password -->
<bean id="org.apache.jetspeed.security.spi.CredentialPasswordValidator"
- class="org.apache.jetspeed.security.spi.impl.DefaultCredentialPasswordValidator"/>
+ class="org.apache.jetspeed.security.spi.impl.DefaultCredentialPasswordValidator"/>
+<!-- MessageDigest encode passwords using SHA-1 -->
<bean id="org.apache.jetspeed.security.spi.CredentialPasswordEncoder"
- class="org.apache.jetspeed.security.spi.impl.MessageDigestCredentialPasswordEncoder">
- <constructor-arg index="0"><value>SHA-1</value></constructor-arg>
+ class="org.apache.jetspeed.security.spi.impl.MessageDigestCredentialPasswordEncoder">
+ <constructor-arg index="0"><value>SHA-1</value></constructor-arg>
</bean>
+<!-- allow multiple InternalPasswordCredentialInterceptors to be used for DefaultCredentialHandler -->
+<bean id="org.apache.jetspeed.security.spi.InternalPasswordCredentialInterceptor"
+ class="org.apache.jetspeed.security.spi.impl.InternalPasswordCredentialInterceptorsProxy">
+ <constructor-arg index="0">
+ <list>
+ <!-- enforce an invalid preset password value in the persisent store is required to be changed -->
+ <bean class="org.apache.jetspeed.security.spi.impl.ValidatePasswordOnLoadInterceptor"/>
+
+ <!-- ensure preset cleartext passwords in the persistent store will be encoded on first use -->
+ <bean class="org.apache.jetspeed.security.spi.impl.EncodePasswordOnFirstLoadInterceptor"/>
+ </list>
+ </constructor-arg>
+</bean>
+
<bean id="org.apache.jetspeed.security.spi.PasswordCredentialProvider"
- class="org.apache.jetspeed.security.spi.impl.DefaultPasswordCredentialProvider">
- <constructor-arg index="0">
- <ref bean="org.apache.jetspeed.security.spi.CredentialPasswordValidator"/>
- </constructor-arg>
- <constructor-arg index="1">
- <ref bean="org.apache.jetspeed.security.spi.CredentialPasswordEncoder"/>
- </constructor-arg>
+ class="org.apache.jetspeed.security.spi.impl.DefaultPasswordCredentialProvider">
+ <constructor-arg index="0">
+ <ref bean="org.apache.jetspeed.security.spi.CredentialPasswordValidator"/>
+ </constructor-arg>
+ <constructor-arg index="1">
+ <ref bean="org.apache.jetspeed.security.spi.CredentialPasswordEncoder"/>
+ </constructor-arg>
</bean>
-<bean id="org.apache.jetspeed.security.spi.InternalPasswordCredentialInterceptor"
- class="org.apache.jetspeed.security.spi.impl.InternalPasswordCredentialHistoryHandlingInterceptor">
- <!-- maxNumberOfAuthenticationFailures -->
- <constructor-arg index="0"><value>3</value></constructor-arg>
- <!-- maxLifeSpanInDays -->
- <constructor-arg index="1"><value>60</value></constructor-arg>
- <!-- historySize -->
- <constructor-arg index="2"><value>3</value></constructor-arg>
+<bean id="org.apache.jetspeed.security.spi.CredentialHandler"
+ class="org.apache.jetspeed.security.spi.impl.DefaultCredentialHandler">
+ <constructor-arg index="0">
+ <ref bean="org.apache.jetspeed.security.spi.SecurityAccess"/>
+ </constructor-arg>
+ <constructor-arg index="1">
+ <ref bean="org.apache.jetspeed.security.spi.PasswordCredentialProvider"/>
+ </constructor-arg>
+ <constructor-arg index="2">
+ <ref bean="org.apache.jetspeed.security.spi.InternalPasswordCredentialInterceptor"/>
+ </constructor-arg>
</bean>]]>
- </source>
- </p>
+ </source>
+ <p>
+ The above configuration requires not much more than that a password should not be
+ empty and MessageDigest encode it using SHA-1.</p>
+ <p>
+ Before the 2.0-M4 release, Jetspeed came configured with a much stricter configuration, but for
+ first time users of the Portal this was a bit overwelming and also quite difficult to configure
+ differently.</p>
+ <p>
+ With the 2.0-M4 release, the previously provided, and rather complex,
+ <code>InternalPasswordCredentialInterceptor</code> implementations are split up in single atomic
+ interceptors which can much easier be configured indepedently.</p>
+ <p>
+ An overview of the new interceptors and how related request processing pipeline valves can be
+ configured to provide feedback to the user is provided in the <a href="credentials.html">
+ Credentials Management</a> document.</p>
+ <p>
+ Since the "old" (pre 2.0-M4) interceptors are no longer provided with Jetspeed, the example below
+ shows how to "restore" the old setup using the new interceptors:</p>
+ <source><![CDATA[
+<!-- require a password of minimum length 6 and at least two numeric characters -->
+<bean id="org.apache.jetspeed.security.spi.CredentialPasswordValidator"
+ class="org.apache.jetspeed.security.spi.impl.SimpleCredentialPasswordValidator">
+ <constructor-arg index="0"><value>6</value></constructor-arg>
+ <constructor-arg index="1"><value>2</value></constructor-arg>
+</bean>
+
+<!-- allow multiple InternalPasswordCredentialInterceptors to be used for DefaultCredentialHandler -->
+<bean id="org.apache.jetspeed.security.spi.InternalPasswordCredentialInterceptor"
+ class="org.apache.jetspeed.security.spi.impl.InternalPasswordCredentialInterceptorsProxy">
+ <constructor-arg index="0">
+ <list>
+ <!-- enforce an invalid preset password value in the persisent store is required to be changed -->
+ <bean class="org.apache.jetspeed.security.spi.impl.ValidatePasswordOnLoadInterceptor"/>
+
+ <!-- ensure preset cleartext passwords in the persistent store will be encoded on first use -->
+ <bean class="org.apache.jetspeed.security.spi.impl.EncodePasswordOnFirstLoadInterceptor"/>
+
+ <!-- remember the last 3 passwords used and require a new password to be different from those -->
+ <bean class="org.apache.jetspeed.security.spi.impl.PasswordHistoryInterceptor">
+ <constructor-arg index="0"><value>3</value></constructor-arg>
+ </bean>
+
+ <!-- Automatically expire a password after 60 days -->
+ <bean class="org.apache.jetspeed.security.spi.impl.PasswordExpirationInterceptor">
+ <constructor-arg index="0"><value>60</value></constructor-arg>
+ </bean>
+
+ <!-- Automatically disable a password after 3 invalid authentication attempts in a row -->
+ <bean class="org.apache.jetspeed.security.spi.impl.MaxPasswordAuthenticationFailuresInterceptor">
+ <constructor-arg index="0"><value>3</value></constructor-arg>
+ </bean>
+ </list>
+ </constructor-arg>
+</bean>]]>
+ </source>
+ <p>
+ And, make sure something like the following configuration is set for the security related valves in
+ pipelines.xml:</p>
+ <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>
+
+<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>
+ Also, make sure the above valves are configured in the <code>jetspeed-pipeline</code> bean.</p>
+ <p>
+ See the <a href="credentials.html#User_interaction">User Interaction</a> section in the
+ Credentials Management document for a description of these valves and their relation to the
+ interceptors configuration.</p>
</subsection>
<subsection name="security-spi-atz.xml">
<p>This configuration file contains all the configurations for configuring the authorization SPI.</p>
Modified: portals/jetspeed-2/trunk/components/security/xdocs/credentials.xml
URL: http://svn.apache.org/viewcvs/portals/jetspeed-2/trunk/components/security/xdocs/credentials.xml?rev=291020&r1=291019&r2=291020&view=diff
==============================================================================
--- portals/jetspeed-2/trunk/components/security/xdocs/credentials.xml (original)
+++ portals/jetspeed-2/trunk/components/security/xdocs/credentials.xml Thu Sep 22 14:41:47 2005
@@ -3,36 +3,129 @@
<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>
- Jetspeed
- <code>DefaultCredentialHandler</code>
- provides the following features:
- </p>
- <ol>
- <li>
- Provides the ability to store password in a encoded fashion. The initial implementation uses
- <code>SHA-1</code> and <code>Base64</code> as a default encoding. The default
- <code>MessageDisgetCredentialPasswordEncoder</code> implements <code>CredentialPasswordEncoder</code>
- and uses <a href="http://java.sun.com/j2se/1.4.2/docs/api/java/security/MessageDigest.html">MessageDigest</a>
- hash algorithms for password encryption.
+ 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>Provides the ability to specify a minimum length and a minimum number of numeric characters in a password</li>
- <li>
- Keeps an history (queue) of previously used password and preventing a user to reuse a password that is currently stored in the user's
- password history (queue). The queue size is configurale.
+ <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>Automatically expires a user's password after a configurable time.</li>
- <li>Warns users that their password is about to expire. Notification time period is configurable.</li>
- <li>Locks a user account when the current password is expired.</li>
- <li>Forces a user to change his/her password on first use.</li>
- <li>Disable a user's password after a certain number of unsuccessful authentication attempts.</li>
- </ol>
- </section>
- <section name="DefaultCredentialHandler Implementation">
+ <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>
@@ -41,27 +134,6 @@
<p align="center">
<img src="images/credential-handler-c.gif" border="0" />
</p>
- <table>
- <tr>
- <th>Bean</th>
- <th>Description</th>
- </tr>
- <tr>
- <td><code>DefaultCredentialHandler</code></td>
- <td>Encapsulates the operations involving manipulation of credentials.</td>
- </tr>
- <tr>
- <td>PasswordCredentialProvider</td>
- <td>Provides the encoding and validation rules for passwords through the <code>CredentialPasswordEncoder</code>
- which encapsulates the encoding and <code>CredentialPasswordValidator</code> which encapsulates
- the password validation rules.</td>
- </tr>
- <tr>
- <td>InternalPasswordCredentialInterceptor</td>
- <td>Provide credential lifecycle management. Manages parameters such as maximum number of authentication failures,
- maximum life span of a credential in days and how much history to retain for a given credential.</td>
- </tr>
- </table>
<p>
The OJB mappings for the default credentials implementation are described in
<code>security_repository.xml</code>:
@@ -73,6 +145,178 @@
<p align="center">
<img src="images/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#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/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#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/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/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/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>
Added: portals/jetspeed-2/trunk/components/security/xdocs/images/add-user.jpg
URL: http://svn.apache.org/viewcvs/portals/jetspeed-2/trunk/components/security/xdocs/images/add-user.jpg?rev=291020&view=auto
==============================================================================
Binary file - no diff available.
Propchange: portals/jetspeed-2/trunk/components/security/xdocs/images/add-user.jpg
------------------------------------------------------------------------------
svn:mime-type = image/jpeg
Added: portals/jetspeed-2/trunk/components/security/xdocs/images/password-expiration.jpg
URL: http://svn.apache.org/viewcvs/portals/jetspeed-2/trunk/components/security/xdocs/images/password-expiration.jpg?rev=291020&view=auto
==============================================================================
Binary file - no diff available.
Propchange: portals/jetspeed-2/trunk/components/security/xdocs/images/password-expiration.jpg
------------------------------------------------------------------------------
svn:mime-type = image/jpeg
Added: portals/jetspeed-2/trunk/components/security/xdocs/images/security-locator.jpg
URL: http://svn.apache.org/viewcvs/portals/jetspeed-2/trunk/components/security/xdocs/images/security-locator.jpg?rev=291020&view=auto
==============================================================================
Binary file - no diff available.
Propchange: portals/jetspeed-2/trunk/components/security/xdocs/images/security-locator.jpg
------------------------------------------------------------------------------
svn:mime-type = image/jpeg
Added: portals/jetspeed-2/trunk/components/security/xdocs/images/user-detail-prefs.jpg
URL: http://svn.apache.org/viewcvs/portals/jetspeed-2/trunk/components/security/xdocs/images/user-detail-prefs.jpg?rev=291020&view=auto
==============================================================================
Binary file - no diff available.
Propchange: portals/jetspeed-2/trunk/components/security/xdocs/images/user-detail-prefs.jpg
------------------------------------------------------------------------------
svn:mime-type = image/jpeg
---------------------------------------------------------------------
To unsubscribe, e-mail: jetspeed-dev-unsubscribe@portals.apache.org
For additional commands, e-mail: jetspeed-dev-help@portals.apache.org