Author: shane.bryzak(a)jboss.com Date: 2010-05-30 07:51:36 -0400 (Sun, 30 May 2010) New Revision: 12906 Modified: modules/security/trunk/api/src/main/java/org/jboss/seam/security/management/IdentityManager.java modules/security/trunk/impl/src/main/java/org/jboss/seam/security/management/IdentityManagerImpl.java Log: formalise IdentityManager interface Modified: modules/security/trunk/api/src/main/java/org/jboss/seam/security/management/IdentityManager.java =================================================================== --- modules/security/trunk/api/src/main/java/org/jboss/seam/security/management/IdentityManager.java 2010-05-29 03:06:00 UTC (rev 12905) +++ modules/security/trunk/api/src/main/java/org/jboss/seam/security/management/IdentityManager.java 2010-05-30 11:51:36 UTC (rev 12906) @@ -3,54 +3,186 @@ import java.util.List; import org.picketlink.idm.api.Credential; -import org.picketlink.idm.api.Group; import org.picketlink.idm.api.IdentityType; import org.picketlink.idm.api.Role; /** - * Identity Management API, deals with user name/password-based identity management. + * Identity Management API, allows management of users, groups and roles. * * @author Shane Bryzak */ public interface IdentityManager { + /** + * Creates a new user with the specified username and credential. + * + * @param username The new user's username + * @param credential The new user's credential + * @return true if the user was successfully created, false otherwise. + */ boolean createUser(String username, Credential credential); + /** + * Deletes the user with the specified username. This operation also deletes + * all of the user's credentials, relationships and attributes. + * + * @param username The username of the user to delete + * @return true if the user was successfully deleted. + */ boolean deleteUser(String username); + /** + * Updates the credentials of the user with the specified username + * + * @param username The username of the user's credential to update + * @param credential The new credential + * @return true if the credential was successfully updated + */ + boolean updateCredential(String username, Credential credential); + + /** + * Checks if the user with the specified username exists + * + * @param username The username of the user + * @return true if the user exists + */ + boolean userExists(String username); + + /** + * Checks if a user account is currently enabled + * + * @param username The username of the user account to check + * @return true if the user account is enabled + */ + boolean isUserEnabled(String username); + + /** + * Enables the user account of the specified username + * + * @param username The username of the account to enable + * @return true if the account was successfully enabled + */ boolean enableUser(String username); + /** + * Disables the user account of the specified username + * + * @param username The username of the account to disable + * @return true if the account was successfully disabled + */ boolean disableUser(String username); - boolean changePassword(String username, Credential credential); + /** + * Sets the specified attribute value for the specified user + * + * @param username The username of the user + * @param attribute The name of the attribute to set + * @param value The value of the attribute + * @return true if the attribute was successfully set + */ + boolean setUserAttribute(String username, String attribute, Object value); - boolean isUserEnabled(String username); - - boolean grantRole(String username, String roleType, Group group); - - boolean revokeRole(String username, String roleType, Group group); - + /** + * Deletes the specified attribute value from the specified user + * + * @param username The username of the user + * @param attribute The name of the attribute to delete + * @return true if the attribute was successfully deleted + */ + boolean deleteUserAttribute(String username, String attribute); + + /** + * Creates a new role type + * + * @param roleType The name of the new role type + * @return true if the role type was successfully created + */ boolean createRoleType(String roleType); + /** + * Deletes the specified role type. All granted roles of the specified + * role type are deleted also. + * + * @param roleType The name of the role type to delete + * @return true if the role type was successfully deleted + */ boolean deleteRoleType(String roleType); - - boolean userExists(String username); - boolean roleTypeExists(String roleType); + /** + * Creates a new group, with the specified name and of the specified group type + * + * @param name The name of the new group + * @param groupType The type of the new group + * @return true if the group was successfully created + */ + boolean createGroup(String name, String groupType); - boolean createGroup(Group group); + /** + * Deletes the group with the specified name and group type + * + * @param name The name of the group to delete + * @param groupType The type of the group to delete + * @return true if the group was successfully deleted + */ + boolean deleteGroup(String name, String groupType); - boolean deleteGroup(Group group); + /** + * Grants a role membership to the specified user. + * + * @param username The username of the user being granted role membership + * @param roleType The role type of the role being granted + * @param groupName The name of the group the role is being granted in + * @param groupType The type of the group + * @return true if the role was successfully granted + */ + boolean grantRole(String username, String roleType, String groupName, String groupType); - boolean addToGroup(String username, Group group); + /** + * Revokes role membership from the specified user. + * + * @param username The username of the user being revoked role membership + * @param roleType The role type of the role being revoked + * @param groupName The name of the group the role is being revoked from + * @param groupType The type of the group + * @return true if the role was successfully revoked + */ + boolean revokeRole(String username, String roleType, String groupName, String groupType); - boolean removeFromGroup(String username, Group group); + /** + * Adds a user to the specified group + * + * @param username The username of the user being added to the group + * @param groupName The name of the group the user is being added to + * @param groupType The type of the group + * @return true if the user was successfully added + */ + boolean addUserToGroup(String username, String groupName, String groupType); - List<String> findUsers(); + /** + * Removes a user from the specified group + * + * @param username The username of the user being removed + * @param groupName The name of the group the user is being removed from + * @param groupType The type of the group + * @return true if the user was successfully removed + */ + boolean removeUserFromGroup(String username, String groupName, String groupType); + /** + * Finds users that match the specified filter. A filter of null will return + * all users. + * + * @param filter The filter used to perform the search. + * @return A list of users that match the specified filter. + */ List<String> findUsers(String filter); - List<String> getRoleTypes(); + /** + * Returns a list of all the role types. + * + * @return A list of all role types + */ + List<String> listRoleTypes(); List<String> getGrantableRoles(); @@ -70,9 +202,26 @@ */ List<Role> getImpliedRoles(String name); - List<IdentityType> listRoleMembers(String roleType, Group group); + /** + * Returns a list of all members that have been granted the specified role + * + * @param roleType The role type of the role + * @param groupName The name of the group the role has been granted in + * @param groupType The type of the group + * @return A List of IdentityType objects having membership of the specified role + */ + List<IdentityType> listRoleMembers(String roleType, String groupName, String groupType); - boolean authenticate(String username, String password); + /** + * Performs an authentication check using the specified username and credential. + * This operation does not establish any kind of security context, it simply + * returns a result indicating whether authentication is successful or not. + * + * @param username The username to authenticate + * @param credential The credential to authenticate with + * @return true if authentication was successful, false otherwise. + */ + boolean authenticate(String username, Credential credential); IdentityStore getIdentityStore(); Modified: modules/security/trunk/impl/src/main/java/org/jboss/seam/security/management/IdentityManagerImpl.java =================================================================== --- modules/security/trunk/impl/src/main/java/org/jboss/seam/security/management/IdentityManagerImpl.java 2010-05-29 03:06:00 UTC (rev 12905) +++ modules/security/trunk/impl/src/main/java/org/jboss/seam/security/management/IdentityManagerImpl.java 2010-05-30 11:51:36 UTC (rev 12906) @@ -13,6 +13,7 @@ import org.jboss.seam.security.Identity; import org.jboss.seam.security.util.Strings; +import org.picketlink.idm.api.Credential; import org.picketlink.idm.api.Group; import org.picketlink.idm.api.IdentityType; import org.picketlink.idm.api.Role; @@ -68,15 +69,10 @@ } } - public boolean createUser(String name, String password) + public boolean createUser(String name, Credential credential) { - return createUser(name, password, null, null); - } - - public boolean createUser(String name, String password, String firstname, String lastname) - { identity.checkPermission(USER_PERMISSION_NAME, PERMISSION_CREATE); - return identityStore.createUser(name, password, firstname, lastname); + return identityStore.createUser(name, credential, null); } public boolean deleteUser(String name) @@ -97,10 +93,10 @@ return identityStore.disableUser(name); } - public boolean changePassword(String name, String password) + public boolean updateCredential(String name, Credential credential) { identity.checkPermission(USER_PERMISSION_NAME, PERMISSION_UPDATE); - return identityStore.changePassword(name, password); + return identityStore.updateCredential(name, credential); } public boolean isUserEnabled(String name) @@ -133,30 +129,35 @@ return roleIdentityStore.deleteRoleType(roleType); } - public boolean createGroup(String name, String groupType) + public boolean createGroup(Group group) { identity.checkPermission(GROUP_PERMISSION_NAME, PERMISSION_CREATE); - return groupIdentityStore.createGroup(name, groupType); + return groupIdentityStore.createGroup(group.getName(), group.getGroupType()); } - public boolean deleteGroup(String name, String groupType) + public boolean deleteGroup(Group group) { identity.checkPermission(GROUP_PERMISSION_NAME, PERMISSION_DELETE); - return groupIdentityStore.deleteGroup(name, groupType); + return groupIdentityStore.deleteGroup(group.getName(), group.getGroupType()); } + public boolean removeFromGroup(String username, Group group) + { + return groupIdentityStore.removeUserFromGroup(username, group); + } + public boolean userExists(String name) { identity.checkPermission(USER_PERMISSION_NAME, PERMISSION_READ); return identityStore.userExists(name); } - public boolean roleExists(String roleType) + public boolean roleTypeExists(String roleType) { return roleIdentityStore.roleTypeExists(roleType); } - public List<String> getUsers() + public List<String> findUsers() { identity.checkPermission(USER_PERMISSION_NAME, PERMISSION_READ); List<String> users = identityStore.findUsers(); @@ -170,7 +171,7 @@ return users; } - public List<String> getUsers(String filter) + public List<String> findUsers(String filter) { identity.checkPermission(USER_PERMISSION_NAME, PERMISSION_READ); List<String> users = identityStore.findUsers(filter); @@ -184,7 +185,7 @@ return users; } - public List<String> getRoles() + public List<String> getRoleTypes() { identity.checkPermission(ROLE_PERMISSION_NAME, PERMISSION_READ); List<String> roles = roleIdentityStore.listRoleTypes(); @@ -239,10 +240,10 @@ return roleIdentityStore.listRoleMembers(roleType, group); } - public boolean authenticate(String username, String password) + public boolean authenticate(String username, Credential credential) { if (Strings.isEmpty(username)) return false; - return identityStore.authenticate(username, password); + return identityStore.authenticate(username, credential); } public IdentityStore getIdentityStore()