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 }