[seam-commits] Seam SVN: r7321 - trunk/doc/reference/en/modules.

[seam-commits at lists.jboss.org]

Author: shane.bryzak at jboss.com
Date: 2008-01-31 03:33:54 -0500 (Thu, 31 Jan 2008)
New Revision: 7321

Modified:
   trunk/doc/reference/en/modules/security.xml
Log:
documented RunAsOperation

Modified: trunk/doc/reference/en/modules/security.xml
===================================================================
--- trunk/doc/reference/en/modules/security.xml	2008-01-31 07:43:40 UTC (rev 7320)
+++ trunk/doc/reference/en/modules/security.xml	2008-01-31 08:33:54 UTC (rev 7321)
@@ -1465,7 +1465,47 @@
     </table>
 
   </sect1>
+  
+  <sect1>
+    <title>Run As</title>
+    
+    <para>
+        Sometimes it may be necessary to perform certain operations with elevated privileges, such
+        as creating a new user account as an unauthenticated user.  Seam Security supports such a
+        mechanism via the <literal>RunAsOperation</literal> class.  This class allows either the
+        <literal>Principal</literal> or <literal>Subject</literal>, or the user's roles to be
+        overridden for a single set of operations.
+    </para>
+    
+    <para>
+      The following code example demonstrates how <literal>RunAsOperation</literal> is used, by
+      overriding its <literal>getRoles()</literal> method to specify a set of roles to masquerade
+      as for the duration of the operation.  The <literal>execute()</literal> method contains the
+      code that will be executed with the elevated privileges.
+    </para>
+    
+    <programlisting><![CDATA[    new RunAsOperation() {
+       @Override
+       public String[] getRoles() {
+          return new String[] { "admin" };
+       }
+       
+       public void execute() {
+          identityManager.createAccount(username, password);
+          identityManager.grantRole(username, "user");            
+       }         
+    }.run();]]></programlisting>
+    
+    <para>
+        In a similar way, the <literal>getPrincipal()</literal> or <literal>getSubject()</literal>
+        methods can also be overriden to specify the <literal>Principal</literal> and 
+        <literal>Subject</literal> instances to use for the duration of the operation.
+        Finally, the <literal>run()</literal> method is used to carry out the 
+        <literal>RunAsOperation</literal>.
+    </para>
 
+  </sect1>
+
   <sect1>
     <title>Extending the Identity component</title>
 
@@ -1669,6 +1709,40 @@
         Please note that this is a required parameter, and must always be specified when using the
         <literal>JPAIdentityStore</literal>.
       </para>
+      
+      <sect3>
+        <title>Password hashing</title>
+        
+        <para>
+            The <literal>JPAIdentityStore</literal> stores a salted hash of the user's password, using the username
+            as the source material for salt generation.  This guarantees that two users with the same password will
+            still have different password hashes.  The method for generating a password hash is listed here for
+            convenience - it may be useful for generating password hashes for inclusion in DML scripts, etc:
+        </para>
+        
+        <programlisting><![CDATA[
+   public String hashPassword(String password, String saltPhrase)
+   {
+      try {
+         MessageDigest md = MessageDigest.getInstance("MD5");
+         
+         md.update(saltPhrase.getBytes());
+         byte[] salt = md.digest();
+         
+         md.reset();
+         md.update(password.getBytes("UTF-8"));
+         md.update(salt);
+         
+         byte[] raw = md.digest();
+         
+         return new String(Hex.encodeHex(raw));
+     } 
+     catch (Exception e) {
+         throw new RuntimeException(e);        
+     }      
+   }         
+        ]]></programlisting>
+      </sect3>
 
     </sect2>