[jboss-cvs] jboss-seam/doc/reference/en/modules ...
Shane Bryzak
Shane_Bryzak at symantec.com
Tue Jan 30 02:30:13 EST 2007
User: sbryzak2
Date: 07/01/30 02:30:13
Modified: doc/reference/en/modules security.xml
Log:
documented interface and page security
Revision Changes Path
1.10 +245 -127 jboss-seam/doc/reference/en/modules/security.xml
(In the diff below, changes in quantity of whitespace are not shown.)
Index: security.xml
===================================================================
RCS file: /cvsroot/jboss/jboss-seam/doc/reference/en/modules/security.xml,v
retrieving revision 1.9
retrieving revision 1.10
diff -u -b -r1.9 -r1.10
--- security.xml 30 Jan 2007 03:32:45 -0000 1.9
+++ security.xml 30 Jan 2007 07:30:13 -0000 1.10
@@ -2,10 +2,8 @@
<title>Security</title>
<para>
- The Seam Security API is an optional Seam module that provides authentication and authorization features
- for securing both domain and page resources within your Seam project. It supports multiple levels of security
- <emphasis>granularity</emphasis>, making it capable of performing either simple role-based security checks,
- or at the other end of the scale complex rule-based permission checks on domain objects using JBoss Rules.
+ The Seam Security API is an optional Seam feature that provides authentication and authorization features
+ for securing both domain and page resources within your Seam project.
</para>
<sect1>
@@ -460,7 +458,127 @@
</sect3>
</sect2>
+ <sect2>
+ <title>Securing your interface</title>
+
+ <para>
+ One indication of a well designed user interface is that the user is not presented with options for
+ which they don't have the necessary privileges to use. Seam Security allows conditional rendering of
+ either 1) sections of a page or 2) individual controls, based upon the privileges of the user, using
+ the very same EL expressions that are used for component security.
+ </para>
+
+ <para>
+ Let's take a look at some examples of interface security. First of all, let's pretend that we have a
+ login form that should only be rendered if the user is not already logged in. Using the
+ <literal>identity.isLoggedIn()</literal> property, we can write this:
+ </para>
+
+ <programlisting>
+ <![CDATA[
+ <h:form class="loginForm" rendered="#{not identity.loggedIn}">
+ ]]>
+ </programlisting>
+
+ <para>
+ If the user isn't logged in, then the login form will be rendered - very straight forward so far.
+ Now let's pretend there is a menu on the page that contains some actions which should only be accessible
+ to users in the <literal>manager</literal> role. Here's one way that these could be written:
+ </para>
+ <programlisting>
+ <![CDATA[
+ <h:outputLink action="#{reports.listManagerReports}" rendered="#{s:hasRole('manager')}">
+ Manager Reports
+ </h:outputLink>]
+ ]]>
+ </programlisting>
+
+ <para>
+ This is also quite straight forward. If the user is not a member of the <literal>manager</literal>
+ role, then the outputLink will not be rendered. The <literal>rendered</literal> attribute can
+ generally be used on the control itself, or on a surrounding <literal><s:div></literal> or
+ <literal><s:span></literal> control.
+ </para>
+
+ <para>
+ Now for something more complex. Let's say you have a <literal>h:dataTable</literal> control on a
+ page listing records for which you may or may not wish to render action links depending on the
+ user's privileges. The <literal>s:hasPermission</literal> EL function allows us to pass in an
+ object parameter which can be used to determine whether the user has the requested permission
+ for that object or not. Here's how a dataTable with secured links might look:
+ </para>
+
+ <programlisting>
+ <![CDATA[
+ <h:dataTable value="#{clients}" var="cl">
+ <h:column>
+ <f:facet name="header">Name</f:facet>
+ #{cl.name}
+ </h:column>
+ <h:column>
+ <f:facet name="header">City</f:facet>
+ #{cl.city}
+ </h:column>
+ <h:column>
+ <f:facet name="header">Action</f:facet>
+ <s:link value="Modify Client" action="#{clientAction.modify}" rendered="#{s:hasPermission('client','modify',cl)"/>
+ <s:link value="Delete Client" action="#{clientAction.delete}" rendered="#{s:hasPermission('client','delete',cl)"/>
+ </h:column>
+ </h:dataTable>
+ ]]>
+ </programlisting>
+ </sect2>
+
+ <sect2>
+ <title>Securing your pages</title>
+ <para>
+ Page security requires that your application is using a <literal>pages.xml</literal> file, however is
+ extremely simple to configure. Simply include a <literal><restrict/></literal> element within
+ the <literal>page</literal> element. By default, if a value is not provided for the
+ <literal>restrict</literal> element, an implied permission of <literal>{viewId}:view</literal> will
+ be checked for whenever accessing that page. Otherwise the value will be evaluated as a standard
+ security expression. Here's a couple of examples:
+ </para>
+
+ <programlisting>
+ <![CDATA[
+ <page view-id="/settings.xhtml">
+ <restrict/>
+ </page>
+
+ <page view-id="/reports.xhtml">
+ <restrict>#{s:hasRole('admin')}</restrict>
+ </page>
+ ]]>
+ </programlisting>
+
+ <para>
+ In the above example, the first page has an implied permission restriction of
+ <literal>/settings.xhtml:view</literal>, while the second one checks that the user
+ is a member of the <literal>admin</literal> role.
+ </para>
+
+ </sect2>
+
+ </sect1>
+
+ <sect1>
+ <title>Authoring Security Rules</title>
+
+ <para>
+ Up to this point there has been a lot of mention of permissions, but no information about how permissions
+ are actually defined or granted. This section completes the circle, by explaining how permission
+ checks are processed, and how to implement permission checks for a Seam application.
+ </para>
+
+ <sect2>
+ <title>Permissions Overview</title>
+
+ <para>
+ Seam Security provides quite a novel method for determining user permissions.
+ </para>
+ </sect2>
</sect1>
</chapter>
More information about the jboss-cvs-commits
mailing list