[seam-commits] Seam SVN: r8420 - trunk/doc/Seam_Reference_Guide/en-US.
seam-commits at lists.jboss.org
seam-commits at lists.jboss.org
Wed Jun 25 21:52:56 EDT 2008
Author: shane.bryzak at jboss.com
Date: 2008-06-25 21:52:56 -0400 (Wed, 25 Jun 2008)
New Revision: 8420
Modified:
trunk/doc/Seam_Reference_Guide/en-US/Security.xml
Log:
documented "remember me"
Modified: trunk/doc/Seam_Reference_Guide/en-US/Security.xml
===================================================================
--- trunk/doc/Seam_Reference_Guide/en-US/Security.xml 2008-06-26 00:48:02 UTC (rev 8419)
+++ trunk/doc/Seam_Reference_Guide/en-US/Security.xml 2008-06-26 01:52:56 UTC (rev 8420)
@@ -301,7 +301,155 @@
</itemizedlist>
</sect2>
+
+ <sect2>
+ <title>Remember Me</title>
+
+ <para>
+ Seam Security supports the same kind of "Remember Me" functionality that is commonly encountered in many
+ online web-based applications. It is actually supported in two different "flavours", or modes - the first
+ mode allows the username to be stored in the user's browser as a cookie, and leaves the entering of the
+ password up to the browser (many modern browsers are capable of remembering passwords).
+ </para>
+
+ <para>
+ The second mode supports the storing of a unique token in a cookie, and allows a user to authenticate
+ automatically upon returning to the site, without having to provide a password.
+ </para>
+
+ <note>
+ <para>
+ IMPORTANT: Automatic client authentication with a persistent cookie stored on the client machine is dangerous.
+ While convenient for users, any cross-site scripting security hole in your website would have dramatically more
+ serious effects than usual. Without the authentication cookie, the only cookie to steal for an attacker with XSS
+ is the cookie of the current session of a user. This means the attack only works when the user has an open session -
+ which should be a short timespan. However, it is much more attractive and dangerous if an attacker has the possibility
+ to steal a persistent Remember Me cookie that allows him to login without authentication, at any time. Note that this
+ all depends on how well you protect your website against XSS attacks - it's up to you to make sure that your website
+ is 100% XSS safe - a non-trival achievement for any website that allows user input to be rendered on a page.
+ </para>
+
+ <para>
+ Browser vendors recognized this issue and introduced a "Remember Passwords" feature - today almost all browsers support
+ this. Here, the browser remembers the login username and password for a particular website and domain, and fills out the
+ login form automatically when you don't have an active session with the website. If you as a website designer then offer
+ a convenient login keyboard shortcut, this approach is almost as convenient as a "Remember Me" cookie and much safer.
+ Some browsers (e.g. Safari on OS X) even store the login form data in the encrypted global operation system keychain.
+ Or, in a networked environment, the keychain can be transported with the user (between laptop and desktop for example),
+ while browser cookies are usually not synchronized.
+ </para>
+
+ <para>
+ To summarize: While everyone is doing it, persistent "Remember Me" cookies with automatic authentication are a bad
+ practice and should not be used. Cookies that "remember" only the users login name, and fill out the login form with
+ that username as a convenience, are not an issue.
+ </para>
+ </note>
+
+ <para>
+ To enable the remember me feature for the default (safe, username only) mode, no special configuration is required.
+ In your login form, simply bind the remember me checkbox to <literal>rememberMe.enabled</literal>, like in the following
+ example:
+ </para>
+
+ <programlisting><![CDATA[ <div>
+ <h:outputLabel for="name" value="User name"/>
+ <h:inputText id="name" value="#{credentials.username}"/>
+ </div>
+
+ <div>
+ <h:outputLabel for="password" value="Password"/>
+ <h:inputSecret id="password" value="#{credentials.password}" redisplay="true"/>
+ </div>
+
+ <div class="loginRow">
+ <h:outputLabel for="rememberMe" value="Remember me"/>
+ <h:selectBooleanCheckbox id="rememberMe" value="#{rememberMe.enabled}"/>
+ </div>]]></programlisting>
+
+ <sect3>
+ <title>Token-based Remember-me Authentication</title>
+
+ <para>
+ To use the automatic, token-based mode of the remember me feature, you must first configure a token store. The
+ most common scenario is to store these authentication tokens within a database (which Seam supports), however it
+ is possible to implement your own token store by implementing the <literal>org.jboss.seam.security.TokenStore</literal>
+ interface. This section will assume you will be using the provided <literal>JpaTokenStore</literal> implementation
+ to store authentication tokens inside a database table.
+ </para>
+
+ <para>
+ The first step is to create a new Entity which will contain the tokens. The following example shows the possible
+ structure that you may use:
+ </para>
+
+ <programlisting><![CDATA[@Entity
+public class AuthenticationToken implements Serializable {
+ private Integer tokenId;
+ private String username;
+ private String value;
+
+ @Id @GeneratedValue
+ public Integer getTokenId() {
+ return tokenId;
+ }
+
+ public void setTokenId(Integer tokenId) {
+ this.tokenId = tokenId;
+ }
+
+ @TokenUsername
+ public String getUsername() {
+ return username;
+ }
+
+ public void setUsername(String username) {
+ this.username = username;
+ }
+
+ @TokenValue
+ public String getValue() {
+ return value;
+ }
+
+ public void setValue(String value) {
+ this.value = value;
+ }
+}]]></programlisting>
+ <para>
+ As you can see from this listing, a couple of special annotations, <literal>@TokenUsername</literal> and
+ <literal>@TokenValue</literal> are used to configure the username and token properties of the entity. These
+ annotations are required for the entity that will contain the authentication tokens.
+ </para>
+
+ <para>
+ The next step is to configure <literal>JpaTokenStore</literal> to use this entity bean to store and retrieve
+ authentication tokens. This is done in <literal>components.xml</literal> by specifying the <literal>token-class</literal>
+ attribute:
+ </para>
+
+ <programlisting><![CDATA[
+ <security:jpa-token-store token-class="org.jboss.seam.example.seamspace.AuthenticationToken"/>
+ ]]></programlisting>
+
+ <para>
+ Once this is done, the last thing to do is to configure the <literal>RememberMe</literal> component in
+ <literal>components.xml</literal> also. Its <literal>mode</literal> should be set to <literal>autoLogin</literal>:
+ </para>
+
+ <programlisting><![CDATA[ <security:remember-me mode="autoLogin"/>
+ ]]></programlisting>
+
+ <para>
+ That is all that is required - automatic authentication will now occur for users revisiting your site (as long as they
+ check the "remember me" checkbox).
+ </para>
+
+ </sect3>
+
+ </sect2>
+
<sect2>
<title>Handling Security Exceptions</title>
More information about the seam-commits
mailing list