[seam-commits] Seam SVN: r7875 - branches/Seam_2_0/doc/Seam_Reference_Guide/en-US.
seam-commits at lists.jboss.org
seam-commits at lists.jboss.org
Tue Apr 8 11:10:51 EDT 2008
Author: shane.bryzak at jboss.com
Date: 2008-04-08 11:10:51 -0400 (Tue, 08 Apr 2008)
New Revision: 7875
Modified:
branches/Seam_2_0/doc/Seam_Reference_Guide/en-US/Security.xml
Log:
removed section on identity management
Modified: branches/Seam_2_0/doc/Seam_Reference_Guide/en-US/Security.xml
===================================================================
--- branches/Seam_2_0/doc/Seam_Reference_Guide/en-US/Security.xml 2008-04-08 12:31:50 UTC (rev 7874)
+++ branches/Seam_2_0/doc/Seam_Reference_Guide/en-US/Security.xml 2008-04-08 15:10:51 UTC (rev 7875)
@@ -1625,846 +1625,4 @@
</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" scalefit="1"/>
- </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 role="XML"><![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 role="JAVA"><![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 role="XML"><![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 role="JAVA"><![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 role="JAVA"><![CDATA[ @In IdentityManager identityManager;]]></programlisting>
-
- <para>
- or by accessing it through its static <literal>instance()</literal> method:
- </para>
-
- <programlisting role="JAVA"><![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="3">
- <colspec colnum="1" colwidth="2*" />
- <colspec colnum="2" colwidth="1*" />
- <colspec colnum="3" 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>createAccount(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>deleteAccount(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>enableAccount(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>disableAccount(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>isEnabled(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 account. 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 account. 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>accountExists(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="3">
- <colspec colnum="1" colwidth="2*" />
- <colspec colnum="2" colwidth="2*" />
- <colspec colnum="2" colwidth="2*" />
-
- <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>createAccount()</literal>
- </para>
- </entry>
- <entry>
- <para>
- <literal>seam.account</literal>
- </para>
- </entry>
- <entry>
- <para>
- <literal>create</literal>
- </para>
- </entry>
- </row>
-
- <row>
- <entry>
- <para>
- <literal>deleteAccount()</literal>
- </para>
- </entry>
- <entry>
- <para>
- <literal>seam.account</literal>
- </para>
- </entry>
- <entry>
- <para>
- <literal>delete</literal>
- </para>
- </entry>
- </row>
-
- <row>
- <entry>
- <para>
- <literal>enableAccount()</literal>
- </para>
- </entry>
- <entry>
- <para>
- <literal>seam.account</literal>
- </para>
- </entry>
- <entry>
- <para>
- <literal>update</literal>
- </para>
- </entry>
- </row>
-
- <row>
- <entry>
- <para>
- <literal>disableAccount()</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>isEnabled()</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>accountExists()</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>
- <title>Seam-gen and Identity Management</title>
-
- <para>
- When creating a new project using seam-gen (see <xref linkend="gettingstarted"/>), by default the
- <literal>IdentityManager</literal> will be configured with a <literal>JPAIdentityStore</literal>
- and a <literal>UserAccount</literal> implementation will be generated as part of the new project.
- In addition to this, the project will include the following user management screens, allowing
- new users to be created, roles assigned, etc:
- </para>
-
- <mediaobject>
- <imageobject role="fo">
- <imagedata fileref="images/security-usermanager1.png" align="center" scalefit="1"/>
- </imageobject>
- <imageobject role="html">
- <imagedata fileref="images/security-usermanager1.png" align="center"/>
- </imageobject>
- </mediaobject>
-
- <para>
- The user detail screen:
- </para>
-
- <mediaobject>
- <imageobject role="fo">
- <imagedata fileref="images/security-usermanager2.png" align="center" scalefit="1"/>
- </imageobject>
- <imageobject role="html">
- <imagedata fileref="images/security-usermanager2.png" align="center"/>
- </imageobject>
- </mediaobject>
-
-
- </sect2>
-
- </sect1>
-
</chapter>
More information about the seam-commits
mailing list