    001package org.apache.turbine.services.security;
    002
    003
    004/*
    005 * Licensed to the Apache Software Foundation (ASF) under one
    006 * or more contributor license agreements.  See the NOTICE file
    007 * distributed with this work for additional information
    008 * regarding copyright ownership.  The ASF licenses this file
    009 * to you under the Apache License, Version 2.0 (the
    010 * "License"); you may not use this file except in compliance
    011 * with the License.  You may obtain a copy of the License at
    012 *
    013 *   http://www.apache.org/licenses/LICENSE-2.0
    014 *
    015 * Unless required by applicable law or agreed to in writing,
    016 * software distributed under the License is distributed on an
    017 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
    018 * KIND, either express or implied.  See the License for the
    019 * specific language governing permissions and limitations
    020 * under the License.
    021 */
    022
    023
    024import org.apache.fulcrum.security.acl.AccessControlList;
    025import org.apache.fulcrum.security.entity.Group;
    026import org.apache.fulcrum.security.entity.Permission;
    027import org.apache.fulcrum.security.entity.Role;
    028import org.apache.fulcrum.security.util.DataBackendException;
    029import org.apache.fulcrum.security.util.EntityExistsException;
    030import org.apache.fulcrum.security.util.GroupSet;
    031import org.apache.fulcrum.security.util.PasswordMismatchException;
    032import org.apache.fulcrum.security.util.PermissionSet;
    033import org.apache.fulcrum.security.util.RoleSet;
    034import org.apache.fulcrum.security.util.UnknownEntityException;
    035import org.apache.turbine.om.security.User;
    036import org.apache.turbine.services.Service;
    037import org.apache.turbine.services.security.passive.PassiveUserManager;
    038
    039/**
    040 * The Security Service manages Users, Groups Roles and Permissions in the
    041 * system.
    042 *
    043 * The task performed by the security service include creation and removal of
    044 * accounts, groups, roles, and permissions; assigning users roles in groups;
    045 * assigning roles specific permissions and construction of objects
    046 * representing these logical entities.
    047 *
    048 * <p> Because of pluggable nature of the Services, it is possible to create
    049 * multiple implementations of SecurityService, for example employing database
    050 * and directory server as the data backend.<br>
    051 *
    052 * @author <a href="mailto:Rafal.Krzewski@e-point.pl">Rafal Krzewski</a>
    053 * @author <a href="mailto:hps@intermeta.de">Henning P. Schmiedehausen</a>
    054 * @author <a href="mailto:marco@intermeta.de">Marco Kn&uuml;ttel</a>
    055 * @version $Id: SecurityService.java 1706239 2015-10-01 13:18:35Z tv $
    056 */
    057public interface SecurityService
    058        extends Service
    059{
    060    /** The name of the service */
    061    String SERVICE_NAME = "SecurityService";
    062
    063    /**
    064     * the key within services's properties for user implementation
    065     * classname (user.manager)
    066     */
    067    String USER_MANAGER_KEY = "user.manager";
    068
    069    /**
    070     * the default implementation of UserManager interface
    071     * (org.apache.turbine.services.security.passive.PassiveUserManager)
    072     */
    073    String USER_MANAGER_DEFAULT
    074            = PassiveUserManager.class.getName();
    075
    076    /*-----------------------------------------------------------------------
    077      Management of User objects
    078      -----------------------------------------------------------------------*/
    079
    080    /**
    081     * Construct a blank User object.
    082     *
    083     * @return an object implementing User interface.
    084     * @throws UnknownEntityException if the object could not be instantiated.
    085     */
    086    <U extends User> U getUserInstance()
    087            throws UnknownEntityException;
    088
    089    /**
    090     * Construct a blank User object.
    091     *
    092     * @param userName The name of the user.
    093     *
    094     * @return an object implementing User interface.
    095     * @throws UnknownEntityException if the object could not be instantiated.
    096     */
    097    <U extends User> U getUserInstance(String userName)
    098            throws UnknownEntityException;
    099
    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}