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}