View Javadoc

    1   package org.apache.turbine.services.security;
    2
    3
    4   /*
    5    * Licensed to the Apache Software Foundation (ASF) under one
    6    * or more contributor license agreements.  See the NOTICE file
    7    * distributed with this work for additional information
    8    * regarding copyright ownership.  The ASF licenses this file
    9    * to you under the Apache License, Version 2.0 (the
    10   * "License"); you may not use this file except in compliance
    11   * with the License.  You may obtain a copy of the License at
    12   *
    13   *   http://www.apache.org/licenses/LICENSE-2.0
    14   *
    15   * Unless required by applicable law or agreed to in writing,
    16   * software distributed under the License is distributed on an
    17   * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
    18   * KIND, either express or implied.  See the License for the
    19   * specific language governing permissions and limitations
    20   * under the License.
    21   */
    22
    23
    24  import org.apache.fulcrum.security.acl.AccessControlList;
    25  import org.apache.fulcrum.security.entity.Group;
    26  import org.apache.fulcrum.security.entity.Permission;
    27  import org.apache.fulcrum.security.entity.Role;
    28  import org.apache.fulcrum.security.util.DataBackendException;
    29  import org.apache.fulcrum.security.util.EntityExistsException;
    30  import org.apache.fulcrum.security.util.GroupSet;
    31  import org.apache.fulcrum.security.util.PasswordMismatchException;
    32  import org.apache.fulcrum.security.util.PermissionSet;
    33  import org.apache.fulcrum.security.util.RoleSet;
    34  import org.apache.fulcrum.security.util.UnknownEntityException;
    35  import org.apache.turbine.om.security.User;
    36  import org.apache.turbine.services.Service;
    37  import org.apache.turbine.services.security.passive.PassiveUserManager;
    38
    39  /**
    40   * The Security Service manages Users, Groups Roles and Permissions in the
    41   * system.
    42   *
    43   * The task performed by the security service include creation and removal of
    44   * accounts, groups, roles, and permissions; assigning users roles in groups;
    45   * assigning roles specific permissions and construction of objects
    46   * representing these logical entities.
    47   *
    48   * <p> Because of pluggable nature of the Services, it is possible to create
    49   * multiple implementations of SecurityService, for example employing database
    50   * and directory server as the data backend.<br>
    51   *
    52   * @author <a href="mailto:Rafal.Krzewski@e-point.pl">Rafal Krzewski</a>
    53   * @author <a href="mailto:hps@intermeta.de">Henning P. Schmiedehausen</a>
    54   * @author <a href="mailto:marco@intermeta.de">Marco Kn&uuml;ttel</a>
    55   * @version $Id: SecurityService.java 1706239 2015-10-01 13:18:35Z tv $
    56   */
    57  public interface SecurityService
    58          extends Service
    59  {
    60      /** The name of the service */
    61      String SERVICE_NAME = "SecurityService";
    62
    63      /**
    64       * the key within services's properties for user implementation
    65       * classname (user.manager)
    66       */
    67      String USER_MANAGER_KEY = "user.manager";
    68
    69      /**
    70       * the default implementation of UserManager interface
    71       * (org.apache.turbine.services.security.passive.PassiveUserManager)
    72       */
    73      String USER_MANAGER_DEFAULT
    74              = PassiveUserManager.class.getName();
    75
    76      /*-----------------------------------------------------------------------
    77        Management of User objects
    78        -----------------------------------------------------------------------*/
    79
    80      /**
    81       * Construct a blank User object.
    82       *
    83       * @return an object implementing User interface.
    84       * @throws UnknownEntityException if the object could not be instantiated.
    85       */
    86      <U extends User> U getUserInstance()
    87              throws UnknownEntityException;
    88
    89      /**
    90       * Construct a blank User object.
    91       *
    92       * @param userName The name of the user.
    93       *
    94       * @return an object implementing User interface.
    95       * @throws UnknownEntityException if the object could not be instantiated.
    96       */
    97      <U extends User> U getUserInstance(String userName)
    98              throws UnknownEntityException;
    99
    100     /**
    101      * Construct a blank Group object.
    102      *
    103      * @return an object implementing Group interface.
    104      * @throws UnknownEntityException if the object could not be instantiated.
    105      */
    106     <G extends Group> G getGroupInstance()
    107             throws UnknownEntityException;
    108
    109     /**
    110      * Construct a blank Group object.
    111      *
    112      * @param groupName The name of the Group
    113      *
    114      * @return an object implementing Group interface.
    115      * @throws UnknownEntityException if the object could not be instantiated.
    116      */
    117     <G extends Group> G getGroupInstance(String groupName)
    118             throws UnknownEntityException;
    119
    120     /**
    121      * Construct a blank Permission object.
    122      *
    123      * @return an object implementing Permission interface.
    124      * @throws UnknownEntityException if the object could not be instantiated.
    125      */
    126     <P extends Permission> P getPermissionInstance()
    127             throws UnknownEntityException;
    128
    129     /**
    130      * Construct a blank Permission object.
    131      *
    132      * @param permName The name of the Permission
    133      *
    134      * @return an object implementing Permission interface.
    135      * @throws UnknownEntityException if the object could not be instantiated.
    136      */
    137     <P extends Permission> P getPermissionInstance(String permName)
    138             throws UnknownEntityException;
    139
    140     /**
    141      * Construct a blank Role object.
    142      *
    143      * @return an object implementing Role interface.
    144      * @throws UnknownEntityException if the object could not be instantiated.
    145      */
    146     <R extends Role> R getRoleInstance()
    147             throws UnknownEntityException;
    148
    149     /**
    150      * Construct a blank Role object.
    151      *
    152      * @param roleName The name of the Role
    153      *
    154      * @return an object implementing Role interface.
    155      * @throws UnknownEntityException if the object could not be instantiated.
    156      */
    157     <R extends Role> R getRoleInstance(String roleName)
    158             throws UnknownEntityException;
    159
    160     /**
    161      * Returns the configured UserManager.
    162      *
    163      * @return An UserManager object
    164      */
    165     UserManager getUserManager();
    166
    167     /**
    168      * Check whether a specified user's account exists.
    169      *
    170      * The login name is used for looking up the account.
    171      *
    172      * @param userName The user to be checked.
    173      * @return true if the specified account exists
    174      * @throws DataBackendException if there was an error accessing the data
    175      *         backend.
    176      */
    177     boolean accountExists(String userName)
    178             throws DataBackendException;
    179
    180     /**
    181      * Check whether a specified user's account exists.
    182      * An User object is used for looking up the account.
    183      *
    184      * @param user The user object to be checked.
    185      * @return true if the specified account exists
    186      * @throws DataBackendException if there was an error accessing the data
    187      *         backend.
    188      */
    189     boolean accountExists(User user)
    190             throws DataBackendException;
    191
    192     /**
    193      * Authenticates an user, and constructs an User object to represent
    194      * him/her.
    195      *
    196      * @param username The user name.
    197      * @param password The user password.
    198      * @return An authenticated Turbine User.
    199      * @throws DataBackendException if there was an error accessing the data
    200      *         backend.
    201      * @throws UnknownEntityException if user account is not present.
    202      * @throws PasswordMismatchException if the supplied password was incorrect.
    203      */
    204     <U extends User> U getAuthenticatedUser(String username, String password)
    205             throws DataBackendException, UnknownEntityException,
    206             PasswordMismatchException;
    207
    208     /**
    209      * Constructs an User object to represent a registered user of the
    210      * application.
    211      *
    212      * @param username The user name.
    213      * @return A Turbine User.
    214      * @throws DataBackendException if there was an error accessing the data
    215      *         backend.
    216      * @throws UnknownEntityException if user account is not present.
    217      */
    218     <U extends User> U getUser(String username)
    219             throws DataBackendException, UnknownEntityException;
    220
    221     /**
    222      * Constructs an User object to represent an anonymous user of the
    223      * application.
    224      *
    225      * @return An anonymous Turbine User.
    226      * @throws UnknownEntityException if the anonymous User object couldn't be
    227      *         constructed.
    228      */
    229     <U extends User> U getAnonymousUser()
    230             throws UnknownEntityException;
    231
    232     /**
    233      * Checks whether a passed user object matches the anonymous user pattern
    234      * according to the configured user manager
    235      *
    236      * @param u a user object
    237      *
    238      * @return True if this is an anonymous user
    239      *
    240      */
    241     boolean isAnonymousUser(User u);
    242
    243     /**
    244      * Saves User's data in the permanent storage. The user account is required
    245      * to exist in the storage.
    246      *
    247      * @param user the user object to save
    248      * @throws UnknownEntityException if the user's account does not
    249      *         exist in the database.
    250      * @throws DataBackendException if there is a problem accessing the storage.
    251      */
    252     void saveUser(User user)
    253             throws UnknownEntityException, DataBackendException;
    254
    255     /**
    256      * Saves User data when the session is unbound. The user account is required
    257      * to exist in the storage.
    258      *
    259      * LastLogin, AccessCounter, persistent pull tools, and any data stored
    260      * in the permData hashtable that is not mapped to a column will be saved.
    261      *
    262      * @param user the user object
    263      *
    264      * @exception UnknownEntityException if the user's account does not
    265      *            exist in the database.
    266      * @exception DataBackendException if there is a problem accessing the
    267      *            storage.
    268      */
    269     void saveOnSessionUnbind(User user)
    270             throws UnknownEntityException, DataBackendException;
    271
    272     /*-----------------------------------------------------------------------
    273       Account management
    274       -----------------------------------------------------------------------*/
    275
    276     /**
    277      * Creates new user account with specified attributes.
    278      *
    279      * @param user the object describing account to be created.
    280      * @param password The password to use.
    281      * @throws DataBackendException if there was an error accessing the data
    282      *         backend.
    283      * @throws EntityExistsException if the user account already exists.
    284      */
    285     void addUser(User user, String password)
    286             throws DataBackendException, EntityExistsException;
    287
    288     /**
    289      * Removes an user account from the system.
    290      *
    291      * @param user the object describing the account to be removed.
    292      * @throws DataBackendException if there was an error accessing the data
    293      *         backend.
    294      * @throws UnknownEntityException if the user account is not present.
    295      */
    296     void removeUser(User user)
    297             throws DataBackendException, UnknownEntityException;
    298
    299     /*-----------------------------------------------------------------------
    300       Management of passwords
    301       -----------------------------------------------------------------------*/
    302
    303     /**
    304      * Change the password for an User.
    305      *
    306      * @param user an User to change password for.
    307      * @param oldPassword the current password supplied by the user.
    308      * @param newPassword the current password requested by the user.
    309      * @exception PasswordMismatchException if the supplied password was
    310      *            incorrect.
    311      * @exception UnknownEntityException if the user's record does not
    312      *            exist in the database.
    313      * @exception DataBackendException if there is a problem accessing the
    314      *            storage.
    315      */
    316     void changePassword(User user, String oldPassword,
    317                         String newPassword)
    318             throws PasswordMismatchException, UnknownEntityException,
    319             DataBackendException;
    320
    321     /**
    322      * Forcibly sets new password for an User.
    323      *
    324      * This is supposed by the administrator to change the forgotten or
    325      * compromised passwords. Certain implementatations of this feature
    326      * would require administrative level access to the authenticating
    327      * server / program.
    328      *
    329      * @param user an User to change password for.
    330      * @param password the new password.
    331      * @exception UnknownEntityException if the user's record does not
    332      *            exist in the database.
    333      * @exception DataBackendException if there is a problem accessing the
    334      *            storage.
    335      */
    336     void forcePassword(User user, String password)
    337             throws UnknownEntityException, DataBackendException;
    338
    339     /*-----------------------------------------------------------------------
    340       Retrieval of security information
    341       -----------------------------------------------------------------------*/
    342
    343     /**
    344      * Constructs an AccessControlList for a specific user.
    345      *
    346      * @param user the user for whom the AccessControlList are to be retrieved
    347      * @return A new AccessControlList object.
    348      * @throws DataBackendException if there was an error accessing the data backend.
    349      * @throws UnknownEntityException if user account is not present.
    350      */
    351     <A extends AccessControlList> A getACL(User user)
    352             throws DataBackendException, UnknownEntityException;
    353
    354     /**
    355      * Retrieves all permissions associated with a role.
    356      *
    357      * @param role the role name, for which the permissions are to be retrieved.
    358      * @return the permissions associated with the role
    359      * @throws DataBackendException if there was an error accessing the data
    360      *         backend.
    361      * @throws UnknownEntityException if the role is not present.
    362      */
    363     PermissionSet getPermissions(Role role)
    364             throws DataBackendException, UnknownEntityException;
    365
    366     /*-----------------------------------------------------------------------
    367       Manipulation of security information
    368       -----------------------------------------------------------------------*/
    369
    370     /**
    371      * Grant an User a Role in a Group.
    372      *
    373      * @param user the user.
    374      * @param group the group.
    375      * @param role the role.
    376      * @throws DataBackendException if there was an error accessing the data
    377      *         backend.
    378      * @throws UnknownEntityException if user account, group or role is not
    379      *         present.
    380      */
    381     void grant(User user, Group group, Role role)
    382             throws DataBackendException, UnknownEntityException;
    383
    384     /**
    385      * Revoke a Role in a Group from an User.
    386      *
    387      * @param user the user.
    388      * @param group the group.
    389      * @param role the role.
    390      * @throws DataBackendException if there was an error accessing the data
    391      *         backend.
    392      * @throws UnknownEntityException if user account, group or role is not
    393      *         present.
    394      */
    395     void revoke(User user, Group group, Role role)
    396             throws DataBackendException, UnknownEntityException;
    397
    398     /**
    399      * Revokes all roles from an User.
    400      *
    401      * This method is used when deleting an account.
    402      *
    403      * @param user the User.
    404      * @throws DataBackendException if there was an error accessing the data
    405      *         backend.
    406      * @throws UnknownEntityException if the account is not present.
    407      */
    408     void revokeAll(User user)
    409             throws DataBackendException, UnknownEntityException;
    410
    411     /**
    412      * Grants a Role a Permission
    413      *
    414      * @param role the Role.
    415      * @param permission the Permission.
    416      * @throws DataBackendException if there was an error accessing the data
    417      *         backend.
    418      * @throws UnknownEntityException if role or permission is not present.
    419      */
    420     void grant(Role role, Permission permission)
    421             throws DataBackendException, UnknownEntityException;
    422
    423     /**
    424      * Revokes a Permission from a Role.
    425      *
    426      * @param role the Role.
    427      * @param permission the Permission.
    428      * @throws DataBackendException if there was an error accessing the data
    429      *         backend.
    430      * @throws UnknownEntityException if role or permission is not present.
    431      */
    432     void revoke(Role role, Permission permission)
    433             throws DataBackendException, UnknownEntityException;
    434
    435     /**
    436      * Revokes all permissions from a Role.
    437      *
    438      * This method is user when deleting a Role.
    439      *
    440      * @param role the Role
    441      * @throws DataBackendException if there was an error accessing the data
    442      *         backend.
    443      * @throws  UnknownEntityException if the Role is not present.
    444      */
    445     void revokeAll(Role role)
    446             throws DataBackendException, UnknownEntityException;
    447
    448     /*-----------------------------------------------------------------------
    449       Retrieval & storage of SecurityObjects
    450       -----------------------------------------------------------------------*/
    451
    452     /**
    453      * Provides a reference to the Group object that represents the
    454      * <a href="#global">global group</a>.
    455      *
    456      * @return A Group object that represents the global group.
    457      */
    458     <G extends Group> G getGlobalGroup();
    459
    460     /**
    461      * Retrieve a Group object with specified name.
    462      *
    463      * @param name the name of the Group.
    464      * @return an object representing the Group with specified name.
    465      * @throws DataBackendException if there was an error accessing the data
    466      *         backend.
    467      * @throws UnknownEntityException if the group does not exist.
    468      */
    469     <G extends Group> G getGroupByName(String name)
    470             throws DataBackendException, UnknownEntityException;
    471
    472     /**
    473      * Retrieve a Group object with specified Id.
    474      *
    475      * @param id the id of the Group.
    476      *
    477      * @return an object representing the Group with specified name.
    478      *
    479      * @exception UnknownEntityException if the permission does not
    480      *            exist in the database.
    481      * @exception DataBackendException if there is a problem accessing the
    482      *            storage.
    483      */
    484     <G extends Group> G getGroupById(int id)
    485             throws DataBackendException,
    486                    UnknownEntityException;
    487
    488     /**
    489      * Retrieve a Role object with specified name.
    490      *
    491      * @param name the name of the Role.
    492      * @return an object representing the Role with specified name.
    493      * @throws DataBackendException if there was an error accessing the data
    494      *         backend.
    495      * @throws UnknownEntityException if the role does not exist.
    496      */
    497     <R extends Role> R getRoleByName(String name)
    498             throws DataBackendException, UnknownEntityException;
    499
    500     /**
    501      * Retrieve a Role object with specified Id.
    502      *
    503      * @param id the id of the Role.
    504      *
    505      * @return an object representing the Role with specified name.
    506      *
    507      * @exception UnknownEntityException if the permission does not
    508      *            exist in the database.
    509      * @exception DataBackendException if there is a problem accessing the
    510      *            storage.
    511      */
    512     <R extends Role> R getRoleById(int id)
    513             throws DataBackendException,
    514                    UnknownEntityException;
    515
    516     /**
    517      * Retrieve a Permission object with specified name.
    518      *
    519      * @param name the name of the Permission.
    520      * @return an object representing the Permission with specified name.
    521      * @throws DataBackendException if there was an error accessing the data
    522      *         backend.
    523      * @throws UnknownEntityException if the permission does not exist.
    524      */
    525     <P extends Permission> P getPermissionByName(String name)
    526             throws DataBackendException, UnknownEntityException;
    527
    528     /**
    529      * Retrieve a Permission object with specified Id.
    530      *
    531      * @param id the id of the Permission.
    532      *
    533      * @return an object representing the Permission with specified name.
    534      *
    535      * @exception UnknownEntityException if the permission does not
    536      *            exist in the database.
    537      * @exception DataBackendException if there is a problem accessing the
    538      *            storage.
    539      */
    540     <P extends Permission> P getPermissionById(int id)
    541             throws DataBackendException,
    542                    UnknownEntityException;
    543
    544     /**
    545      * Retrieves all groups defined in the system.
    546      *
    547      * @return the names of all groups defined in the system.
    548      * @throws DataBackendException if there was an error accessing the data
    549      *         backend.
    550      */
    551     GroupSet getAllGroups()
    552             throws DataBackendException;
    553
    554     /**
    555      * Retrieves all roles defined in the system.
    556      *
    557      * @return the names of all roles defined in the system.
    558      * @throws DataBackendException if there was an error accessing the data
    559      *         backend.
    560      */
    561     RoleSet getAllRoles()
    562             throws DataBackendException;
    563
    564     /**
    565      * Retrieves all permissions defined in the system.
    566      *
    567      * @return the names of all roles defined in the system.
    568      * @throws DataBackendException if there was an error accessing the data
    569      *         backend.
    570      */
    571     PermissionSet getAllPermissions()
    572             throws DataBackendException;
    573
    574     /*-----------------------------------------------------------------------
    575       Group/Role/Permission management
    576       -----------------------------------------------------------------------*/
    577
    578     /**
    579      * Creates a new group with specified attributes.
    580      *
    581      * @param group the object describing the group to be created.
    582      * @return the new Group object.
    583      * @throws DataBackendException if there was an error accessing the data
    584      *         backend.
    585      * @throws EntityExistsException if the group already exists.
    586      */
    587     <G extends Group> G addGroup(G group)
    588             throws DataBackendException, EntityExistsException;
    589
    590     /**
    591      * Creates a new role with specified attributes.
    592      *
    593      * @param role The object describing the role to be created.
    594      * @return the new Role object.
    595      * @throws DataBackendException if there was an error accessing the data
    596      *         backend.
    597      * @throws EntityExistsException if the role already exists.
    598      */
    599     <R extends Role> R addRole(R role)
    600             throws DataBackendException, EntityExistsException;
    601
    602     /**
    603      * Creates a new permission with specified attributes.
    604      *
    605      * @param permission The object describing the permission to be created.
    606      * @return the new Permission object.
    607      * @throws DataBackendException if there was an error accessing the data
    608      *         backend.
    609      * @throws EntityExistsException if the permission already exists.
    610      */
    611     <P extends Permission> P addPermission(P permission)
    612             throws DataBackendException, EntityExistsException;
    613
    614     /**
    615      * Removes a Group from the system.
    616      *
    617      * @param group The object describing the group to be removed.
    618      * @throws DataBackendException if there was an error accessing the data
    619      *         backend.
    620      * @throws UnknownEntityException if the group does not exist.
    621      */
    622     void removeGroup(Group group)
    623             throws DataBackendException, UnknownEntityException;
    624
    625     /**
    626      * Removes a Role from the system.
    627      *
    628      * @param role The object describing the role to be removed.
    629      * @throws DataBackendException if there was an error accessing the data
    630      *         backend.
    631      * @throws UnknownEntityException if the role does not exist.
    632      */
    633     void removeRole(Role role)
    634             throws DataBackendException, UnknownEntityException;
    635
    636     /**
    637      * Removes a Permission from the system.
    638      *
    639      * @param permission The object describing the permission to be removed.
    640      * @throws DataBackendException if there was an error accessing the data
    641      *         backend.
    642      * @throws UnknownEntityException if the permission does not exist.
    643      */
    644     void removePermission(Permission permission)
    645             throws DataBackendException, UnknownEntityException;
    646
    647     /**
    648      * Renames an existing Group.
    649      *
    650      * @param group The object describing the group to be renamed.
    651      * @param name the new name for the group.
    652      * @throws DataBackendException if there was an error accessing the data
    653      *         backend.
    654      * @throws UnknownEntityException if the group does not exist.
    655      */
    656     void renameGroup(Group group, String name)
    657             throws DataBackendException, UnknownEntityException;
    658
    659     /**
    660      * Renames an existing Role.
    661      *
    662      * @param role The object describing the role to be renamed.
    663      * @param name the new name for the role.
    664      * @throws DataBackendException if there was an error accessing the data
    665      *         backend.
    666      * @throws UnknownEntityException if the role does not exist.
    667      */
    668     void renameRole(Role role, String name)
    669             throws DataBackendException, UnknownEntityException;
    670
    671     /**
    672      * Renames an existing Permission.
    673      *
    674      * @param permission The object describing the permission to be renamed.
    675      * @param name the new name for the permission.
    676      * @throws DataBackendException if there was an error accessing the data
    677      *         backend.
    678      * @throws UnknownEntityException if the permission does not exist.
    679      */
    680     void renamePermission(Permission permission, String name)
    681             throws DataBackendException, UnknownEntityException;
    682 }