[jboss-cvs] JBossAS SVN: r103736 - projects/docs/enterprise/5.0/Seam_Reference_Guide/en-US.
jboss-cvs-commits at lists.jboss.org
jboss-cvs-commits at lists.jboss.org
Fri Apr 9 03:21:33 EDT 2010
Author: laubai
Date: 2010-04-09 03:21:33 -0400 (Fri, 09 Apr 2010)
New Revision: 103736
Modified:
projects/docs/enterprise/5.0/Seam_Reference_Guide/en-US/Security.xml
Log:
Changed tables into variablelists to prevent publican issue with programlisting in entry tags.
Modified: projects/docs/enterprise/5.0/Seam_Reference_Guide/en-US/Security.xml
===================================================================
--- projects/docs/enterprise/5.0/Seam_Reference_Guide/en-US/Security.xml 2010-04-09 07:06:28 UTC (rev 103735)
+++ projects/docs/enterprise/5.0/Seam_Reference_Guide/en-US/Security.xml 2010-04-09 07:21:33 UTC (rev 103736)
@@ -226,21 +226,21 @@
There are three easy steps to configure authentication:
</para>
<itemizedlist>
- <listitem>
- <para>
- Configure an authentication method in <filename>components.xml</filename>.
- </para>
- </listitem>
- <listitem>
- <para>
- Write an authentication method.
- </para>
- </listitem>
- <listitem>
- <para>
- Write a login form so that the user can authenticate.
- </para>
- </listitem>
+ <listitem>
+ <para>
+ Configure an authentication method in <filename>components.xml</filename>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Write an authentication method.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Write a login form so that the user can authenticate.
+ </para>
+ </listitem>
</itemizedlist>
</section>
@@ -250,15 +250,15 @@
Seam Security supports two different modes of the <emphasis>Remember Me</emphasis> functionality common to many web-based applications. The first mode allows the username to be stored in the user's browser as a cookie, and leaves the browser to remember the password. The second mode stores a unique token in a cookie, and lets a user authenticate automatically when they return to the site, without having to provide a password.
</para>
<warning>
- <para>
- Although it is convenient for users, automatic client authentication through a persistent cookie on the client machine is dangerous because the effects of any cross-site scripting (XSS) security hole are magnified. Without the authentication cookie, the only cookie an attacker can steal with XSS is the user's <emphasis>current session cookie</emphasis> — so an attack can only occur while a user has a session open. If a persistent <emphasis>Remember Me</emphasis> cookie is stolen, an attacker can log in without authentication at any time. If you wish to use automatic client authentication, it is vital to protect your website against XSS attacks.
- </para>
- <para>
- Browser vendors introduced the <emphasis>Remember Passwords</emphasis> feature to combat this issue. Here, the browser remembers the username and password used to log in to a particular website and domain, and automatically fills in the login form when there is no session active. A login keyboard shortcut on your website can make the login process almost as convenient as the "Remember Me" cookie, and much safer. Some browsers (for example, Safari on OS X) store the login form data in the encrypted global operation system keychain. In a networked environment, the keychain can be transported with the user between laptop and desktop — cookies are not usually synchronised.
- </para>
- <para>
- Although persistent <emphasis>Remember Me</emphasis> cookies with automatic authentication are widely used, they are bad security practice. Cookies that recall only the user's login name, and fill out the login form with that username as a convenience, are much more secure.
- </para>
+ <para>
+ Although it is convenient for users, automatic client authentication through a persistent cookie on the client machine is dangerous because the effects of any cross-site scripting (XSS) security hole are magnified. Without the authentication cookie, the only cookie an attacker can steal with XSS is the user's <emphasis>current session cookie</emphasis> — so an attack can only occur while a user has a session open. If a persistent <emphasis>Remember Me</emphasis> cookie is stolen, an attacker can log in without authentication at any time. If you wish to use automatic client authentication, it is vital to protect your website against XSS attacks.
+ </para>
+ <para>
+ Browser vendors introduced the <emphasis>Remember Passwords</emphasis> feature to combat this issue. Here, the browser remembers the username and password used to log in to a particular website and domain, and automatically fills in the login form when there is no session active. A login keyboard shortcut on your website can make the login process almost as convenient as the "Remember Me" cookie, and much safer. Some browsers (for example, Safari on OS X) store the login form data in the encrypted global operation system keychain. In a networked environment, the keychain can be transported with the user between laptop and desktop — cookies are not usually synchronised.
+ </para>
+ <para>
+ Although persistent <emphasis>Remember Me</emphasis> cookies with automatic authentication are widely used, they are bad security practice. Cookies that recall only the user's login name, and fill out the login form with that username as a convenience, are much more secure.
+ </para>
</warning>
<para>
No special configuration is required to enable the <emphasis>Remember Me</emphasis> feature for the default (safe, username-only) mode. In your login form, simply bind the <emphasis>Remember Me</emphasis> checkbox to <literal>rememberMe.enabled</literal>, as seen in the following example:
@@ -569,230 +569,95 @@
</section>
<section>
- <title>Configuring the Entities</title>
- <para>
- The following table describes the special annotations used to configure entity beans for user and role storage.
- </para>
- <table>
- <title>User Entity Annotations</title>
- <tgroup cols="3">
- <colspec colnum="1" colwidth="2*"></colspec>
- <colspec colnum="2" colwidth="1*"></colspec>
- <colspec colnum="3" colwidth="3*"></colspec>
- <thead>
- <row>
- <entry align="center">
- <para>
- Annotation
- </para>
- </entry>
- <entry align="center">
- <para>
- Status
- </para>
- </entry>
- <entry align="center">
- <para>
- Description
- </para>
- </entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>
- <para>
- <literal>@UserPrincipal</literal>
- </para>
- </entry>
- <entry>
- <para>
- Required
- </para>
- </entry>
- <entry>
- <para>
- This annotation marks the field or method containing the user's username.
- </para>
- </entry>
- </row>
- <row>
- <entry>
- <para>
- <literal>@UserPassword</literal>
- </para>
- </entry>
- <entry>
- <para>
- Required
- </para>
- </entry>
- <entry>
- <para>
- This annotation marks the field or method containing the user's password. It allows a <literal>hash</literal> algorithm to be specified for password hashing. Possible values for <literal>hash</literal> are <literal>md5</literal>, <literal>sha</literal> and <literal>none</literal>. For example:
- </para>
- <para>
- It is possible to extend the <literal>PasswordHash</literal> component to implement other hashing algorithms, if required.
- </para>
-
- <programlisting role="JAVA"><![CDATA[@UserPassword(hash = "md5")
- public String getPasswordHash() {
- return passwordHash;
- }]]>
- </programlisting>
- </entry>
- </row>
- <row>
- <entry>
- <para>
- <literal>@UserFirstName</literal>
- </para>
- </entry>
- <entry>
- <para>
- Optional
- </para>
- </entry>
- <entry>
- <para>
- This annotation marks the field or method containing the user's first name.
- </para>
- </entry>
- </row>
- <row>
- <entry>
- <para>
- <literal>@UserLastName</literal>
- </para>
- </entry>
- <entry>
- <para>
- Optional
- </para>
- </entry>
- <entry>
- <para>
- This annotation marks the field or method containing the user's last name.
- </para>
- </entry>
- </row>
- <row>
- <entry>
- <para>
- <literal>@UserEnabled</literal>
- </para>
- </entry>
- <entry>
- <para>
- Optional
- </para>
- </entry>
- <entry>
- <para>
- This annotation marks the field or method containing the enabled user status. This should be a Boolean property. If not present, all user accounts are assumed to be enabled.
- </para>
- </entry>
- </row>
- <row>
- <entry>
- <para>
- <literal>@UserRoles</literal>
- </para>
- </entry>
- <entry>
- <para>
- Required
- </para>
- </entry>
- <entry>
- <para>
- This annotation marks the field or method containing the roles of the user. This property will be described in more detail in a later section. <!-- #modify: xref if possible -->
- </para>
- </entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- <table>
- <title>Role Entity Annotations</title>
- <tgroup cols="3">
- <colspec colnum="1" colwidth="2*"></colspec>
- <colspec colnum="2" colwidth="1*"></colspec>
- <colspec colnum="3" colwidth="3*"></colspec>
- <thead>
- <row>
- <entry align="center">
- <para>
- Annotation
- </para>
- </entry>
- <entry align="center">
- <para>
- Status
- </para>
- </entry>
- <entry align="center">
- <para>
- Description
- </para>
- </entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>
- <para>
- <literal>@RoleName</literal>
- </para>
- </entry>
- <entry>
- <para>
- Required
- </para>
- </entry>
- <entry>
- <para>
- This annotation marks the field or method containing the name of the role.
- </para>
- </entry>
- </row>
- <row>
- <entry>
- <para>
- <literal>@RoleGroups</literal>
- </para>
- </entry>
- <entry>
- <para>
- Optional
- </para>
- </entry>
- <entry>
- <para>
- This annotation marks the field or method containing the group memberships of the role.
- </para>
- </entry>
- </row>
- <row>
- <entry>
- <para>
- <literal>@RoleConditional</literal>
- </para>
- </entry>
- <entry>
- <para>
- Optional
- </para>
- </entry>
- <entry>
- <para>
- This annotation marks the field or method that indicates whether a role is conditional. Conditional roles are explained later in this chapter.
- </para>
- </entry>
- </row>
- </tbody>
- </tgroup>
- </table>
+ <title>Configuring the Entities</title>
+ <para>
+ The following table describes the special annotations used to configure entity beans for user and role storage.
+ </para>
+ <variablelist>
+ <title>User Entity Annotations</title>
+ <varlistentry>
+ <term>@UserPrincipal</term>
+ <listitem>
+ <para>
+ Required. This annotation marks the field or method containing the user's username.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>@UserPassword</term>
+ <listitem>
+ <para>
+ Required. This annotation marks the field or method containing the user's password. It allows a <literal>hash</literal> algorithm to be specified for password hashing. Possible values for <literal>hash</literal> are <literal>md5</literal>, <literal>sha</literal> and <literal>none</literal>. For example:
+ </para>
+ <programlisting role="JAVA"><![CDATA[@UserPassword(hash = "md5")
+ public String getPasswordHash() {
+ return passwordHash;
+ }]]></programlisting>
+ <para>
+ It is possible to extend the <literal>PasswordHash</literal> component to implement other hashing algorithms, if required.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>@UserFirstName</term>
+ <listitem>
+ <para>
+ Optional. This annotation marks the field or method containing the user's first name.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>@UserLastName</term>
+ <listitem>
+ <para>
+ Optional. This annotation marks the field or method containing the user's last name.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>@UserEnabled</term>
+ <listitem>
+ <para>
+ Optional. This annotation marks the field or method containing the enabled user status. This should be a Boolean property. If not present, all user accounts are assumed to be enabled.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>@UserRoles</term>
+ <listitem>
+ <para>
+ Required. This annotation marks the field or method containing the roles of the user. This property will be described in more detail in a later section.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ <variablelist>
+ <title>Role Entity Annotations</title>
+ <varlistentry>
+ <term>@RoleName</term>
+ <listitem>
+ <para>
+ Required. This annotation marks the field or method containing the name of the role.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>@RoleGroups</term>
+ <listitem>
+ <para>
+ Optional. This annotation marks the field or method containing the group memberships of the role.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>@RoleConditional</term>
+ <listitem>
+ <para>
+ Optional. This annotation marks the field or method that indicates whether a role is conditional. Conditional roles are explained later in this chapter.
+ </para>
+ </listitem>
+ </varlistentry>
+ </varlistentry>
</section>
<section>
@@ -3573,131 +3438,131 @@
role-permission-class="com.acme.model.RolePermission"/>]]>
</programlisting>
<section>
- <title>Permission annotations</title>
- <para>
- The entity classes that contain the user and role permissions must be configured with a special set of annotations in the <literal>org.jboss.seam.annotations.security.permission</literal> package. The following table describes these annotations:
- </para>
- <table>
- <title>Entity Permission annotations</title>
- <tgroup cols="3">
- <colspec colnum="1" colwidth="2*"></colspec>
- <colspec colnum="2" colwidth="1*"></colspec>
- <colspec colnum="3" colwidth="2*"></colspec>
- <thead>
- <row>
- <entry align="center">
- <para>
- Annotation
- </para>
- </entry>
- <entry align="center">
- <para>
- Target
- </para>
- </entry>
- <entry align="center">
- <para>
- Description
- </para>
- </entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>
- <para>
- <literal>@PermissionTarget</literal>
- </para>
- </entry>
- <entry>
- <para>
- <literal>FIELD,METHOD</literal>
- </para>
- </entry>
- <entry>
- <para>
- This annotation identifies the entity property containing the permission target. The property should be of type <literal>java.lang.String</literal>.
- </para>
- </entry>
- </row>
- <row>
- <entry>
- <para>
- <literal>@PermissionAction</literal>
- </para>
- </entry>
- <entry>
- <para>
- <literal>FIELD,METHOD</literal>
- </para>
- </entry>
- <entry>
- <para>
- This annotation identifies the entity property containing the permission action. The property should be of type <literal>java.lang.String</literal>.
- </para>
- </entry>
- </row>
- <row>
- <entry>
- <para>
- <literal>@PermissionUser</literal>
- </para>
- </entry>
- <entry>
- <para>
- <literal>FIELD,METHOD</literal>
- </para>
- </entry>
- <entry>
- <para>
- This annotation identifies the entity property containing the recipient user for the permission. It should be of type <literal>java.lang.String</literal> and contain the user's username.
- </para>
- </entry>
- </row>
- <row>
- <entry>
- <para>
- <literal>@PermissionRole</literal>
- </para>
- </entry>
- <entry>
- <para>
- <literal>FIELD,METHOD</literal>
- </para>
- </entry>
- <entry>
- <para>
- This annotation identifies the entity property containing the recipient role for the permission. It should be of type <literal>java.lang.String</literal> and contain the role name.
- </para>
- </entry>
- </row>
- <row>
- <entry>
- <para>
- <literal>@PermissionDiscriminator</literal>
- </para>
- </entry>
- <entry>
- <para>
- <literal>FIELD,METHOD</literal>
- </para>
- </entry>
- <entry>
- <para>
- This annotation should be used when the same entity/table stores both user and role permissions. It identifies the property of the entity being used to discriminate between user and role permissions. By default, if the column value contains the string literal <literal>user</literal>, then the record will be treated as a user permission. If it contains the string literal <literal>role</literal>, it will be treated as a role permission. You can also override these defaults by specifying the <literal>userValue</literal> and <literal>roleValue</literal> properties within the annotation. For example, to use <literal>u</literal> and <literal>r</literal> instead of <literal>user</literal> and <literal>role</literal>, write the annotation like so:
- </para>
-
-
-<programlisting role="JAVA"><![CDATA[
- at PermissionDiscriminator(
- userValue = "u",
- roleValue = "r")]]>
-</programlisting>
- </entry>
- </row>
- </tbody>
- </tgroup>
- </table>
+ <title>Permission annotations</title>
+ <para>
+ The entity classes that contain the user and role permissions must be configured with a special set of annotations in the <literal>org.jboss.seam.annotations.security.permission</literal> package. The following list describes these annotations:
+ </para>
+ <variablelist>
+ <title>Entity Permission annotations</title>
+ <varlistentry>
+ <term>@PermissionTarget</term>
+ <listitem>
+ <variablelist>
+ <varlistentry>
+ <term>Target:</term>
+ <listitem>
+ <para>
+ <literal>FIELD<literal>, <literal>METHOD</literal>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Description:</term>
+ <listitem>
+ <para>
+ This annotation identifies the entity property containing the permission target. The property should be of type <classname>java.lang.String</classname>.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>@PermissionAction</term>
+ <listitem>
+ <variablelist>
+ <varlistentry>
+ <term>Target:</term>
+ <listitem>
+ <para>
+ <literal>FIELD<literal>, <literal>METHOD</literal>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Description:</term>
+ <listitem>
+ <para>
+ This annotation identifies the entity property containing the permission action. The property should be of type <classname>java.lang.String</classname>.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>@PermissionUser</term>
+ <listitem>
+ <variablelist>
+ <varlistentry>
+ <term>Target:</term>
+ <listitem>
+ <para>
+ <literal>FIELD<literal>, <literal>METHOD</literal>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Description:</term>
+ <listitem>
+ <para>
+ This annotation identifies the entity property containing the recipient user for the permission. It should be of type <classname>java.lang.String</classname> and contain the user's username.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>@PermissionRole</term>
+ <listitem>
+ <variablelist>
+ <varlistentry>
+ <term>Target:</term>
+ <listitem>
+ <para>
+ <literal>FIELD<literal>, <literal>METHOD</literal>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Description:</term>
+ <listitem>
+ <para>
+ This annotation identifies the entity property containing the recipient role for the permission. It should be of type <classname>java.lang.String</classname> and contain the role name.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>@PermissionDiscriminator</term>
+ <listitem>
+ <variablelist>
+ <varlistentry>
+ <term>Target:</term>
+ <listitem>
+ <para>
+ <literal>FIELD<literal>, <literal>METHOD</literal>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Description:</term>
+ <listitem>
+ <para>
+ This annotation should be used when the same entity/table stores both user and role permissions. It identifies the property of the entity being used to discriminate between user and role permissions. By default, if the column value contains the string literal <literal>user</literal>, then the record will be treated as a user permission. If it contains the string literal <literal>role</literal>, it will be treated as a role permission. You can also override these defaults by specifying the <literal>userValue</literal> and <literal>roleValue</literal> properties within the annotation. For example, to use <literal>u</literal> and <literal>r</literal> instead of <literal>user</literal> and <literal>role</literal>, write the annotation like so:
+ </para>
+ <programlisting role="JAVA"><![CDATA[@PermissionDiscriminator(
+ userValue = "u",
+ roleValue = "r")]]></programlisting>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+ </variablelist>
</section>
<section>
More information about the jboss-cvs-commits
mailing list