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