Author: shane.bryzak(a)jboss.com Date: 2008-01-28 22:15:19 -0500 (Mon, 28 Jan 2008) New Revision: 7276 Removed: branches/Seam_2_0/doc/reference/en/images/security-identitymanager.png branches/Seam_2_0/doc/reference/en/images/security-useraccount.png branches/Seam_2_0/doc/reference/en/images/security-useraccountschema.png branches/Seam_2_0/doc/reference/en/images/security-usermanager1.png branches/Seam_2_0/doc/reference/en/images/security-usermanager2.png Modified: branches/Seam_2_0/doc/reference/en/modules/security.xml Log: removed identity management from 2.0.x documentation Deleted: branches/Seam_2_0/doc/reference/en/images/security-identitymanager.png =================================================================== (Binary files differ) Deleted: branches/Seam_2_0/doc/reference/en/images/security-useraccount.png =================================================================== (Binary files differ) Deleted: branches/Seam_2_0/doc/reference/en/images/security-useraccountschema.png =================================================================== (Binary files differ) Deleted: branches/Seam_2_0/doc/reference/en/images/security-usermanager1.png =================================================================== (Binary files differ) Deleted: branches/Seam_2_0/doc/reference/en/images/security-usermanager2.png =================================================================== (Binary files differ) Modified: branches/Seam_2_0/doc/reference/en/modules/security.xml =================================================================== --- branches/Seam_2_0/doc/reference/en/modules/security.xml 2008-01-29 03:11:47 UTC (rev 7275) +++ branches/Seam_2_0/doc/reference/en/modules/security.xml 2008-01-29 03:15:19 UTC (rev 7276) @@ -1514,553 +1514,5 @@ </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="../shared/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.0.xsd<...;. - 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="../shared/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="../shared/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> - - </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 the <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>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> - - </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"/> - </imageobject> - <imageobject role="html"> - <imagedata fileref="../shared/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"/> - </imageobject> - <imageobject role="html"> - <imagedata fileref="../shared/images/security-usermanager2.png" align="center"/> - </imageobject> - </mediaobject> - - - </sect2> - - </sect1> - </chapter>