| package org.apache.turbine.services.security; |
| |
| |
| /* |
| * Licensed to the Apache Software Foundation (ASF) under one |
| * or more contributor license agreements. See the NOTICE file |
| * distributed with this work for additional information |
| * regarding copyright ownership. The ASF licenses this file |
| * to you under the Apache License, Version 2.0 (the |
| * "License"); you may not use this file except in compliance |
| * with the License. You may obtain a copy of the License at |
| * |
| * http://www.apache.org/licenses/LICENSE-2.0 |
| * |
| * Unless required by applicable law or agreed to in writing, |
| * software distributed under the License is distributed on an |
| * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| * KIND, either express or implied. See the License for the |
| * specific language governing permissions and limitations |
| * under the License. |
| */ |
| |
| |
| import org.apache.fulcrum.security.acl.AccessControlList; |
| import org.apache.fulcrum.security.entity.Group; |
| import org.apache.fulcrum.security.entity.Permission; |
| import org.apache.fulcrum.security.entity.Role; |
| import org.apache.fulcrum.security.util.DataBackendException; |
| import org.apache.fulcrum.security.util.EntityExistsException; |
| import org.apache.fulcrum.security.util.GroupSet; |
| import org.apache.fulcrum.security.util.PasswordMismatchException; |
| import org.apache.fulcrum.security.util.PermissionSet; |
| import org.apache.fulcrum.security.util.RoleSet; |
| import org.apache.fulcrum.security.util.UnknownEntityException; |
| import org.apache.turbine.om.security.DefaultUserImpl; |
| import org.apache.turbine.om.security.User; |
| import org.apache.turbine.services.Service; |
| import org.apache.turbine.services.security.passive.PassiveUserManager; |
| |
| /** |
| * <p> |
| * The Security Service manages Users, Groups Roles and Permissions in the |
| * system. |
| * </p> |
| * |
| * <p> |
| * The task performed by the security service include creation and removal of |
| * accounts, groups, roles, and permissions; assigning users roles in groups; |
| * assigning roles specific permissions and construction of objects |
| * representing these logical entities. |
| * </p> |
| * |
| * <p> |
| * Because of pluggable nature of the Services, it is possible to create |
| * multiple implementations of SecurityService, for example employing database |
| * and directory server as the data backend. |
| * </p> |
| * |
| * @author <a href="mailto:Rafal.Krzewski@e-point.pl">Rafal Krzewski</a> |
| * @author <a href="mailto:hps@intermeta.de">Henning P. Schmiedehausen</a> |
| * @author <a href="mailto:marco@intermeta.de">Marco Knüttel</a> |
| * @version $Id$ |
| */ |
| public interface SecurityService |
| extends Service |
| { |
| /** The name of the service */ |
| String SERVICE_NAME = "SecurityService"; |
| |
| /** |
| * the key within services's properties for user manager implementation |
| * classname (user.manager) |
| */ |
| String USER_MANAGER_KEY = "user.manager"; |
| |
| /** |
| * the default implementation of UserManager interface |
| * (org.apache.turbine.services.security.passive.PassiveUserManager) |
| */ |
| String USER_MANAGER_DEFAULT |
| = PassiveUserManager.class.getName(); |
| |
| /** |
| * the key within services's properties for user implementation |
| * classname (wrapper.class) |
| */ |
| String USER_WRAPPER_KEY = "wrapper.class"; |
| |
| /** |
| * the default implementation of {@link User} interface |
| * (org.apache.turbine.om.security.DefaultUserImpl) |
| */ |
| String USER_WRAPPER_DEFAULT |
| = DefaultUserImpl.class.getName(); |
| |
| |
| /*----------------------------------------------------------------------- |
| Management of User objects |
| -----------------------------------------------------------------------*/ |
| |
| /** |
| * Construct a blank User object. |
| * |
| * @param <U> user class |
| * @return an object implementing User interface. |
| * @throws UnknownEntityException if the object could not be instantiated. |
| */ |
| <U extends User> U getUserInstance() |
| throws UnknownEntityException; |
| |
| /** |
| * Construct a blank User object. |
| * |
| * @param <U> user class |
| * @param userName The name of the user. |
| * |
| * @return an object implementing User interface. |
| * @throws UnknownEntityException if the object could not be instantiated. |
| */ |
| <U extends User> U getUserInstance(String userName) |
| throws UnknownEntityException; |
| |
| /** |
| * Construct a blank Group object. |
| * |
| * @param <G> group class |
| * @return an object implementing Group interface. |
| * @throws UnknownEntityException if the object could not be instantiated. |
| */ |
| <G extends Group> G getGroupInstance() |
| throws UnknownEntityException; |
| |
| /** |
| * Construct a blank Group object. |
| * |
| * @param <G> group class |
| * @param groupName The name of the Group |
| * |
| * @return an object implementing Group interface. |
| * @throws UnknownEntityException if the object could not be instantiated. |
| */ |
| <G extends Group> G getGroupInstance(String groupName) |
| throws UnknownEntityException; |
| |
| /** |
| * Construct a blank Permission object. |
| * |
| * @param <P> permission class |
| * @return an object implementing Permission interface. |
| * @throws UnknownEntityException if the object could not be instantiated. |
| */ |
| <P extends Permission> P getPermissionInstance() |
| throws UnknownEntityException; |
| |
| /** |
| * Construct a blank Permission object. |
| * |
| * @param <P> permission class |
| * @param permName The name of the Permission |
| * |
| * @return an object implementing Permission interface. |
| * @throws UnknownEntityException if the object could not be instantiated. |
| */ |
| <P extends Permission> P getPermissionInstance(String permName) |
| throws UnknownEntityException; |
| |
| /** |
| * Construct a blank Role object. |
| * |
| * @param <R> role class |
| * @return an object implementing Role interface. |
| * @throws UnknownEntityException if the object could not be instantiated. |
| */ |
| <R extends Role> R getRoleInstance() |
| throws UnknownEntityException; |
| |
| /** |
| * Construct a blank Role object. |
| * |
| * @param <R> role class |
| * @param roleName The name of the Role |
| * |
| * @return an object implementing Role interface. |
| * @throws UnknownEntityException if the object could not be instantiated. |
| */ |
| <R extends Role> R getRoleInstance(String roleName) |
| throws UnknownEntityException; |
| |
| /** |
| * Returns the configured UserManager. |
| * |
| * @return An UserManager object |
| */ |
| UserManager getUserManager(); |
| |
| /** |
| * Check whether a specified user's account exists. |
| * |
| * The login name is used for looking up the account. |
| * |
| * @param userName The user to be checked. |
| * @return true if the specified account exists |
| * @throws DataBackendException if there was an error accessing the data |
| * backend. |
| */ |
| boolean accountExists(String userName) |
| throws DataBackendException; |
| |
| /** |
| * Check whether a specified user's account exists. |
| * An User object is used for looking up the account. |
| * |
| * @param user The user object to be checked. |
| * @return true if the specified account exists |
| * @throws DataBackendException if there was an error accessing the data |
| * backend. |
| */ |
| boolean accountExists(User user) |
| throws DataBackendException; |
| |
| /** |
| * Authenticates an user, and constructs an User object to represent |
| * him/her. |
| * |
| * @param <U> user class |
| * @param username The user name. |
| * @param password The user password. |
| * @return An authenticated Turbine User. |
| * @throws DataBackendException if there was an error accessing the data |
| * backend. |
| * @throws UnknownEntityException if user account is not present. |
| * @throws PasswordMismatchException if the supplied password was incorrect. |
| */ |
| <U extends User> U getAuthenticatedUser(String username, String password) |
| throws DataBackendException, UnknownEntityException, |
| PasswordMismatchException; |
| |
| /** |
| * Constructs an User object to represent a registered user of the |
| * application. |
| * |
| * @param <U> user class |
| * @param username The user name. |
| * @return A Turbine User. |
| * @throws DataBackendException if there was an error accessing the data |
| * backend. |
| * @throws UnknownEntityException if user account is not present. |
| */ |
| <U extends User> U getUser(String username) |
| throws DataBackendException, UnknownEntityException; |
| |
| /** |
| * Constructs an User object to represent an anonymous user of the |
| * application. |
| * |
| * @param <U> user class |
| * @return An anonymous Turbine User. |
| * @throws UnknownEntityException if the anonymous User object couldn't be |
| * constructed. |
| */ |
| <U extends User> U getAnonymousUser() |
| throws UnknownEntityException; |
| |
| /** |
| * Checks whether a passed user object matches the anonymous user pattern |
| * according to the configured user manager |
| * |
| * @param u a user object |
| * @return True if this is an anonymous user |
| * |
| */ |
| boolean isAnonymousUser(User u); |
| |
| /** |
| * Saves User's data in the permanent storage. The user account is required |
| * to exist in the storage. |
| * |
| * @param user the user object to save |
| * @throws UnknownEntityException if the user's account does not |
| * exist in the database. |
| * @throws DataBackendException if there is a problem accessing the storage. |
| */ |
| void saveUser(User user) |
| throws UnknownEntityException, DataBackendException; |
| |
| /** |
| * Saves User data when the session is unbound. The user account is required |
| * to exist in the storage. |
| * |
| * LastLogin, AccessCounter, persistent pull tools, and any data stored |
| * in the permData hashtable that is not mapped to a column will be saved. |
| * |
| * @param user the user object |
| * |
| * @throws UnknownEntityException if the user's account does not |
| * exist in the database. |
| * @throws DataBackendException if there is a problem accessing the |
| * storage. |
| */ |
| void saveOnSessionUnbind(User user) |
| throws UnknownEntityException, DataBackendException; |
| |
| /*----------------------------------------------------------------------- |
| Account management |
| -----------------------------------------------------------------------*/ |
| |
| /** |
| * Creates new user account with specified attributes. |
| * |
| * @param user the object describing account to be created. |
| * @param password The password to use. |
| * @throws DataBackendException if there was an error accessing the data |
| * backend. |
| * @throws EntityExistsException if the user account already exists. |
| * @throws UnknownEntityException if the provided user does not exist (is null) |
| */ |
| void addUser(User user, String password) |
| throws DataBackendException, EntityExistsException, UnknownEntityException; |
| |
| /** |
| * Removes an user account from the system. |
| * |
| * @param user the object describing the account to be removed. |
| * @throws DataBackendException if there was an error accessing the data |
| * backend. |
| * @throws UnknownEntityException if the user account is not present. |
| */ |
| void removeUser(User user) |
| throws DataBackendException, UnknownEntityException; |
| |
| /*----------------------------------------------------------------------- |
| Management of passwords |
| -----------------------------------------------------------------------*/ |
| |
| /** |
| * Change the password for an User. |
| * |
| * @param user an User to change password for. |
| * @param oldPassword the current password supplied by the user. |
| * @param newPassword the current password requested by the user. |
| * @throws PasswordMismatchException if the supplied password was |
| * incorrect. |
| * @throws UnknownEntityException if the user's record does not |
| * exist in the database. |
| * @throws DataBackendException if there is a problem accessing the |
| * storage. |
| */ |
| void changePassword(User user, String oldPassword, |
| String newPassword) |
| throws PasswordMismatchException, UnknownEntityException, |
| DataBackendException; |
| |
| /** |
| * Forcibly sets new password for an User. |
| * |
| * This is supposed by the administrator to change the forgotten or |
| * compromised passwords. Certain implementatations of this feature |
| * would require administrative level access to the authenticating |
| * server / program. |
| * |
| * @param user an User to change password for. |
| * @param password the new password. |
| * @throws UnknownEntityException if the user's record does not |
| * exist in the database. |
| * @throws DataBackendException if there is a problem accessing the |
| * storage. |
| */ |
| void forcePassword(User user, String password) |
| throws UnknownEntityException, DataBackendException; |
| |
| /*----------------------------------------------------------------------- |
| Retrieval of security information |
| -----------------------------------------------------------------------*/ |
| |
| /** |
| * Constructs an AccessControlList for a specific user. |
| * |
| * @param <A> ACL class |
| * @param user the user for whom the AccessControlList are to be retrieved |
| * @return A new AccessControlList object. |
| * @throws DataBackendException if there was an error accessing the data backend. |
| * @throws UnknownEntityException if user account is not present. |
| */ |
| <A extends AccessControlList> A getACL(User user) |
| throws DataBackendException, UnknownEntityException; |
| |
| /** |
| * Retrieves all permissions associated with a role. |
| * |
| * @param role the role name, for which the permissions are to be retrieved. |
| * @return the permissions associated with the role |
| * @throws DataBackendException if there was an error accessing the data |
| * backend. |
| * @throws UnknownEntityException if the role is not present. |
| */ |
| PermissionSet getPermissions(Role role) |
| throws DataBackendException, UnknownEntityException; |
| |
| /*----------------------------------------------------------------------- |
| Manipulation of security information |
| -----------------------------------------------------------------------*/ |
| |
| /** |
| * Grant an User a Role in a Group. |
| * |
| * @param user the user. |
| * @param group the group. |
| * @param role the role. |
| * @throws DataBackendException if there was an error accessing the data |
| * backend. |
| * @throws UnknownEntityException if user account, group or role is not |
| * present. |
| */ |
| void grant(User user, Group group, Role role) |
| throws DataBackendException, UnknownEntityException; |
| |
| /** |
| * Revoke a Role in a Group from an User. |
| * |
| * @param user the user. |
| * @param group the group. |
| * @param role the role. |
| * @throws DataBackendException if there was an error accessing the data |
| * backend. |
| * @throws UnknownEntityException if user account, group or role is not |
| * present. |
| */ |
| void revoke(User user, Group group, Role role) |
| throws DataBackendException, UnknownEntityException; |
| |
| /** |
| * Revokes all roles from an User. |
| * |
| * This method is used when deleting an account. |
| * |
| * @param user the User. |
| * @throws DataBackendException if there was an error accessing the data |
| * backend. |
| * @throws UnknownEntityException if the account is not present. |
| */ |
| void revokeAll(User user) |
| throws DataBackendException, UnknownEntityException; |
| |
| /** |
| * Grants a Role a Permission |
| * |
| * @param role the Role. |
| * @param permission the Permission. |
| * @throws DataBackendException if there was an error accessing the data |
| * backend. |
| * @throws UnknownEntityException if role or permission is not present. |
| */ |
| void grant(Role role, Permission permission) |
| throws DataBackendException, UnknownEntityException; |
| |
| /** |
| * Revokes a Permission from a Role. |
| * |
| * @param role the Role. |
| * @param permission the Permission. |
| * @throws DataBackendException if there was an error accessing the data |
| * backend. |
| * @throws UnknownEntityException if role or permission is not present. |
| */ |
| void revoke(Role role, Permission permission) |
| throws DataBackendException, UnknownEntityException; |
| |
| /** |
| * Revokes all permissions from a Role. |
| * |
| * This method is user when deleting a Role. |
| * |
| * @param role the Role |
| * @throws DataBackendException if there was an error accessing the data |
| * backend. |
| * @throws UnknownEntityException if the Role is not present. |
| */ |
| void revokeAll(Role role) |
| throws DataBackendException, UnknownEntityException; |
| |
| /** |
| * Revokes by default all permissions from a Role and if flag is set |
| * all groups and users for this role |
| * |
| * This method is used when deleting a Role. |
| * |
| * @param role |
| * the Role |
| * @param cascadeDelete |
| * if <code>true </code> removes all groups and user for this role. |
| * @throws DataBackendException |
| * if there was an error accessing the data backend. |
| * @throws UnknownEntityException |
| * if the Role is not present. |
| */ |
| void revokeAll( Role role, boolean cascadeDelete ) |
| throws DataBackendException, UnknownEntityException; |
| |
| /*----------------------------------------------------------------------- |
| Retrieval & storage of SecurityObjects |
| -----------------------------------------------------------------------*/ |
| |
| /** |
| * Provides a reference to the Group object that represents the |
| * <a href="#global">global group</a>. |
| * |
| * @param <G> group class |
| * @return A Group object that represents the global group. |
| */ |
| <G extends Group> G getGlobalGroup(); |
| |
| /** |
| * Retrieve a Group object with specified name. |
| * |
| * @param <G> group class |
| * @param name the name of the Group. |
| * @return an object representing the Group with specified name. |
| * @throws DataBackendException if there was an error accessing the data |
| * backend. |
| * @throws UnknownEntityException if the group does not exist. |
| */ |
| <G extends Group> G getGroupByName(String name) |
| throws DataBackendException, UnknownEntityException; |
| |
| /** |
| * Retrieve a Group object with specified Id. |
| * |
| * @param <G> group class |
| * @param id the id of the Group. |
| * |
| * @return an object representing the Group with specified name. |
| * |
| * @throws UnknownEntityException if the permission does not |
| * exist in the database. |
| * @throws DataBackendException if there is a problem accessing the |
| * storage. |
| */ |
| <G extends Group> G getGroupById(int id) |
| throws DataBackendException, |
| UnknownEntityException; |
| |
| /** |
| * Retrieve a Role object with specified name. |
| * |
| * @param <R> role class |
| * @param name the name of the Role. |
| * @return an object representing the Role with specified name. |
| * @throws DataBackendException if there was an error accessing the data |
| * backend. |
| * @throws UnknownEntityException if the role does not exist. |
| */ |
| <R extends Role> R getRoleByName(String name) |
| throws DataBackendException, UnknownEntityException; |
| |
| /** |
| * Retrieve a Role object with specified Id. |
| * |
| * @param <R> role class |
| * @param id the id of the Role. |
| * |
| * @return an object representing the Role with specified name. |
| * |
| * @throws UnknownEntityException if the permission does not |
| * exist in the database. |
| * @throws DataBackendException if there is a problem accessing the |
| * storage. |
| */ |
| <R extends Role> R getRoleById(int id) |
| throws DataBackendException, |
| UnknownEntityException; |
| |
| /** |
| * Retrieve a Permission object with specified name. |
| * |
| * @param <P> permission class |
| * @param name the name of the Permission. |
| * @return an object representing the Permission with specified name. |
| * @throws DataBackendException if there was an error accessing the data |
| * backend. |
| * @throws UnknownEntityException if the permission does not exist. |
| */ |
| <P extends Permission> P getPermissionByName(String name) |
| throws DataBackendException, UnknownEntityException; |
| |
| /** |
| * Retrieve a Permission object with specified Id. |
| * |
| * @param <P> permission class |
| * @param id the id of the Permission. |
| * |
| * @return an object representing the Permission with specified name. |
| * |
| * @throws UnknownEntityException if the permission does not |
| * exist in the database. |
| * @throws DataBackendException if there is a problem accessing the |
| * storage. |
| */ |
| <P extends Permission> P getPermissionById(int id) |
| throws DataBackendException, |
| UnknownEntityException; |
| |
| /** |
| * Retrieves all groups defined in the system. |
| * |
| * @return the names of all groups defined in the system. |
| * @throws DataBackendException if there was an error accessing the data |
| * backend. |
| */ |
| GroupSet getAllGroups() |
| throws DataBackendException; |
| |
| /** |
| * Retrieves all roles defined in the system. |
| * |
| * @return the names of all roles defined in the system. |
| * @throws DataBackendException if there was an error accessing the data |
| * backend. |
| */ |
| RoleSet getAllRoles() |
| throws DataBackendException; |
| |
| /** |
| * Retrieves all permissions defined in the system. |
| * |
| * @return the names of all roles defined in the system. |
| * @throws DataBackendException if there was an error accessing the data |
| * backend. |
| */ |
| PermissionSet getAllPermissions() |
| throws DataBackendException; |
| |
| /*----------------------------------------------------------------------- |
| Group/Role/Permission management |
| -----------------------------------------------------------------------*/ |
| |
| /** |
| * Creates a new group with specified attributes. |
| * |
| * @param <G> group class |
| * @param group the object describing the group to be created. |
| * @return the new Group object. |
| * @throws DataBackendException if there was an error accessing the data |
| * backend. |
| * @throws EntityExistsException if the group already exists. |
| */ |
| <G extends Group> G addGroup(G group) |
| throws DataBackendException, EntityExistsException; |
| |
| /** |
| * Creates a new role with specified attributes. |
| * |
| * @param <R> role class |
| * @param role The object describing the role to be created. |
| * @return the new Role object. |
| * @throws DataBackendException if there was an error accessing the data |
| * backend. |
| * @throws EntityExistsException if the role already exists. |
| */ |
| <R extends Role> R addRole(R role) |
| throws DataBackendException, EntityExistsException; |
| |
| /** |
| * Creates a new permission with specified attributes. |
| * |
| * @param <P> permission class |
| * @param permission The object describing the permission to be created. |
| * @return the new Permission object. |
| * @throws DataBackendException if there was an error accessing the data |
| * backend. |
| * @throws EntityExistsException if the permission already exists. |
| */ |
| <P extends Permission> P addPermission(P permission) |
| throws DataBackendException, EntityExistsException; |
| |
| /** |
| * Removes a Group from the system. |
| * |
| * @param group The object describing the group to be removed. |
| * @throws DataBackendException if there was an error accessing the data |
| * backend. |
| * @throws UnknownEntityException if the group does not exist. |
| */ |
| void removeGroup(Group group) |
| throws DataBackendException, UnknownEntityException; |
| |
| /** |
| * Removes a Role from the system. |
| * |
| * @param role The object describing the role to be removed. |
| * @throws DataBackendException if there was an error accessing the data |
| * backend. |
| * @throws UnknownEntityException if the role does not exist. |
| */ |
| void removeRole(Role role) |
| throws DataBackendException, UnknownEntityException; |
| |
| /** |
| * Removes a Permission from the system. |
| * |
| * @param permission The object describing the permission to be removed. |
| * @throws DataBackendException if there was an error accessing the data |
| * backend. |
| * @throws UnknownEntityException if the permission does not exist. |
| */ |
| void removePermission(Permission permission) |
| throws DataBackendException, UnknownEntityException; |
| |
| /** |
| * Renames an existing Group. |
| * |
| * @param group The object describing the group to be renamed. |
| * @param name the new name for the group. |
| * @throws DataBackendException if there was an error accessing the data |
| * backend. |
| * @throws UnknownEntityException if the group does not exist. |
| */ |
| void renameGroup(Group group, String name) |
| throws DataBackendException, UnknownEntityException; |
| |
| /** |
| * Renames an existing Role. |
| * |
| * @param role The object describing the role to be renamed. |
| * @param name the new name for the role. |
| * @throws DataBackendException if there was an error accessing the data |
| * backend. |
| * @throws UnknownEntityException if the role does not exist. |
| */ |
| void renameRole(Role role, String name) |
| throws DataBackendException, UnknownEntityException; |
| |
| /** |
| * Renames an existing Permission. |
| * |
| * @param permission The object describing the permission to be renamed. |
| * @param name the new name for the permission. |
| * @throws DataBackendException if there was an error accessing the data |
| * backend. |
| * @throws UnknownEntityException if the permission does not exist. |
| */ |
| void renamePermission(Permission permission, String name) |
| throws DataBackendException, UnknownEntityException; |
| /** |
| * Replaces transactionally the first given role with the second role for the given user. |
| * |
| * @param user the user. |
| * @param role the old role |
| * @param newRole the new role |
| * |
| * @throws DataBackendException if there was an error accessing the data |
| * backend. |
| * @throws UnknownEntityException if the permission does not exist. |
| */ |
| void replaceRole( User user, Role role, Role newRole ) |
| throws DataBackendException, UnknownEntityException; |
| |
| } |