org.apache.turbine.services.security
Interface SecurityService

All Superinterfaces:
Initable, Service
All Known Implementing Classes:
BaseSecurityService

public interface SecurityService
extends Service

The Security Service manages Users, Groups Roles and Permissions in the system. 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.

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.

Version:
$Id$
Author:
Rafal Krzewski

Field Summary
static java.lang.String SECURE_PASSWORDS_ALGORITHM_DEFAULT
          the default algorithm for password encryption (SHA)
static java.lang.String SECURE_PASSWORDS_ALGORITHM_KEY
          the key within services's properties for secure passwords algorithm (secure.passwords.algorithm)
static java.lang.String SECURE_PASSWORDS_DEFAULT
          the value of secure passwords flag (false)
static java.lang.String SECURE_PASSWORDS_KEY
          the key within services's properties for secure passwords flag (secure.passwords)
static java.lang.String SERVICE_NAME
          The name of the service
static java.lang.String USER_CLASS_DEFAULT
          the default implementation of User interface (org.apache.turbine.om.security.DBUser)
static java.lang.String USER_CLASS_KEY
          the key within services's properties for user implementation classname (user.class)
static java.lang.String USER_MANAGER_DEFAULT
          the default implementation of UserManager interface (org.apache.turbine.services.security.DBUserManager)
static java.lang.String USER_MANAGER_KEY
          the key within services's properties for user implementation classname (user.manager)
 
Method Summary
 boolean accountExists(java.lang.String username)
          Check whether a specified user's account exists.
 boolean accountExists(User user)
          Check whether a specified user's account exists.
 Group addGroup(Group group)
          Creates a new group with specified attributes.
 Permission addPermission(Permission permission)
          Creates a new permission with specified attributes.
 Role addRole(Role role)
          Creates a new role with specified attributes.
 void addUser(User user, java.lang.String password)
          Creates new user account with specified attributes.
 void changePassword(User user, java.lang.String oldPassword, java.lang.String newPassword)
          Change the password for an User.
 java.lang.String encryptPassword(java.lang.String password)
          This method provides client-side encryption mechanism for passwords.
 void forcePassword(User user, java.lang.String password)
          Forcibly sets new password for an User.
 AccessControlList getACL(User user)
          Constructs an AccessControlList for a specific user.
 GroupSet getAllGroups()
          Retrieves all groups defined in the system.
 PermissionSet getAllPermissions()
          Retrieves all permissions defined in the system.
 RoleSet getAllRoles()
          Retrieves all roles defined in the system.
 User getAnonymousUser()
          Constructs an User object to represent an anonymous user of the application.
 User getAuthenticatedUser(java.lang.String username, java.lang.String password)
          Authenticates an user, and constructs an User object to represent him/her.
 Group getGlobalGroup()
          Provides a reference to the Group object that represents the global group.
 Group getGroup(java.lang.String name)
          Retrieve a Group object with specified name.
 GroupSet getGroups(Criteria criteria)
          Retrieve a set of Groups that meet the specified Criteria.
 Group getNewGroup(java.lang.String groupName)
          Retrieves a new Group.
 Permission getNewPermission(java.lang.String permissionName)
          Retrieves a new Permission.
 Role getNewRole(java.lang.String roleName)
          Retrieves a new Role.
 Permission getPermission(java.lang.String name)
          Retrieve a Permission object with specified name.
 PermissionSet getPermissions(Criteria criteria)
          Retrieve a set of Permissions that meet the specified Criteria.
 PermissionSet getPermissions(Role role)
          Retrieves all permissions associated with a role.
 Role getRole(java.lang.String name)
          Retrieve a Role object with specified name.
 RoleSet getRoles(Criteria criteria)
          Retrieve a set of Roles that meet the specified Criteria.
 User getUser(java.lang.String username)
          Constructs an User object to represent a registered user of the application.
 java.lang.Class getUserClass()
          Returns the Class object for the implementation of User interface used by the system.
 User getUserInstance()
          Construct a blank User object.
 User[] getUsers(Criteria criteria)
          Retrieve a set of users that meet the specified criteria.
 void grant(Role role, Permission permission)
          Grants a Role a Permission
 void grant(User user, Group group, Role role)
          Grant an User a Role in a Group.
 void removeGroup(Group group)
          Removes a Group from the system.
 void removePermission(Permission permission)
          Removes a Permission from the system.
 void removeRole(Role role)
          Removes a Role from the system.
 void removeUser(User user)
          Removes an user account from the system.
 void renameGroup(Group group, java.lang.String name)
          Renames an existing Group.
 void renamePermission(Permission permission, java.lang.String name)
          Renames an existing Permission.
 void renameRole(Role role, java.lang.String name)
          Renames an existing Role.
 void revoke(Role role, Permission permission)
          Revokes a Permission from a Role.
 void revoke(User user, Group group, Role role)
          Revoke a Role in a Group from an User.
 void revokeAll(Role role)
          Revokes all permissions from a Role.
 void revokeAll(User user)
          Revokes all roles from an User.
 void saveGroup(Group group)
          Stores Group's attributes.
 void savePermission(Permission permission)
          Stores Permission's attributes.
 void saveRole(Role role)
          Stores Role's attributes.
 void saveUser(User user)
          Saves User's data in the permanent storage.
 
