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