[jboss-cvs] jboss-seam/doc/reference/en/modules ...
Shane Bryzak
Shane_Bryzak at symantec.com
Wed Jan 17 08:46:19 EST 2007
User: sbryzak2
Date: 07/01/17 08:46:19
Modified: doc/reference/en/modules security.xml
Log:
more security documentation
Revision Changes Path
1.6 +152 -3 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.5
retrieving revision 1.6
diff -u -b -r1.5 -r1.6
--- security.xml 16 Jan 2007 13:06:20 -0000 1.5
+++ security.xml 17 Jan 2007 13:46:19 -0000 1.6
@@ -51,9 +51,9 @@
<title>Rule-based Authorization</title>
<para>
- By integrating with JBoss Rules, the security API is able to make a security decision by evaluating
+ By integrating with JBoss Rules, the security API is able to make security decisions by evaluating
a set of user-defined security rules defined at deployment time. This feature allows any security
- checks to carry out a decision-making process which can be as simple or complex as required, while
+ checks to carry out a decision-making process which can be as simple or as complex as required, while
taking into account the state of any objects asserted into the security context for the check.
</para>
</sect2>
@@ -846,14 +846,163 @@
<title>Authorization</title>
<para>
+ The authorization features of the Seam security API make it possible to restrict access to a Seam
+ component based on the roles and permissions granted to the authenticated user. Security restrictions
+ are defined using EL expressions, and configured by annotating either a Seam component method, or the component
+ class itself, with the <literal>@Restrict</literal> annotation.
+ </para>
+
+ <sect2>
+ <title>Types of authorization checks</title>
+
+ <para>
+ The Seam security API provides two types of authorization checks; role checks and permission checks. Role
+ checks are simple checks to determine if a user is a member of a specific role. They are equivalent in
+ function to the <literal>isUserInRole()</literal> method found within the servlet specification. Role checks
+ can be performed by using the <literal>s:hasRole()</literal> EL function. Here's a few examples of role checks.
+ </para>
+
+ <para>
+ This first example demonstrates how to restrict access to the Seam component <literal>secureAction</literal>
+ to all users besides those in the <literal>admin</literal> role.
+ </para>
+
+ <programlisting>
+ <![CDATA[
+ at Name("secureAction")
+ at Restrict("#{s:hasRole('admin')}")
+public class SecureAction {
+ // ...
+}
+ ]]>
+ </programlisting>
+
+ <para>
+ This example demonstrates how to restrict access to a method of a Seam component to users in the
+ <literal>superuser</literal> role.
+ </para>
+
+ <programlisting>
+ <![CDATA[
+ @Restrict("#{s:hasRole('superuser')}")
+ public void secureMethod {
+ // ...
+ }
+ ]]>
+ </programlisting>
+
+ <para>
+ This last example shows how an inline security check can be performed within the body of a method,
+ rather than using the <literal>@Restrict</literal> annotation.
+ </para>
+
+ <programlisting>
+ <![CDATA[
+ public String changeUserPassword() {
+ // code here
+ Identity.instance().checkRestriction("#{s:hasRole('superuser')}");
+ // code here
+ }
+ ]]>
+ </programlisting>
+
+
+
+
+ </sect2>
+
+ <sect2>
+ <title>The Security Context</title>
+ <para>
+ The first time that a permission check is performed after a user is authenticated, a security context is
+ created for that user and placed into the user's session context. This security context (which in
+ fact is an instance of <literal>org.drools.WorkingMemory</literal>) is populated with all of the
+ <literal>Principal</literal>s for the authenticated user, plus all of the explicitly granted
+ permissions granted to the user's role/s, as instances of<literal>org.jboss.seam.security.SeamPermission</literal>.
+ To make this a little clearer, here's a diagram:
+ </para>
+
+ <mediaobject>
+ <imageobject role="fo">
+ <imagedata fileref="images/security-context.png" align="center"/>
+ </imageobject>
+ <imageobject role="html">
+ <imagedata fileref="../shared/images/security-context.png" align="center"/>
+ </imageobject>
+ </mediaobject>
+
+ <para>
+ In this diagram, the database contains a user "bob", who is a member of the "user" role. The
+ security configuration file, <literal>security-config.xml</literal> defines a role called "user"
+ that has the explicitly assigned permissions <literal>customer:create</literal>,
+ <literal>account:create</literal> and <literal>invoice:create</literal>. After bob authenticates,
+ his Security Context will contain all of the permissions granted to him through his role
+ memberships, as well as any <literal>Principal</literal>s created as a result of the authentication
+ process. This includes his roles, which exist in a <literal>SimpleGroup</literal> principal with the
+ name of "roles".
</para>
+ </sect2>
+
+ <sect2>
+ <title>How do permission checks work?</title>
+
+ <para>
+
+ </para>
+ </sect2>
+
<sect2>
<title>Establishing a default security policy</title>
<para>
+ As mentioned previously, permissions can either be explicitly granted, or they can be granted as the
+ result of a rule-based decision. Strictly speaking though, <emphasis>all</emphasis> permissions must
+ be granted via a security rule; this includes explicit permissions also. By having all
+ permissioning under the control of the rule engine, it is easier to configure any custom security
+ requirements for your application. So what does this mean? For starters, granting explicit permissions
+ without specifying a minimal security policy will mean that any security checks for those permissions
+ will fail. What does a minimal security policy look like? Here's an example
+ <literal>security-rules.drl</literal> file with a default security policy defined:
+ </para>
+
+ <programlisting>
+ <![CDATA[
+package MyProjectPermissions;
+
+import org.jboss.seam.security.Identity;
+import org.jboss.seam.security.rules.PermissionCheck;
+import org.jboss.seam.security.SeamPermission;
+rule DefaultPolicy
+ salience -10
+ activation-group "permissions"
+when
+ c: PermissionCheck(granted == false)
+ p: SeamPermission()
+ eval( p.getName().equals(c.getName()) && p.getAction().equals(c.getAction()))
+then
+ c.grant();
+end;
+ ]]>
+ </programlisting>
+
+ <para>
+ If you're familiar with JBoss Rules then this example should make at least some sense already. In a
+ nutshell, what this rule does is "catch" any permission checks that haven't already been granted by
+ any higher priority rules, and grant the permission if a <literal>SeamPermission</literal> instance
+ having the same name and action as the <literal>PermissionCheck</literal> exists within the security
+ context.
+ </para>
+
+ <para>
+ A couple of notes about this rule; first of all, the <literal>salience -10</literal> line means that
+ this rule will have a lower priority than any other rules with a higher salience (the default
+ salience if not specified is 0). This assigns rules for any dynamic permissions (that don't have an explicit
+ <literal>SeamPermission</literal> in the security context) a higher firing priority.
+ Secondly, the <literal>activation-group</literal> value means that once the first rule within the
+ activation group fires, no other rules within the same activation group will fire.
</para>
</sect2>
More information about the jboss-cvs-commits
mailing list