Methods inherited from interface org.apache.turbine.services.Service
getConfiguration, getProperties, setName, setServiceBroker
 
Methods inherited from interface org.apache.turbine.services.Initable
getInit, init, init, setInitableBroker, shutdown
 

Field Detail

SERVICE_NAME

public static final java.lang.String SERVICE_NAME
The name of the service

USER_CLASS_KEY

public static final java.lang.String USER_CLASS_KEY
the key within services's properties for user implementation classname (user.class)

USER_CLASS_DEFAULT

public static final java.lang.String USER_CLASS_DEFAULT
the default implementation of User interface (org.apache.turbine.om.security.DBUser)

USER_MANAGER_KEY

public static final java.lang.String USER_MANAGER_KEY
the key within services's properties for user implementation classname (user.manager)

USER_MANAGER_DEFAULT

public static final java.lang.String USER_MANAGER_DEFAULT
the default implementation of UserManager interface (org.apache.turbine.services.security.DBUserManager)

SECURE_PASSWORDS_KEY

public static final java.lang.String SECURE_PASSWORDS_KEY
the key within services's properties for secure passwords flag (secure.passwords)

SECURE_PASSWORDS_DEFAULT

public static final java.lang.String SECURE_PASSWORDS_DEFAULT
the value of secure passwords flag (false)

SECURE_PASSWORDS_ALGORITHM_KEY

public static final java.lang.String SECURE_PASSWORDS_ALGORITHM_KEY
the key within services's properties for secure passwords algorithm (secure.passwords.algorithm)

SECURE_PASSWORDS_ALGORITHM_DEFAULT

public static final java.lang.String SECURE_PASSWORDS_ALGORITHM_DEFAULT
the default algorithm for password encryption (SHA)
Method Detail

getUserClass

public java.lang.Class getUserClass()
                             throws UnknownEntityException
Returns the Class object for the implementation of User interface used by the system.
Returns:
the implementation of User interface used by the system.
Throws:
UnknownEntityException - if the system's implementation of User interface could not be determined.

getUserInstance

public User getUserInstance()
                     throws UnknownEntityException
Construct a blank User object. This method calls getUserClass, and then creates a new object using the default constructor.
Returns:
an object implementing User interface.
Throws:
UnknownEntityException - if the object could not be instantiated.

accountExists

public boolean accountExists(java.lang.String username)
                      throws DataBackendException
Check whether a specified user's account exists. The login name is used for looking up the account.
Parameters:
user - The user to be checked.
Returns:
true if the specified account exists
Throws:
DataBackendException - if there was an error accessing the data backend.

accountExists

public boolean accountExists(User user)
                      throws DataBackendException
Check whether a specified user's account exists. The login name is used for looking up the account.
Parameters:
usename - The name of the user to be checked.
Returns:
true if the specified account exists
Throws:
DataBackendException - if there was an error accessing the data backend.

getAuthenticatedUser

public User getAuthenticatedUser(java.lang.String username,
                                 java.lang.String password)
                          throws DataBackendException,
                                 UnknownEntityException,
                                 PasswordMismatchException
Authenticates an user, and constructs an User object to represent him/her.
Parameters:
username - The user name.
password - The user password.
Returns:
An authenticated Turbine User.
Throws:
DataBackendException - if there was an error accessing the data backend.
UnknownEntityException - if user account is not present.
PasswordMismatchException - if the supplied password was incorrect.

