Author: shane.bryzak(a)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>