[jboss-cvs] jboss-seam/doc/reference/en/modules ...
Shane Bryzak
sbryzak at redhat.com
Mon Jan 14 05:34:28 EST 2008
User: sbryzak2
Date: 08/01/14 05:34:28
Modified: doc/reference/en/modules security.xml
Log:
identity management first draft
Revision Changes Path
1.89 +549 -0 jboss-seam/doc/reference/en/modules/security.xml
(In the diff below, changes in quantity of whitespace are not shown.)
Index: security.xml
===================================================================
RCS file: /cvsroot/jboss/jboss-seam/doc/reference/en/modules/security.xml,v
retrieving revision 1.88
retrieving revision 1.89
diff -u -b -r1.88 -r1.89
--- security.xml 3 Dec 2007 05:08:30 -0000 1.88
+++ security.xml 14 Jan 2008 10:34:28 -0000 1.89
@@ -1514,4 +1514,553 @@
</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</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="../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>
More information about the jboss-cvs-commits
mailing list