getUser

public User getUser(java.lang.String username)
             throws DataBackendException,
                    UnknownEntityException
Constructs an User object to represent a registered user of the application.
Parameters:
username - The user name.
Returns:
A Turbine User.
Throws:
DataBackendException - if there was an error accessing the data backend.
UnknownEntityException - if user account is not present.

getUsers

public User[] getUsers(Criteria criteria)
                throws DataBackendException
Retrieve a set of users that meet the specified criteria. As the keys for the criteria, you should use the constants that are defined in User interface, plus the names of the custom attributes you added to your user representation in the data storage. Use verbatim names of the attributes - without table name prefix in case of DB implementation.
Parameters:
criteria - The criteria of selection.
Returns:
a List of users meeting the criteria.
Throws:
DataBackendException - if there is a problem accessing the storage.

getAnonymousUser

public User getAnonymousUser()
                      throws UnknownEntityException
Constructs an User object to represent an anonymous user of the application.
Returns:
An anonymous Turbine User.
Throws:
UnknownEntityException - if the anonymous User object couldn't be constructed.

saveUser

public void saveUser(User user)
              throws UnknownEntityException,
                     DataBackendException
Saves User's data in the permanent storage. The user account is required to exist in the storage.
Throws:
UnknownEntityException - if the user's account does not exist in the database.
DataBackendException - if there is a problem accessing the storage.

addUser

public void addUser(User user,
                    java.lang.String password)
             throws DataBackendException,
                    EntityExistsException
Creates new user account with specified attributes.
Parameters:
user - the object describing account to be created.
Throws:
DataBackendException - if there was an error accessing the data backend.
EntityExistsException - if the user account already exists.

removeUser

public void removeUser(User user)
                throws DataBackendException,
                       UnknownEntityException
Removes an user account from the system.
Parameters:
user - the object describing the account to be removed.
Throws:
DataBackendException - if there was an error accessing the data backend.
UnknownEntityException - if the user account is not present.

encryptPassword

public java.lang.String encryptPassword(java.lang.String password)
This method provides client-side encryption mechanism for passwords. This is an utility method that is used by other classes to maintain a consistent approach to encrypting password. The behavior of the method can be configured in service's properties.
Parameters:
password - the password to process
Returns:
processed password

changePassword

public void changePassword(User user,
                           java.lang.String oldPassword,
                           java.lang.String newPassword)
                    throws PasswordMismatchException,
                           UnknownEntityException,
                           DataBackendException
Change the password for an User.
Parameters:
user - an User to change password for.
oldPassword - the current password supplied by the user.
newPassword - the current password requested by the user.
Throws:
PasswordMismatchException - if the supplied password was incorrect.
UnknownEntityException - if the user's record does not exist in the database.
DataBackendException - if there is a problem accessing the storage.

forcePassword

public void forcePassword(User user,
                          java.lang.String password)
                   throws 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.
Parameters:
user - an User to change password for.
password - the new password.
Throws:
UnknownEntityException - if the user's record does not exist in the database.
DataBackendException - if there is a problem accessing the storage.

getACL

public AccessControlList getACL(User user)
                         throws DataBackendException,
                                UnknownEntityException
Constructs an AccessControlList for a specific user.
Parameters:
user - the user for whom the AccessControlList are to be retrieved
Throws:
DataBackendException - if there was an error accessing the data backend.
UnknownEntityException - if user account is not present.

getPermissions

public PermissionSet getPermissions(Role role)
                             throws DataBackendException,
                                    UnknownEntityException
Retrieves all permissions associated with a role.
Parameters:
role - the role name, for which the permissions are to be retrieved.
Throws:
DataBackendException - if there was an error accessing the data backend.
UnknownEntityException - if the role is not present.

grant

public void grant(User user,
                  Group group,
                  Role role)
           throws DataBackendException,
                  UnknownEntityException
Grant an User a Role in a Group.
Parameters:
User - the user.
Group - the group.
Role - the role.
Throws:
DataBackendException - if there was an error accessing the data backend.
UnknownEntityException - if user account, group or role is not present.

revoke

public void revoke(User user,
                   Group group,
                   Role role)
            throws DataBackendException,
                   UnknownEntityException
