[seam-commits] Seam SVN: r8413 - trunk/doc/Seam_Reference_Guide/en-US.
seam-commits at lists.jboss.org
seam-commits at lists.jboss.org
Wed Jun 25 00:20:21 EDT 2008
Author: shane.bryzak at jboss.com
Date: 2008-06-25 00:20:21 -0400 (Wed, 25 Jun 2008)
New Revision: 8413
Modified:
trunk/doc/Seam_Reference_Guide/en-US/Security.xml
Log:
more restructuring
Modified: trunk/doc/Seam_Reference_Guide/en-US/Security.xml
===================================================================
--- trunk/doc/Seam_Reference_Guide/en-US/Security.xml 2008-06-24 19:13:55 UTC (rev 8412)
+++ trunk/doc/Seam_Reference_Guide/en-US/Security.xml 2008-06-25 04:20:21 UTC (rev 8413)
@@ -506,6 +506,21 @@
enabling and disabling user accounts, authenticating users and listing users and roles.
</para>
+ <para>
+ Before it may be used, the <literal>identityManager</literal> must first be configured with one or more
+ <literal>IdentityStore</literal>s. These components do the actual work of interacting with the backend
+ security provider, whether it be a database, LDAP server, or something else.
+ </para>
+
+ <mediaobject>
+ <imageobject role="fo">
+ <imagedata fileref="images/security-identitymanager.png" align="center"/>
+ </imageobject>
+ <imageobject role="html">
+ <imagedata fileref="images/security-identitymanager.png" align="center"/>
+ </imageobject>
+ </mediaobject>
+
<sect2>
<title>Configuring IdentityManager</title>
@@ -1449,7 +1464,7 @@
<para>
Writing your own identity store implementation allows you to authenticate and perform identity management
- operations against sources that aren't supported out of the box by Seam. Only a single class is
+ operations against security providers that aren't supported out of the box by Seam. Only a single class is
required to achieve this, and it must implement the
<literal>org.jboss.seam.security.management.IdentityStore</literal> interface.
</para>
@@ -1473,6 +1488,766 @@
configuration required.
</para>
</sect2>
+
+ <sect2>
+ <title>Using IdentityManager</title>
+
+ <para>
+ The <literal>IdentityManager</literal> can be accessed either by injecting it into your Seam
+ component as follows:
+ </para>
+
+ <programlisting><![CDATA[ @In IdentityManager identityManager;]]></programlisting>
+
+ <para>
+ or by accessing it through its static <literal>instance()</literal> method:
+ </para>
+
+ <programlisting><![CDATA[ IdentityManager identityManager = IdentityManager.instance();]]></programlisting>
+
+ <para>
+ The following table describes <literal>IdentityManager</literal>'s API methods:
+ </para>
+
+ <table>
+ <title>Identity Management API</title>
+
+ <tgroup cols="2">
+ <colspec colnum="1" colwidth="1*" />
+ <colspec colnum="2" colwidth="3*" />
+
+ <thead>
+ <row>
+ <entry align="center">
+ <para>Method</para>
+ </entry>
+ <entry align="center">
+ <para>Returns</para>
+ </entry>
+ <entry align="center">
+ <para>Description</para>
+ </entry>
+ </row>
+ </thead>
+
+ <tbody>
+
+ <row>
+ <entry>
+ <para>
+ <literal>createUser(String name, String password)</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>boolean</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ Creates a new user account, with the specified name and password. Returns <literal>true</literal>
+ if successful, or <literal>false</literal> if not.
+ </para>
+ </entry>
+ </row>
+
+ <row>
+ <entry>
+ <para>
+ <literal>deleteUser(String name)</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>boolean</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ Deletes the user account with the specified name. Returns <literal>true</literal>
+ if successful, or <literal>false</literal> if not.
+ </para>
+ </entry>
+ </row>
+
+ <row>
+ <entry>
+ <para>
+ <literal>createRole(String role)</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>boolean</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ Creates a new role, with the specified name. Returns <literal>true</literal>
+ if successful, or <literal>false</literal> if not.
+ </para>
+ </entry>
+ </row>
+
+ <row>
+ <entry>
+ <para>
+ <literal>deleteRole(String name)</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>boolean</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ Deletes the role with the specified name. Returns <literal>true</literal>
+ if successful, or <literal>false</literal> if not.
+ </para>
+ </entry>
+ </row>
+
+ <row>
+ <entry>
+ <para>
+ <literal>enableUser(String name)</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>boolean</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ Enables the user account with the specified name. Accounts that are not enabled are
+ not able to authenticate. Returns <literal>true</literal> if successful, or
+ <literal>false</literal> if not.
+ </para>
+ </entry>
+ </row>
+
+ <row>
+ <entry>
+ <para>
+ <literal>disableUser(String name)</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>boolean</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ Disables the user account with the specified name. Returns <literal>true</literal> if
+ successful, or <literal>false</literal> if not.
+ </para>
+ </entry>
+ </row>
+
+ <row>
+ <entry>
+ <para>
+ <literal>changePassword(String name, String password)</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>boolean</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ Changes the password for the user account with the specified name. Returns
+ <literal>true</literal> if successful, or <literal>false</literal> if not.
+ </para>
+ </entry>
+ </row>
+
+ <row>
+ <entry>
+ <para>
+ <literal>isUserEnabled(String name)</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>boolean</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ Returns <literal>true</literal> if the specified user account is enabled, or
+ <literal>false</literal> if it isn't.
+ </para>
+ </entry>
+ </row>
+
+ <row>
+ <entry>
+ <para>
+ <literal>grantRole(String name, String role)</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>boolean</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ Grants the specified role to the specified user or role. The role must already exist for it to
+ be granted. Returns <literal>true</literal> if the role is successfully granted, or
+ <literal>false</literal> if it is already granted to the user.
+ </para>
+ </entry>
+ </row>
+
+ <row>
+ <entry>
+ <para>
+ <literal>revokeRole(String name, String role)</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>boolean</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ Revokes the specified role from the specified user or role. Returns <literal>true</literal>
+ if the specified user is a member of the role and it is successfully revoked, or
+ <literal>false</literal> if the user is not a member of the role.
+ </para>
+ </entry>
+ </row>
+
+ <row>
+ <entry>
+ <para>
+ <literal>userExists(String name)</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>boolean</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ Returns <literal>true</literal> if the specified user exists, or <literal>false</literal>
+ if it doesn't.
+ </para>
+ </entry>
+ </row>
+
+ <row>
+ <entry>
+ <para>
+ <literal>listUsers()</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>List</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ Returns a list of all user names, sorted in alpha-numeric order.
+ </para>
+ </entry>
+ </row>
+
+ <row>
+ <entry>
+ <para>
+ <literal>listUsers(String filter)</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>List</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ Returns a list of all user names filtered by the specified filter parameter, sorted in alpha-numeric order.
+ </para>
+ </entry>
+ </row>
+
+ <row>
+ <entry>
+ <para>
+ <literal>listRoles()</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>List</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ Returns a list of all role names.
+ </para>
+ </entry>
+ </row>
+
+ <row>
+ <entry>
+ <para>
+ <literal>getGrantedRoles(String name)</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>List</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ Returns a list of the names of all the roles explicitly granted to the specified user name.
+ </para>
+ </entry>
+ </row>
+
+ <row>
+ <entry>
+ <para>
+ <literal>getImpliedRoles(String name)</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>List</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ Returns a list of the names of all the roles implicitly granted to the specified user name.
+ Implicitly granted roles include those that are not directly granted to a user, rather they are
+ granted to the roles that the user is a member of. For example, is the <literal>admin</literal>
+ role is a member of the <literal>user</literal> role, and a user is a member of the <literal>admin</literal>
+ role, then the implied roles for the user are both the <literal>admin</literal>, and <literal>user</literal>
+ roles.
+ </para>
+ </entry>
+ </row>
+
+ <row>
+ <entry>
+ <para>
+ <literal>authenticate(String name, String password)</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>boolean</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ Authenticates the specified username and password using the configured Identity Store. Returns
+ <literal>true</literal> if successful or <literal>false</literal> if authentication failed.
+ Successful authentication implies nothing beyond the return value of the method. It does not
+ change the state of the <literal>Identity</literal> component - to perform a proper Seam login the
+ <literal>Identity.login()</literal> must be used instead.
+ </para>
+ </entry>
+ </row>
+
+ <row>
+ <entry>
+ <para>
+ <literal>addRoleToGroup(String role, String group)</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>boolean</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ Adds the specified role as a member of the specified group. Returns true if the operation is successful.
+ </para>
+ </entry>
+ </row>
+
+ <row>
+ <entry>
+ <para>
+ <literal>removeRoleFromGroup(String role, String group)</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>boolean</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ Removes the specified role from the specified group. Returns true if the operation is successful.
+ </para>
+ </entry>
+ </row>
+
+ <row>
+ <entry>
+ <para>
+ <literal>listRoles()</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>List</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ Lists the names of all roles.
+ </para>
+ </entry>
+ </row>
+
+ </tbody>
+ </tgroup>
+ </table>
+
+ <para>
+ Using the Identity Management API requires that the calling user has the appropriate authorization to invoke
+ its methods. The following table describes the permission requirements for each of the methods in
+ <literal>IdentityManager</literal>. The permission targets listed below are literal String values.
+ </para>
+
+ <table>
+ <title>Identity Management Security Permissions</title>
+
+ <tgroup cols="2">
+ <colspec colnum="1" colwidth="1*" />
+ <colspec colnum="2" colwidth="3*" />
+
+ <thead>
+ <row>
+ <entry align="center">
+ <para>Method</para>
+ </entry>
+ <entry align="center">
+ <para>Permission Target</para>
+ </entry>
+ <entry align="center">
+ <para>Permission Action</para>
+ </entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry>
+ <para>
+ <literal>createUser()</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>seam.user</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>create</literal>
+ </para>
+ </entry>
+ </row>
+
+ <row>
+ <entry>
+ <para>
+ <literal>deleteUser()</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>seam.user</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>delete</literal>
+ </para>
+ </entry>
+ </row>
+
+ <row>
+ <entry>
+ <para>
+ <literal>createRole()</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>seam.role</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>create</literal>
+ </para>
+ </entry>
+ </row>
+
+ <row>
+ <entry>
+ <para>
+ <literal>deleteRole()</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>seam.role</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>delete</literal>
+ </para>
+ </entry>
+ </row>
+
+ <row>
+ <entry>
+ <para>
+ <literal>enableUser()</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>seam.user</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>update</literal>
+ </para>
+ </entry>
+ </row>
+
+ <row>
+ <entry>
+ <para>
+ <literal>disableUser()</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>seam.user</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>update</literal>
+ </para>
+ </entry>
+ </row>
+
+ <row>
+ <entry>
+ <para>
+ <literal>changePassword()</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>seam.user</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>update</literal>
+ </para>
+ </entry>
+ </row>
+
+ <row>
+ <entry>
+ <para>
+ <literal>isUserEnabled()</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>seam.user</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>read</literal>
+ </para>
+ </entry>
+ </row>
+
+ <row>
+ <entry>
+ <para>
+ <literal>grantRole()</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>seam.user</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>update</literal>
+ </para>
+ </entry>
+ </row>
+
+ <row>
+ <entry>
+ <para>
+ <literal>revokeRole()</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>seam.user</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>update</literal>
+ </para>
+ </entry>
+ </row>
+
+ <row>
+ <entry>
+ <para>
+ <literal>userExists()</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>seam.user</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>read</literal>
+ </para>
+ </entry>
+ </row>
+
+ <row>
+ <entry>
+ <para>
+ <literal>listUsers()</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>seam.user</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>read</literal>
+ </para>
+ </entry>
+ </row>
+
+ <row>
+ <entry>
+ <para>
+ <literal>listRoles()</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>seam.role</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>read</literal>
+ </para>
+ </entry>
+ </row>
+
+ <row>
+ <entry>
+ <para>
+ <literal>addRoleToGroup()</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>seam.role</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>update</literal>
+ </para>
+ </entry>
+ </row>
+
+ <row>
+ <entry>
+ <para>
+ <literal>removeRoleFromGroup()</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>seam.role</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>update</literal>
+ </para>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <para>
+ The following code listing provides an example set of security rules that grants access to all
+ Identity Management-related methods to members of the <literal>admin</literal> role:
+ </para>
+
+ <programlisting><![CDATA[rule ManageUsers
+ no-loop
+ activation-group "permissions"
+when
+ check: PermissionCheck(name == "seam.user", granted == false)
+ Role(name == "admin")
+then
+ check.grant();
+end
+
+rule ManageRoles
+ no-loop
+ activation-group "permissions"
+when
+ check: PermissionCheck(name == "seam.role", granted == false)
+ Role(name == "admin")
+then
+ check.grant();
+end
+]]></programlisting>
+
+ </sect2>
+
</sect1>
<sect1>
@@ -2049,6 +2824,8 @@
the added advantage of providing compile-time safety as they don't support arbitrary EL expressions in the same way
that <literal>@Restrict</literal> does.
</para>
+
+
</sect2>
@@ -2684,883 +3461,9 @@
</sect1>
- <sect1>
- <title>Identity Management</title>
- <para>
- Seam Security provides an optional identity management API, which offers the following features:
- </para>
-
- <itemizedlist>
- <listitem>
- <para>
- User management - the ability to create, delete and modify user accounts and their role memberships.
- </para>
- </listitem>
- <listitem>
- <para>
- Authentication of users without the need for writing an Authenticator component.
- </para>
- </listitem>
- <listitem>
- <para>
- A hierarchical role/group membership structure, allowing roles to be members of other roles.
- </para>
- </listitem>
- <listitem>
- <para>
- Pluggable identity store, allowing the developer to choose their security provider, whether it be
- JPA, LDAP, Kerberos, etc.
- </para>
- </listitem>
- </itemizedlist>
-
- <para>
- The core of the identity management API is the <literal>IdentityManager</literal> component. Before it can be
- used however, it must be configured with an <literal>IdentityStore</literal> implementation. The
- <literal>IdentityStore</literal> does the actual work of interacting with the underlying security provider,
- whatever it may be.
- </para>
-
- <mediaobject>
- <imageobject role="fo">
- <imagedata fileref="images/security-identitymanager.png" align="center"/>
- </imageobject>
- <imageobject role="html">
- <imagedata fileref="images/security-identitymanager.png" align="center"/>
- </imageobject>
- </mediaobject>
-
- <sect2>
- <title>Configuration</title>
-
- <para>
- Configuration of the <literal>IdentityManager</literal> is extremely simple, requiring only an
- <literal>IdentityStore</literal> to be configured in <literal>components.xml</literal>.
- The identity management namespace is <literal>http://jboss.com/products/seam/security/management</literal>
- and its schema location is <literal>http://jboss.com/products/seam/identity-management-2.1.xsd</literal>.
- Here's a simple example showing the configuration of a <literal>JPAIdentityStore</literal> - for the
- <literal>IdentityManager</literal> to use it, it must be named <literal>identityStore</literal>:
- </para>
-
- <programlisting><![CDATA[
- <identity-management:jpa-identity-store name="identityStore" account-class="com.acme.UserAccount"/>
- ]]></programlisting>
- </sect2>
-
- <sect2>
- <title>JPAIdentityStore</title>
-
- <para>
- <literal>JPAIdentityStore</literal> is an <literal>IdentityStore</literal> implementation that uses
- JPA as its underlying security provider. User accounts and their role memberships are stored in a
- self-referencing database table, for which the corresponding entity bean must extend
- <literal>org.jboss.seam.security.management.UserAccount</literal> to provide the following properties:
- </para>
-
- <mediaobject>
- <imageobject role="fo">
- <imagedata fileref="images/security-useraccount.png" align="center"/>
- </imageobject>
- <imageobject role="html">
- <imagedata fileref="images/security-useraccount.png" align="center"/>
- </imageobject>
- </mediaobject>
-
- <para>
- To provide a complete example, here's what the actual database tables may look like:
- </para>
-
- <mediaobject>
- <imageobject role="fo">
- <imagedata fileref="images/security-useraccountschema.png" align="center"/>
- </imageobject>
- <imageobject role="html">
- <imagedata fileref="images/security-useraccountschema.png" align="center"/>
- </imageobject>
- </mediaobject>
-
- <para>
- And an example of the corresponding entity bean:
- </para>
-
- <programlisting><![CDATA[@Entity @Table(name = "USER_ACCOUNT")
-public class UserAccount extends org.jboss.seam.security.management.UserAccount
- implements Serializable
-{
- private Integer accountId;
- private String username;
- private String passwordHash;
- private boolean enabled;
- private AccountType accountType;
- private Set<UserAccount> memberships;
-
- @Id @GeneratedValue public Integer getAccountId() { return accountId; }
- public void setAccountId(Integer accountId) { this.accountId = accountId; }
-
- @NotNull @Override public String getUsername() { return username; }
- @Override public void setUsername(String username) { this.username = username; }
-
- @Override public String getPasswordHash() { return passwordHash; }
- @Override public void setPasswordHash(String passwordHash) { this.passwordHash = passwordHash; }
-
- @Override public AccountType getAccountType() { return accountType; }
- @Override public void setAccountType(AccountType accountType) { this.accountType = accountType; }
-
- @Override public boolean isEnabled() { return enabled; }
- @Override public void setEnabled(boolean enabled) { this.enabled = enabled; }
-
- @ManyToMany(targetEntity = MemberAccount.class) @JoinTable(name = "ACCOUNT_MEMBERSHIP",
- joinColumns = @JoinColumn(name = "ACCOUNT_ID"),
- inverseJoinColumns = @JoinColumn(name = "MEMBER_OF"))
- @Override public Set<UserAccount> getMemberships() { return memberships; }
- @Override public void setMemberships(Set<UserAccount> memberships) { this.memberships = memberships; }}]]></programlisting>
-
- <para>
- In the above example, the implementation of <literal>UserAccount</literal> is self-referencing
- in that it has a many-to-many relationship with itself via its <literal>memberships</literal>
- property. To keep the model simple, both user accounts and roles are persisted as
- <literal>UserAccount</literal>s, with the <literal>accountType</literal> property acting as the
- discriminator between the two. With this model, roles can be members of other roles, making it
- possible to define complex role membership hierarchies.
- </para>
-
- <para>
- Once the <literal>UserAccount</literal> implementation has been created, the <literal>JPAIdentityStore</literal>
- must be configured to use that implementation any time it performs an identity management operation.
- This is done by specifying the <literal>account-class</literal> property in <literal>components.xml</literal>.
- In the following example, it is configured as <literal>com.acme.UserAccount</literal>:
- </para>
-
- <programlisting><![CDATA[
- <identity-management:jpa-identity-store name="identityStore" account-class="com.acme.UserAccount"/>]]></programlisting>
-
- <para>
- 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>
-
- <sect2>
- <title>Authentication with the Identity Management API</title>
-
- <para>
- To authenticate using the Identity Management API, it is as simple as not specifying the
- <literal>authenticate-method</literal> property for the <literal>Identity</literal> component.
- If no <literal>authenticate-method</literal> is specified, then by default the authentication
- process (controlled by <literal>SeamLoginModule</literal>) will attempt to authenticate using
- <literal>IdentityManager</literal>'s <literal>authenticate()</literal> method, and no
- Authenticator component is necessary.
- </para>
- </sect2>
-
- <sect2>
- <title>Using the IdentityManager API</title>
-
- <para>
- The <literal>IdentityManager</literal> can be accessed either by injecting it into your Seam
- component as follows:
- </para>
-
- <programlisting><![CDATA[ @In IdentityManager identityManager;]]></programlisting>
-
- <para>
- or by accessing it through its static <literal>instance()</literal> method:
- </para>
-
- <programlisting><![CDATA[ IdentityManager identityManager = IdentityManager.instance();]]></programlisting>
-
- <para>
- The following table describes each of the methods that <literal>IdentityManager</literal> provides:
- </para>
-
- <table>
- <title>Identity Management API</title>
-
- <tgroup cols="2">
- <colspec colnum="1" colwidth="1*" />
- <colspec colnum="2" colwidth="3*" />
-
- <thead>
- <row>
- <entry align="center">
- <para>Method</para>
- </entry>
- <entry align="center">
- <para>Returns</para>
- </entry>
- <entry align="center">
- <para>Description</para>
- </entry>
- </row>
- </thead>
-
- <tbody>
-
- <row>
- <entry>
- <para>
- <literal>createUser(String name, String password)</literal>
- </para>
- </entry>
- <entry>
- <para>
- <literal>boolean</literal>
- </para>
- </entry>
- <entry>
- <para>
- Creates a new user account, with the specified name and password. Returns <literal>true</literal>
- if successful, or <literal>false</literal> if not.
- </para>
- </entry>
- </row>
-
- <row>
- <entry>
- <para>
- <literal>deleteUser(String name)</literal>
- </para>
- </entry>
- <entry>
- <para>
- <literal>boolean</literal>
- </para>
- </entry>
- <entry>
- <para>
- Deletes the user account with the specified name. Returns <literal>true</literal>
- if successful, or <literal>false</literal> if not.
- </para>
- </entry>
- </row>
-
- <row>
- <entry>
- <para>
- <literal>createRole(String role)</literal>
- </para>
- </entry>
- <entry>
- <para>
- <literal>boolean</literal>
- </para>
- </entry>
- <entry>
- <para>
- Creates a new role, with the specified name. Returns <literal>true</literal>
- if successful, or <literal>false</literal> if not.
- </para>
- </entry>
- </row>
-
- <row>
- <entry>
- <para>
- <literal>deleteRole(String name)</literal>
- </para>
- </entry>
- <entry>
- <para>
- <literal>boolean</literal>
- </para>
- </entry>
- <entry>
- <para>
- Deletes the role with the specified name. Returns <literal>true</literal>
- if successful, or <literal>false</literal> if not.
- </para>
- </entry>
- </row>
-
- <row>
- <entry>
- <para>
- <literal>enableUser(String name)</literal>
- </para>
- </entry>
- <entry>
- <para>
- <literal>boolean</literal>
- </para>
- </entry>
- <entry>
- <para>
- Enables the user account with the specified name. Accounts that are not enabled are
- not able to authenticate. Returns <literal>true</literal> if successful, or
- <literal>false</literal> if not.
- </para>
- </entry>
- </row>
-
- <row>
- <entry>
- <para>
- <literal>disableUser(String name)</literal>
- </para>
- </entry>
- <entry>
- <para>
- <literal>boolean</literal>
- </para>
- </entry>
- <entry>
- <para>
- Disables the user account with the specified name. Returns <literal>true</literal> if
- successful, or <literal>false</literal> if not.
- </para>
- </entry>
- </row>
-
- <row>
- <entry>
- <para>
- <literal>changePassword(String name, String password)</literal>
- </para>
- </entry>
- <entry>
- <para>
- <literal>boolean</literal>
- </para>
- </entry>
- <entry>
- <para>
- Changes the password for the user account with the specified name. Returns
- <literal>true</literal> if successful, or <literal>false</literal> if not.
- </para>
- </entry>
- </row>
-
- <row>
- <entry>
- <para>
- <literal>isUserEnabled(String name)</literal>
- </para>
- </entry>
- <entry>
- <para>
- <literal>boolean</literal>
- </para>
- </entry>
- <entry>
- <para>
- Returns <literal>true</literal> if the specified user account is enabled, or
- <literal>false</literal> if it isn't.
- </para>
- </entry>
- </row>
-
- <row>
- <entry>
- <para>
- <literal>grantRole(String name, String role)</literal>
- </para>
- </entry>
- <entry>
- <para>
- <literal>boolean</literal>
- </para>
- </entry>
- <entry>
- <para>
- Grants the specified role to the specified user or role. The role must already exist for it to
- be granted. Returns <literal>true</literal> if the role is successfully granted, or
- <literal>false</literal> if it is already granted to the user.
- </para>
- </entry>
- </row>
-
- <row>
- <entry>
- <para>
- <literal>revokeRole(String name, String role)</literal>
- </para>
- </entry>
- <entry>
- <para>
- <literal>boolean</literal>
- </para>
- </entry>
- <entry>
- <para>
- Revokes the specified role from the specified user or role. Returns <literal>true</literal>
- if the specified user is a member of the role and it is successfully revoked, or
- <literal>false</literal> if the user is not a member of the role.
- </para>
- </entry>
- </row>
-
- <row>
- <entry>
- <para>
- <literal>userExists(String name)</literal>
- </para>
- </entry>
- <entry>
- <para>
- <literal>boolean</literal>
- </para>
- </entry>
- <entry>
- <para>
- Returns <literal>true</literal> if the specified user exists, or <literal>false</literal>
- if it doesn't.
- </para>
- </entry>
- </row>
-
- <row>
- <entry>
- <para>
- <literal>listUsers()</literal>
- </para>
- </entry>
- <entry>
- <para>
- <literal>List</literal>
- </para>
- </entry>
- <entry>
- <para>
- Returns a list of all user names, sorted in alpha-numeric order.
- </para>
- </entry>
- </row>
-
- <row>
- <entry>
- <para>
- <literal>listUsers(String filter)</literal>
- </para>
- </entry>
- <entry>
- <para>
- <literal>List</literal>
- </para>
- </entry>
- <entry>
- <para>
- Returns a list of all user names filtered by the specified filter parameter, sorted in alpha-numeric order.
- </para>
- </entry>
- </row>
-
- <row>
- <entry>
- <para>
- <literal>listRoles()</literal>
- </para>
- </entry>
- <entry>
- <para>
- <literal>List</literal>
- </para>
- </entry>
- <entry>
- <para>
- Returns a list of all role names.
- </para>
- </entry>
- </row>
-
- <row>
- <entry>
- <para>
- <literal>getGrantedRoles(String name)</literal>
- </para>
- </entry>
- <entry>
- <para>
- <literal>List</literal>
- </para>
- </entry>
- <entry>
- <para>
- Returns a list of the names of all the roles explicitly granted to the specified user name.
- </para>
- </entry>
- </row>
-
- <row>
- <entry>
- <para>
- <literal>getImpliedRoles(String name)</literal>
- </para>
- </entry>
- <entry>
- <para>
- <literal>List</literal>
- </para>
- </entry>
- <entry>
- <para>
- Returns a list of the names of all the roles implicitly granted to the specified user name.
- Implicitly granted roles include those that are not directly granted to a user, rather they are
- granted to the roles that the user is a member of. For example, is the <literal>admin</literal>
- role is a member of the <literal>user</literal> role, and a user is a member of the <literal>admin</literal>
- role, then the implied roles for the user are both the <literal>admin</literal>, and <literal>user</literal>
- roles.
- </para>
- </entry>
- </row>
-
- <row>
- <entry>
- <para>
- <literal>authenticate(String name, String password)</literal>
- </para>
- </entry>
- <entry>
- <para>
- <literal>boolean</literal>
- </para>
- </entry>
- <entry>
- <para>
- Authenticates the specified username and password using the configured Identity Store. Returns
- <literal>true</literal> if successful or <literal>false</literal> if authentication failed.
- Successful authentication implies nothing beyond the return value of the method. It does not
- change the state of the <literal>Identity</literal> component - to perform a proper Seam login the
- <literal>Identity.login()</literal> must be used instead.
- </para>
- </entry>
- </row>
-
- </tbody>
- </tgroup>
- </table>
-
- <para>
- Using the Identity Management API requires that the calling user has the appropriate authorization to invoke
- its methods. The following table describes the permission requirements for each of the methods in
- <literal>IdentityManager</literal>.
- </para>
-
- <table>
- <title>Identity Management Security Permissions</title>
-
- <tgroup cols="2">
- <colspec colnum="1" colwidth="1*" />
- <colspec colnum="2" colwidth="3*" />
-
- <thead>
- <row>
- <entry align="center">
- <para>Method</para>
- </entry>
- <entry align="center">
- <para>Permission Name</para>
- </entry>
- <entry align="center">
- <para>Permission Action</para>
- </entry>
- </row>
- </thead>
-
- <tbody>
- <row>
- <entry>
- <para>
- <literal>createUser()</literal>
- </para>
- </entry>
- <entry>
- <para>
- <literal>seam.account</literal>
- </para>
- </entry>
- <entry>
- <para>
- <literal>create</literal>
- </para>
- </entry>
- </row>
-
- <row>
- <entry>
- <para>
- <literal>deleteUser()</literal>
- </para>
- </entry>
- <entry>
- <para>
- <literal>seam.account</literal>
- </para>
- </entry>
- <entry>
- <para>
- <literal>delete</literal>
- </para>
- </entry>
- </row>
-
- <row>
- <entry>
- <para>
- <literal>createRole()</literal>
- </para>
- </entry>
- <entry>
- <para>
- <literal>seam.account</literal>
- </para>
- </entry>
- <entry>
- <para>
- <literal>create</literal>
- </para>
- </entry>
- </row>
-
- <row>
- <entry>
- <para>
- <literal>deleteRole()</literal>
- </para>
- </entry>
- <entry>
- <para>
- <literal>seam.account</literal>
- </para>
- </entry>
- <entry>
- <para>
- <literal>delete</literal>
- </para>
- </entry>
- </row>
-
- <row>
- <entry>
- <para>
- <literal>enableUser()</literal>
- </para>
- </entry>
- <entry>
- <para>
- <literal>seam.account</literal>
- </para>
- </entry>
- <entry>
- <para>
- <literal>update</literal>
- </para>
- </entry>
- </row>
-
- <row>
- <entry>
- <para>
- <literal>disableUser()</literal>
- </para>
- </entry>
- <entry>
- <para>
- <literal>seam.account</literal>
- </para>
- </entry>
- <entry>
- <para>
- <literal>update</literal>
- </para>
- </entry>
- </row>
-
- <row>
- <entry>
- <para>
- <literal>changePassword()</literal>
- </para>
- </entry>
- <entry>
- <para>
- <literal>seam.account</literal>
- </para>
- </entry>
- <entry>
- <para>
- <literal>update</literal>
- </para>
- </entry>
- </row>
-
- <row>
- <entry>
- <para>
- <literal>isUserEnabled()</literal>
- </para>
- </entry>
- <entry>
- <para>
- <literal>seam.account</literal>
- </para>
- </entry>
- <entry>
- <para>
- <literal>read</literal>
- </para>
- </entry>
- </row>
-
- <row>
- <entry>
- <para>
- <literal>grantRole()</literal>
- </para>
- </entry>
- <entry>
- <para>
- <literal>seam.account</literal>
- </para>
- </entry>
- <entry>
- <para>
- <literal>update</literal>
- </para>
- </entry>
- </row>
-
- <row>
- <entry>
- <para>
- <literal>revokeRole()</literal>
- </para>
- </entry>
- <entry>
- <para>
- <literal>seam.account</literal>
- </para>
- </entry>
- <entry>
- <para>
- <literal>update</literal>
- </para>
- </entry>
- </row>
-
- <row>
- <entry>
- <para>
- <literal>userExists()</literal>
- </para>
- </entry>
- <entry>
- <para>
- <literal>seam.account</literal>
- </para>
- </entry>
- <entry>
- <para>
- <literal>read</literal>
- </para>
- </entry>
- </row>
-
- <row>
- <entry>
- <para>
- <literal>listUsers()</literal>
- </para>
- </entry>
- <entry>
- <para>
- <literal>seam.account</literal>
- </para>
- </entry>
- <entry>
- <para>
- <literal>read</literal>
- </para>
- </entry>
- </row>
-
- </tbody>
- </tgroup>
- </table>
-
- <para>
- The following code listing provides an example set of security rules that grants access to all
- Identity Management-related methods to members of the <literal>admin</literal> role:
- </para>
-
- <programlisting><![CDATA[rule CreateAccount
- no-loop
- activation-group "permissions"
-when
- check: PermissionCheck(name == "seam.account", action == "create", granted == false)
- Role(name == "admin")
-then
- check.grant();
-end
-
-rule ReadAccount
- no-loop
- activation-group "permissions"
-when
- check: PermissionCheck(name == "seam.account", action == "read", granted == false)
- Role(name == "admin")
-then
- check.grant();
-end
-
-rule UpdateAccount
- no-loop
- activation-group "permissions"
-when
- check: PermissionCheck(name == "seam.account", action == "update", granted == false)
- Role(name == "admin")
-then
- check.grant();
-end
-
-rule DeleteAccount
- no-loop
- activation-group "permissions"
-when
- check: PermissionCheck(name == "seam.account", action == "delete", granted == false)
- Role(name == "admin")
-then
- check.grant();
-end]]></programlisting>
-
- </sect2>
-
- <sect2>
+
+ <sect1>
<title>Seam-gen and Identity Management</title>
<para>
@@ -3594,8 +3497,6 @@
</mediaobject>
- </sect2>
+ </sect1>
- </sect1>
-
</chapter>
More information about the seam-commits
mailing list