From seam-commits at lists.jboss.org Wed Jun 25 21:52:57 2008
Content-Type: multipart/mixed; boundary="===============4295457472103413440=="
MIME-Version: 1.0
From: seam-commits at lists.jboss.org
To: seam-commits at lists.jboss.org
Subject: [seam-commits] Seam SVN: r8420 - trunk/doc/Seam_Reference_Guide/en-US.
Date: Wed, 25 Jun 2008 21:52:56 -0400
Message-ID: <E1KBgfQ-0001Nr-Jq@committer01.frg.pub.inap.atl.jboss.com>

--===============4295457472103413440==
Content-Type: text/plain; charset="utf-8"
MIME-Version: 1.0
Content-Transfer-Encoding: quoted-printable

Author: shane.bryzak(a)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
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D
--- trunk/doc/Seam_Reference_Guide/en-US/Security.xml	2008-06-26 00:48:02 U=
TC (rev 8419)
+++ trunk/doc/Seam_Reference_Guide/en-US/Security.xml	2008-06-26 01:52:56 U=
TC (rev 8420)
@@ -301,7 +301,155 @@
       </itemizedlist>
 =

     </sect2>
+    =

+    <sect2>
+      <title>Remember Me</title>
+      =

+      <para>
+        Seam Security supports the same kind of "Remember Me" functionalit=
y that is commonly encountered in many
+        online web-based applications.  It is actually supported in two di=
fferent "flavours", or modes - the first
+        mode allows the username to be stored in the user's browser as a c=
ookie, and leaves the entering of the
+        password up to the browser (many modern browsers are capable of re=
membering 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 provid=
e a password.
+      </para>
+      =

+      <note>
+        <para>
+          IMPORTANT: Automatic client authentication with a persistent coo=
kie stored on the client machine is dangerous.  =

+          While convenient for users, any cross-site scripting security ho=
le in your website would have dramatically more =

+          serious effects than usual. Without the authentication cookie, t=
he only cookie to steal for an attacker with XSS =

+          is the cookie of the current session of a user. This means the a=
ttack only works when the user has an open session - =

+          which should be a short timespan. However, it is much more attra=
ctive and dangerous if an attacker has the possibility =

+          to steal a persistent Remember Me cookie that allows him to logi=
n without authentication, at any time. Note that this =

+          all depends on how well you protect your website against XSS att=
acks - 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 passwor=
d for a particular website and domain, and fills out the =

+          login form automatically when you don't have an active session w=
ith 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 da=
ta 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 M=
e" cookies with automatic authentication are a bad =

+          practice and should not be used. Cookies that "remember" only th=
e 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 <liter=
al>rememberMe.enabled</literal>, like in the following
+        example:
+      </para>
+      =

+      <programlisting><![CDATA[  <div>
+    <h:outputLabel for=3D"name" value=3D"User name"/>
+    <h:inputText id=3D"name" value=3D"#{credentials.username}"/>
+  </div>
+  =

+  <div>
+    <h:outputLabel for=3D"password" value=3D"Password"/>
+    <h:inputSecret id=3D"password" value=3D"#{credentials.password}" redis=
play=3D"true"/>
+  </div>      =

+  =

+  <div class=3D"loginRow">
+    <h:outputLabel for=3D"rememberMe" value=3D"Remember me"/>
+    <h:selectBooleanCheckbox id=3D"rememberMe" value=3D"#{rememberMe.enabl=
ed}"/>
+  </div>]]></programlisting>
+  =

+      <sect3>
+        <title>Token-based Remember-me Authentication</title>
+        =

+        <para>
+          To use the automatic, token-based mode of the remember me featur=
e, you must first configure a token store.  The
+          most common scenario is to store these authentication tokens wit=
hin a database (which Seam supports), however it =

+          is possible to implement your own token store by implementing th=
e <literal>org.jboss.seam.security.TokenStore</literal>
+          interface.  This section will assume you will be using the provi=
ded <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 =3D tokenId;
+   }
+   =

+   @TokenUsername
+   public String getUsername() {
+      return username;
+   }
+   =

+   public void setUsername(String username) {
+      this.username =3D username;
+   }
+   =

+   @TokenValue
+   public String getValue() {
+      return value;
+   }
+   =

+   public void setValue(String value) {
+      this.value =3D value;
+   }
+}]]></programlisting>
 =

+        <para>
+          As you can see from this listing, a couple of special annotation=
s, <literal>@TokenUsername</literal> and
+          <literal>@TokenValue</literal> are used to configure the usernam=
e and token properties of the entity.  These
+          annotations are required for the entity that will contain the au=
thentication tokens.
+        </para>
+        =

+        <para>
+          The next step is to configure <literal>JpaTokenStore</literal> t=
o 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=3D"org.jboss.seam.example.seamspac=
e.AuthenticationToken"/>        =

+        ]]></programlisting>
+        =

+        <para>
+          Once this is done, the last thing to do is to configure the <lit=
eral>RememberMe</literal> component in
+          <literal>components.xml</literal> also.  Its <literal>mode</lite=
ral> should be set to <literal>autoLogin</literal>:
+        </para>
+        =

+        <programlisting><![CDATA[  <security:remember-me mode=3D"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>
 =



--===============4295457472103413440==--