Revoke a Role in a Group from an User.
Parameters:
User - the user.
Group - the group.
Role - the role.
Throws:
DataBackendException - if there was an error accessing the data backend.
UnknownEntityException - if user account, group or role is not present.

revokeAll

public void revokeAll(User user)
               throws DataBackendException,
                      UnknownEntityException
Revokes all roles from an User. This method is used when deleting an account.
Parameters:
user - the User.
Throws:
DataBackendException - if there was an error accessing the data backend.
UnknownEntityException - if the account is not present.

grant

public void grant(Role role,
                  Permission permission)
           throws DataBackendException,
                  UnknownEntityException
Grants a Role a Permission
Parameters:
role - the Role.
permission - the Permission.
Throws:
DataBackendException - if there was an error accessing the data backend.
UnknownEntityException - if role or permission is not present.

revoke

public void revoke(Role role,
                   Permission permission)
            throws DataBackendException,
                   UnknownEntityException
Revokes a Permission from a Role.
Parameters:
role - the Role.
permission - the Permission.
Throws:
DataBackendException - if there was an error accessing the data backend.
UnknownEntityException - if role or permission is not present.

revokeAll

public void revokeAll(Role role)
               throws DataBackendException,
                      UnknownEntityException
Revokes all permissions from a Role. This method is user when deleting a Role.
Parameters:
role - the Role
Throws:
DataBackendException - if there was an error accessing the data backend.
UnknownEntityException - if the Role is not present.

getGlobalGroup

public Group getGlobalGroup()
Provides a reference to the Group object that represents the global group.
Returns:
a Group object that represents the global group.

getNewGroup

public Group getNewGroup(java.lang.String groupName)
Retrieves a new Group. It creates a new Group based on the Services Group implementation. It does not create a new Group in the system though. Use addGroup for that.
Parameters:
groupName - The name of the Group to be retrieved.

getNewRole

public Role getNewRole(java.lang.String roleName)
Retrieves a new Role. It creates a new Group based on the Services Role implementation. It does not create a new Role in the system though. Use addRole for that.
Parameters:
roleName - The name of the Role to be retrieved.

getNewPermission

public Permission getNewPermission(java.lang.String permissionName)
Retrieves a new Permission. It creates a new Permission based on the Services Permission implementation. It does not create a new Permission in the system though. Use addPermission for that.
Parameters:
permissionName - The name of the Permission to be retrieved.

getGroup

public Group getGroup(java.lang.String name)
               throws DataBackendException,
                      UnknownEntityException
Retrieve a Group object with specified name.
Parameters:
name - the name of the Group.
Returns:
an object representing the Group with specified name.

getRole

public Role getRole(java.lang.String name)
             throws DataBackendException,
                    UnknownEntityException
Retrieve a Role object with specified name.
Parameters:
name - the name of the Role.
Returns:
an object representing the Role with specified name.

getPermission

public Permission getPermission(java.lang.String name)
                         throws DataBackendException,
                                UnknownEntityException
Retrieve a Permission object with specified name.
Parameters:
name - the name of the Permission.
Returns:
an object representing the Permission with specified name.

getGroups

public GroupSet getGroups(Criteria criteria)
                   throws DataBackendException
Retrieve a set of Groups that meet the specified Criteria.
Parameters:
a - Criteria of Group selection.
Returns:
a set of Groups that meet the specified Criteria.

getRoles

public RoleSet getRoles(Criteria criteria)
                 throws DataBackendException
Retrieve a set of Roles that meet the specified Criteria.
Parameters:
a - Criteria of Roles selection.
Returns:
a set of Roles that meet the specified Criteria.

getPermissions

public PermissionSet getPermissions(Criteria criteria)
                             throws DataBackendException
Retrieve a set of Permissions that meet the specified Criteria.
Parameters:
a - Criteria of Permissions selection.
Returns:
a set of Permissions that meet the specified Criteria.

getAllGroups

public GroupSet getAllGroups()
                      throws DataBackendException
Retrieves all groups defined in the system.
Returns:
the names of all groups defined in the system.
Throws:
DataBackendException - if there was an error accessing the data backend.

getAllRoles

public RoleSet getAllRoles()
                    throws DataBackendException
