From seam-commits at lists.jboss.org Wed Jun 25 00:20:21 2008 Content-Type: multipart/mixed; boundary="===============4273741782643672164==" MIME-Version: 1.0 From: seam-commits at lists.jboss.org To: seam-commits at lists.jboss.org Subject: [seam-commits] Seam SVN: r8413 - trunk/doc/Seam_Reference_Guide/en-US. Date: Wed, 25 Jun 2008 00:20:21 -0400 Message-ID: --===============4273741782643672164== Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable 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 =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D --- trunk/doc/Seam_Reference_Guide/en-US/Security.xml 2008-06-24 19:13:55 U= TC (rev 8412) +++ trunk/doc/Seam_Reference_Guide/en-US/Security.xml 2008-06-25 04:20:21 U= TC (rev 8413) @@ -506,6 +506,21 @@ enabling and disabling user accounts, authenticating users and listi= ng users and roles. = + + Before it may be used, the identityManager must f= irst be configured with one or more + IdentityStores. These components do the actual w= ork of interacting with the backend + security provider, whether it be a database, LDAP server, or somethi= ng else. + + + + + + + + + + = + = Configuring IdentityManager = @@ -1449,7 +1464,7 @@ = Writing your own identity store implementation allows you to authe= nticate 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 org.jboss.seam.security.management.IdentityStore interface. @@ -1473,6 +1488,766 @@ configuration required. + = + + Using IdentityManager + = + + The IdentityManager can be accessed either by i= njecting it into your Seam + component as follows: + + + + + + or by accessing it through its static instance() method: + + + + + + The following table describes IdentityManager's= API methods: + + + + Identity Management API + + + + + + + + + Method + + + Returns + + + Description + + + + + + + + + + createUser(String name, String password) + + + + + boolean + + + + + Creates a new user account, with the specified name and = password. Returns true + if successful, or false if not. + + + = + + + + + deleteUser(String name) + + + + + boolean + + + + + Deletes the user account with the specified name. Retur= ns true + if successful, or false if not. + + + + = + + + + createRole(String role) + + + + + boolean + + + + + Creates a new role, with the specified name. Returns true + if successful, or false if not. + + + = + = + + + + deleteRole(String name) + + + + + boolean + + + + + Deletes the role with the specified name. Returns true + if successful, or false if not. + + + = + + + + + enableUser(String name) + + + + + boolean + + + + + Enables the user account with the specified name. Accou= nts that are not enabled are + not able to authenticate. Returns true if successful, or + false if not. + + + + + + + + disableUser(String name) + + + + + boolean + + + + + Disables the user account with the specified name. Retu= rns true if + successful, or false if not. + + + + + + + + changePassword(String name, String password) + + + + + boolean + + + + + Changes the password for the user account with the speci= fied name. Returns + true if successful, or false= if not. + + + + + + + + isUserEnabled(String name) + + + + + boolean + + + + + Returns true if the specified user ac= count is enabled, or + false if it isn't. + + + + + + + + grantRole(String name, String role) + + + + + boolean + + + + + Grants the specified role to the specified user or role.= The role must already exist for it to + be granted. Returns true if the role= is successfully granted, or + false if it is already granted to the= user. + + + + + + + + revokeRole(String name, String role) + + + + + boolean + + + + + Revokes the specified role from the specified user or ro= le. Returns true + if the specified user is a member of the role and it is = successfully revoked, or + false if the user is not a member of = the role. + + + + + + + + userExists(String name) + + + + + boolean + + + + + Returns true if the specified user ex= ists, or false + if it doesn't. + + + + + + + + listUsers() + + + + + List + + + + + Returns a list of all user names, sorted in alpha-numeri= c order. + + + + + + + + listUsers(String filter) + + + + + List + + + + + Returns a list of all user names filtered by the specifi= ed filter parameter, sorted in alpha-numeric order. + + + + + + + + listRoles() + + + + + List + + + + + Returns a list of all role names. + + + + + + + + getGrantedRoles(String name) + + + + + List + + + + + Returns a list of the names of all the roles explicitly = granted to the specified user name. + + + + + + + + getImpliedRoles(String name) + + + + + List + + + + + 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 dire= ctly granted to a user, rather they are + granted to the roles that the user is a member of. For = example, is the admin + role is a member of the user role, an= d a user is a member of the admin + role, then the implied roles for the user are both the <= literal>admin, and user + roles. + + + + + + + + authenticate(String name, String password) + + + + + boolean + + + + + Authenticates the specified username and password using = the configured Identity Store. Returns + true if successful or false<= /literal> if authentication failed. + Successful authentication implies nothing beyond the ret= urn value of the method. It does not + change the state of the Identity comp= onent - to perform a proper Seam login the + Identity.login() must be used instead. + + + + = + + + + addRoleToGroup(String role, String group) + + + + + boolean + + + + + Adds the specified role as a member of the specified gro= up. Returns true if the operation is successful. + + + = + = + + + + removeRoleFromGroup(String role, String group)<= /literal> + + + + + boolean + + + + + Removes the specified role from the specified group. Re= turns true if the operation is successful. + + + = + = + + + + listRoles() + + + + + List + + + + + Lists the names of all roles. + + + = + + + +
+ + + Using the Identity Management API requires that the calling user h= as the appropriate authorization to invoke + its methods. The following table describes the permission require= ments for each of the methods in + IdentityManager. The permission targets listed= below are literal String values. + + + + Identity Management Security Permissions + + + + + + + + + Method + + + Permission Target + + + Permission Action + + + + + + + + + createUser() + + + + + seam.user + + + + + create + + + + + + + + deleteUser() + + + + + seam.user + + + + + delete + + + + = + + + + createRole() + + + + + seam.role + + + + + create + + + = + = + + + + deleteRole() + + + + + seam.role + + + + + delete + + + = + + + + + enableUser() + + + + + seam.user + + + + + update + + + + + + + + disableUser() + + + + + seam.user + + + + + update + + + + + + + + changePassword() + + + + + seam.user + + + + + update + + + + + + + + isUserEnabled() + + + + + seam.user + + + + + read + + + + + + + + grantRole() + + + + + seam.user + + + + + update + + + + + + + + revokeRole() + + + + + seam.user + + + + + update + + + + + + + + userExists() + + + + + seam.user + + + + + read + + + = + + + + + listUsers() + + + + + seam.user + + + + + read + + + + + + + + listRoles() + + + + + seam.role + + + + + read + + + + = + + + + addRoleToGroup() + + + + + seam.role + + + + + update + + + = + = + + + + removeRoleFromGroup() + + + + + seam.role + + + + + update + + + = + + +
+ + + The following code listing provides an example set of security rul= es that grants access to all + Identity Management-related methods to members of the adm= in role: + + + + + + = = @@ -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 @Restrict does. + = + = = = @@ -2684,883 +3461,9 @@ = = - - Identity Management = - - Seam Security provides an optional identity management API, which of= fers the following features: - - - - - - User management - the ability to create, delete and modify user = accounts and their role memberships. - - - - - Authentication of users without the need for writing an Authenti= cator component. - - - - - A hierarchical role/group membership structure, allowing roles t= o be members of other roles. - - - - - Pluggable identity store, allowing the developer to choose their= security provider, whether it be - JPA, LDAP, Kerberos, etc. - - - - - - The core of the identity management API is the IdentityMana= ger component. Before it can be - used however, it must be configured with an IdentityStore implementation. The - IdentityStore does the actual work of interacting= with the underlying security provider, - whatever it may be. - - - - - - - - - - - - - Configuration - - - Configuration of the IdentityManager is extreme= ly simple, requiring only an - IdentityStore to be configured in comp= onents.xml. - The identity management namespace is http://jboss.com/pro= ducts/seam/security/management - and its schema location is http://jboss.com/products/seam= /identity-management-2.1.xsd. - Here's a simple example showing the configuration of a JP= AIdentityStore - for the - IdentityManager to use it, it must be named identityStore: - - - - ]]> - - - - JPAIdentityStore - - - JPAIdentityStore is an IdentityStore 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 entit= y bean must extend - org.jboss.seam.security.management.UserAccount = to provide the following properties: - - - - - - - - - - - - - To provide a complete example, here's what the actual database tab= les may look like: - - - - - - - - - - - - - And an example of the corresponding entity bean: - - - memberships; - - @Id @GeneratedValue public Integer getAccountId() { return accountId; } - public void setAccountId(Integer accountId) { this.accountId =3D accoun= tId; } - - @NotNull @Override public String getUsername() { return username; } - @Override public void setUsername(String username) { this.username =3D = username; } - - @Override public String getPasswordHash() { return passwordHash; } - @Override public void setPasswordHash(String passwordHash) { this.passw= ordHash =3D passwordHash; } - - @Override public AccountType getAccountType() { return accountType; } - @Override public void setAccountType(AccountType accountType) { this.ac= countType =3D accountType; } - - @Override public boolean isEnabled() { return enabled; } - @Override public void setEnabled(boolean enabled) { this.enabled =3D en= abled; } - - @ManyToMany(targetEntity =3D MemberAccount.class) @JoinTable(name =3D "= ACCOUNT_MEMBERSHIP", - joinColumns =3D @JoinColumn(name =3D "ACCOUNT_ID"), - inverseJoinColumns =3D @JoinColumn(name =3D "MEMBER_OF")) - @Override public Set getMemberships() { return memberships= ; } - @Override public void setMemberships(Set memberships) { th= is.memberships =3D memberships; }}]]> - - - In the above example, the implementation of UserAccount is self-referencing - in that it has a many-to-many relationship with itself via its memberships - property. To keep the model simple, both user accounts and roles = are persisted as - UserAccounts, with the accountType property acting as the - discriminator between the two. With this model, roles can be memb= ers of other roles, making it - possible to define complex role membership hierarchies. - - - - Once the UserAccount implementation has been cr= eated, the JPAIdentityStore - must be configured to use that implementation any time it performs= an identity management operation. - This is done by specifying the account-class pr= operty in components.xml. - In the following example, it is configured as com.acme.Us= erAccount: - - - ]]> - - - Please note that this is a required parameter, and must always be = specified when using the - JPAIdentityStore. - - = - - Password hashing - = - - The JPAIdentityStore stores a salted hash o= f the user's password, using the username - as the source material for salt generation. This guarantees t= hat two users with the same password will - still have different password hashes. The method for generati= ng a password hash is listed here for - convenience - it may be useful for generating password hashes = for inclusion in DML scripts, etc: - - = - - - - - - - Authentication with the Identity Management API - - - To authenticate using the Identity Management API, it is as simple= as not specifying the - authenticate-method property for the I= dentity component. - If no authenticate-method is specified, then by= default the authentication - process (controlled by SeamLoginModule) will at= tempt to authenticate using - IdentityManager's authenticate() method, and no - Authenticator component is necessary. - - - - - Using the IdentityManager API - - - The IdentityManager can be accessed either by i= njecting it into your Seam - component as follows: - - - - - - or by accessing it through its static instance() method: - - - - - - The following table describes each of the methods that Id= entityManager provides: - - - - Identity Management API - - - - - - - - - Method - - - Returns - - - Description - - - - - - - - - - createUser(String name, String password) - - - - - boolean - - - - - Creates a new user account, with the specified name and = password. Returns true - if successful, or false if not. - - - = - - - - - deleteUser(String name) - - - - - boolean - - - - - Deletes the user account with the specified name. Retur= ns true - if successful, or false if not. - - - - = - - - - createRole(String role) - - - - - boolean - - - - - Creates a new role, with the specified name. Returns true - if successful, or false if not. - - - = - = - - - - deleteRole(String name) - - - - - boolean - - - - - Deletes the role with the specified name. Returns true - if successful, or false if not. - - - = - - - - - enableUser(String name) - - - - - boolean - - - - - Enables the user account with the specified name. Accou= nts that are not enabled are - not able to authenticate. Returns true if successful, or - false if not. - - - - - - - - disableUser(String name) - - - - - boolean - - - - - Disables the user account with the specified name. Retu= rns true if - successful, or false if not. - - - - - - - - changePassword(String name, String password) - - - - - boolean - - - - - Changes the password for the user account with the speci= fied name. Returns - true if successful, or false= if not. - - - - - - - - isUserEnabled(String name) - - - - - boolean - - - - - Returns true if the specified user ac= count is enabled, or - false if it isn't. - - - - - - - - grantRole(String name, String role) - - - - - boolean - - - - - Grants the specified role to the specified user or role.= The role must already exist for it to - be granted. Returns true if the role= is successfully granted, or - false if it is already granted to the= user. - - - - - - - - revokeRole(String name, String role) - - - - - boolean - - - - - Revokes the specified role from the specified user or ro= le. Returns true - if the specified user is a member of the role and it is = successfully revoked, or - false if the user is not a member of = the role. - - - - - - - - userExists(String name) - - - - - boolean - - - - - Returns true if the specified user ex= ists, or false - if it doesn't. - - - - - - - - listUsers() - - - - - List - - - - - Returns a list of all user names, sorted in alpha-numeri= c order. - - - - - - - - listUsers(String filter) - - - - - List - - - - - Returns a list of all user names filtered by the specifi= ed filter parameter, sorted in alpha-numeric order. - - - - - - - - listRoles() - - - - - List - - - - - Returns a list of all role names. - - - - - - - - getGrantedRoles(String name) - - - - - List - - - - - Returns a list of the names of all the roles explicitly = granted to the specified user name. - - - - - - - - getImpliedRoles(String name) - - - - - List - - - - - 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 dire= ctly granted to a user, rather they are - granted to the roles that the user is a member of. For = example, is the admin - role is a member of the user role, an= d a user is a member of the admin - role, then the implied roles for the user are both the <= literal>admin, and user - roles. - - - - - - - - authenticate(String name, String password) - - - - - boolean - - - - - Authenticates the specified username and password using = the configured Identity Store. Returns - true if successful or false<= /literal> if authentication failed. - Successful authentication implies nothing beyond the ret= urn value of the method. It does not - change the state of the Identity comp= onent - to perform a proper Seam login the - Identity.login() must be used instead. - - - - - - -
- - - Using the Identity Management API requires that the calling user h= as the appropriate authorization to invoke - its methods. The following table describes the permission require= ments for each of the methods in - IdentityManager. - - - - Identity Management Security Permissions - - - - - - - - - Method - - - Permission Name - - - Permission Action - - - - - - - - - createUser() - - - - - seam.account - - - - - create - - - - - - - - deleteUser() - - - - - seam.account - - - - - delete - - - - = - - - - createRole() - - - - - seam.account - - - - - create - - - = - = - - - - deleteRole() - - - - - seam.account - - - - - delete - - - = - - - - - enableUser() - - - - - seam.account - - - - - update - - - - - - - - disableUser() - - - - - seam.account - - - - - update - - - - - - - - changePassword() - - - - - seam.account - - - - - update - - - - - - - - isUserEnabled() - - - - - seam.account - - - - - read - - - - - - - - grantRole() - - - - - seam.account - - - - - update - - - - - - - - revokeRole() - - - - - seam.account - - - - - update - - - - - - - - userExists() - - - - - seam.account - - - - - read - - - = - - - - - listUsers() - - - - - seam.account - - - - - read - - - - - - -
- - - The following code listing provides an example set of security rul= es that grants access to all - Identity Management-related methods to members of the adm= in role: - - - - - - - + = + Seam-gen and Identity Management = @@ -3594,8 +3497,6 @@ = = - + = - - --===============4273741782643672164==--