Retrieves all roles defined in the system.
Returns:
the names of all roles defined in the system.
Throws:
DataBackendException - if there was an error accessing the data backend.

getAllPermissions

public PermissionSet getAllPermissions()
                                throws DataBackendException
Retrieves all permissions defined in the system.
Returns:
the names of all roles defined in the system.
Throws:
DataBackendException - if there was an error accessing the data backend.

saveGroup

public void saveGroup(Group group)
               throws DataBackendException,
                      UnknownEntityException
Stores Group's attributes. The Groups is required to exist in the system.
Parameters:
group - The Group to be stored.
Throws:
DataBackendException - if there was an error accessing the data backend.
UnknownEntityException - if the group does not exist.

saveRole

public void saveRole(Role role)
              throws DataBackendException,
                     UnknownEntityException
Stores Role's attributes. The Roles is required to exist in the system.
Parameters:
role - The Role to be stored.
Throws:
DataBackendException - if there was an error accessing the data backend.
UnknownEntityException - if the role does not exist.

savePermission

public void savePermission(Permission permission)
                    throws DataBackendException,
                           UnknownEntityException
Stores Permission's attributes. The Permissions is required to exist in the system.
Parameters:
permission - The Permission to be stored.
Throws:
DataBackendException - if there was an error accessing the data backend.
UnknownEntityException - if the permission does not exist.

addGroup

public Group addGroup(Group group)
               throws DataBackendException,
                      EntityExistsException
Creates a new group with specified attributes.
Parameters:
group - the object describing the group to be created.
Returns:
the new Group object.
Throws:
DataBackendException - if there was an error accessing the data backend.
EntityExistsException - if the group already exists.

addRole

public Role addRole(Role role)
             throws DataBackendException,
                    EntityExistsException
Creates a new role with specified attributes.
Parameters:
group - the objects describing the group to be created.
Returns:
the new Role object.
Throws:
DataBackendException - if there was an error accessing the data backend.
EntityExistsException - if the role already exists.

addPermission

public Permission addPermission(Permission permission)
                         throws DataBackendException,
                                EntityExistsException
Creates a new permission with specified attributes.
Parameters:
group - the objects describing the group to be created.
Returns:
the new Permission object.
Throws:
DataBackendException - if there was an error accessing the data backend.
EntityExistsException - if the permission already exists.

removeGroup

public void removeGroup(Group group)
                 throws DataBackendException,
                        UnknownEntityException
Removes a Group from the system.
Parameters:
the - object describing group to be removed.
Throws:
DataBackendException - if there was an error accessing the data backend.
UnknownEntityException - if the group does not exist.

removeRole

public void removeRole(Role role)
                throws DataBackendException,
                       UnknownEntityException
Removes a Role from the system.
Parameters:
the - object describing role to be removed.
Throws:
DataBackendException - if there was an error accessing the data backend.
UnknownEntityException - if the role does not exist.

removePermission

public void removePermission(Permission permission)
                      throws DataBackendException,
                             UnknownEntityException
Removes a Permission from the system.
Parameters:
the - object describing permission to be removed.
Throws:
DataBackendException - if there was an error accessing the data backend.
UnknownEntityException - if the permission does not exist.

renameGroup

public void renameGroup(Group group,
                        java.lang.String name)
                 throws DataBackendException,
                        UnknownEntityException
Renames an existing Group.
Parameters:
the - object describing the group to be renamed.
name - the new name for the group.
Throws:
DataBackendException - if there was an error accessing the data backend.
UnknownEntityException - if the group does not exist.

renameRole

public void renameRole(Role role,
                       java.lang.String name)
                throws DataBackendException,
                       UnknownEntityException
Renames an existing Role.
Parameters:
the - object describing the role to be renamed.
name - the new name for the role.
Throws:
DataBackendException - if there was an error accessing the data backend.
UnknownEntityException - if the role does not exist.

renamePermission

public void renamePermission(Permission permission,
                             java.lang.String name)
                      throws DataBackendException,
                             UnknownEntityException
Renames an existing Permission.
Parameters:
the - object describing the permission to be renamed.
name - the new name for the permission.
Throws:
DataBackendException - if there was an error accessing the data backend.
UnknownEntityException - if the permission does not exist.


Copyright © 1999-2001 Apache Software Foundation. All Rights Reserved.