View Javadoc

1   package org.apache.turbine.services.security;
2   
3   /*
4    * Licensed to the Apache Software Foundation (ASF) under one
5    * or more contributor license agreements.  See the NOTICE file
6    * distributed with this work for additional information
7    * regarding copyright ownership.  The ASF licenses this file
8    * to you under the Apache License, Version 2.0 (the
9    * "License"); you may not use this file except in compliance
10   * with the License.  You may obtain a copy of the License at
11   *
12   *   http://www.apache.org/licenses/LICENSE-2.0
13   *
14   * Unless required by applicable law or agreed to in writing,
15   * software distributed under the License is distributed on an
16   * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
17   * KIND, either express or implied.  See the License for the
18   * specific language governing permissions and limitations
19   * under the License.
20   */
21  
22  
23  import org.apache.fulcrum.security.acl.AccessControlList;
24  import org.apache.fulcrum.security.entity.Group;
25  import org.apache.fulcrum.security.entity.Permission;
26  import org.apache.fulcrum.security.entity.Role;
27  import org.apache.fulcrum.security.model.turbine.TurbineModelManager;
28  import org.apache.fulcrum.security.util.DataBackendException;
29  import org.apache.fulcrum.security.util.EntityExistsException;
30  import org.apache.fulcrum.security.util.FulcrumSecurityException;
31  import org.apache.fulcrum.security.util.GroupSet;
32  import org.apache.fulcrum.security.util.PasswordMismatchException;
33  import org.apache.fulcrum.security.util.PermissionSet;
34  import org.apache.fulcrum.security.util.RoleSet;
35  import org.apache.fulcrum.security.util.UnknownEntityException;
36  import org.apache.turbine.om.security.User;
37  import org.apache.turbine.services.TurbineServices;
38  
39  /**
40   * This is a Facade class for SecurityService.
41   *
42   * This class provides static methods that call related methods of the
43   * implementation of SecurityService used by the System, according to
44   * the settings in TurbineResources.
45   * <br>
46   *
47   * <a name="global">
48   * <p> Certain Roles that the Users may have in the system may are not related
49   * to any specific resource nor entity. They are assigned within a special group
50   * named 'global' that can be referenced in the code as
51   * {@link TurbineModelManager#GLOBAL_GROUP_NAME}.
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   * @version $Id: TurbineSecurity.java 1706239 2015-10-01 13:18:35Z tv $
56   */
57  public abstract class TurbineSecurity
58  {
59      /**
60       * Retrieves an implementation of SecurityService, base on the settings in
61       * TurbineResources.
62       *
63       * @return an implementation of SecurityService.
64       */
65      public static SecurityService getService()
66      {
67          return (SecurityService) TurbineServices.getInstance().
68                  getService(SecurityService.SERVICE_NAME);
69      }
70  
71      /*-----------------------------------------------------------------------
72        Management of User objects
73        -----------------------------------------------------------------------*/
74  
75      /**
76       * Construct a blank User object.
77       *
78       * This method calls getUserClass, and then creates a new object using
79       * the default constructor.
80       *
81       * @return an object implementing User interface.
82       * @throws UnknownEntityException if the object could not be instantiated.
83       */
84      public static User getUserInstance()
85              throws UnknownEntityException
86      {
87          return getService().getUserInstance();
88      }
89  
90      /**
91       * Returns the configured UserManager.
92       *
93       * @return An UserManager object
94       */
95      public static UserManager getUserManager()
96      {
97          return getService().getUserManager();
98      }
99  
100     /**
101      * Check whether a specified user's account exists.
102      *
103      * The login name is used for looking up the account.
104      *
105      * @param user The user to be checked.
106      * @return true if the specified account exists
107      * @throws DataBackendException if there was an error accessing the data
108      *         backend.
109      */
110     public static boolean accountExists(User user)
111             throws DataBackendException
112     {
113         return getService().accountExists(user);
114     }
115 
116     /**
117      * Check whether a specified user's account exists.
118      *
119      * The login name is used for looking up the account.
120      *
121      * @param userName The name of the user to be checked.
122      * @return true if the specified account exists
123      * @throws DataBackendException if there was an error accessing the data
124      *         backend.
125      */
126     public static boolean accountExists(String userName)
127             throws DataBackendException
128     {
129         return getService().accountExists(userName);
130     }
131 
132     /**
133      * Authenticates an user, and constructs an User object to represent
134      * him/her.
135      *
136      * @param username The user name.
137      * @param password The user password.
138      * @return An authenticated Turbine User.
139      * @throws DataBackendException if there was an error accessing the data
140      *         backend.
141      * @throws UnknownEntityException if user account is not present.
142      * @throws PasswordMismatchException if the supplied password was incorrect.
143      */
144     public static User getAuthenticatedUser(String username, String password)
145             throws DataBackendException, UnknownEntityException,
146             PasswordMismatchException
147     {
148         return getService().getAuthenticatedUser(username, password);
149     }
150 
151     /**
152      * Constructs an User object to represent a registered user of the
153      * application.
154      *
155      * @param username The user name.
156      * @return A Turbine User.
157      * @throws DataBackendException if there was an error accessing the data
158      *         backend.
159      * @throws UnknownEntityException if user account is not present.
160      */
161     public static User getUser(String username)
162             throws DataBackendException, UnknownEntityException
163     {
164         return getService().getUser(username);
165     }
166 
167     /**
168      * Constructs an User object to represent an anonymous user of the
169      * application.
170      *
171      * @return An anonymous Turbine User.
172      * @throws UnknownEntityException if the anonymous User object couldn't be
173      *         constructed.
174      */
175     public static User getAnonymousUser()
176             throws UnknownEntityException
177     {
178         return getService().getAnonymousUser();
179     }
180 
181     /**
182      * Checks whether a passed user object matches the anonymous user pattern
183      * according to the configured service
184      *
185      * @param user A user object
186      * @return True if this is an anonymous user
187      */
188     public static boolean isAnonymousUser(User user)
189     {
190         return getService().isAnonymousUser(user);
191     }
192 
193     /**
194      * Saves User's data in the permanent storage. The user account is required
195      * to exist in the storage.
196      *
197      * @param user The User object to save.
198      * @throws UnknownEntityException if the user's account does not
199      *         exist in the database.
200      * @throws DataBackendException if there is a problem accessing the
201      *         storage.
202      */
203     public static void saveUser(User user)
204             throws UnknownEntityException, DataBackendException
205     {
206         getService().saveUser(user);
207     }
208 
209     /**
210      * Saves User data when the session is unbound. The user account is required
211      * to exist in the storage.
212      *
213      * LastLogin, AccessCounter, persistent pull tools, and any data stored
214      * in the permData hashtable that is not mapped to a column will be saved.
215      *
216      * @param user the user in the session
217      *
218      * @exception UnknownEntityException if the user's account does not
219      *            exist in the database.
220      * @exception DataBackendException if there is a problem accessing the
221      *            storage.
222      */
223     public static void saveOnSessionUnbind(User user)
224             throws UnknownEntityException, DataBackendException
225     {
226         getService().saveOnSessionUnbind(user);
227     }
228 
229     /**
230      * Change the password for an User.
231      *
232      * @param user an User to change password for.
233      * @param oldPassword the current password supplied by the user.
234      * @param newPassword the current password requested by the user.
235      * @throws PasswordMismatchException if the supplied password was
236      *         incorrect.
237      * @throws UnknownEntityException if the user's record does not
238      *         exist in the database.
239      * @throws DataBackendException if there is a problem accessing the
240      *         storage.
241      */
242     public static void changePassword(User user, String oldPassword,
243                                       String newPassword)
244             throws PasswordMismatchException, UnknownEntityException,
245             DataBackendException
246     {
247         getService().changePassword(user, oldPassword, newPassword);
248     }
249 
250     /**
251      * Forcibly sets new password for an User.
252      *
253      * This is supposed by the administrator to change the forgotten or
254      * compromised passwords. Certain implementations of this feature
255      * would require administrative level access to the authenticating
256      * server / program.
257      *
258      * @param user an User to change password for.
259      * @param password the new password.
260      * @throws UnknownEntityException if the user's record does not
261      *         exist in the database.
262      * @throws DataBackendException if there is a problem accessing the
263      *         storage.
264      */
265     public static void forcePassword(User user, String password)
266             throws UnknownEntityException, DataBackendException
267     {
268         getService().forcePassword(user, password);
269     }
270 
271     /*-----------------------------------------------------------------------
272       Creation of AccessControlLists
273       -----------------------------------------------------------------------*/
274 
275     /**
276      * Constructs an AccessControlList for a specific user.
277      *
278      * @param user the user for whom the AccessControlList are to be retrieved
279      * @return The AccessControList object constructed from the user object.
280      * @throws DataBackendException if there was an error accessing the data
281      *         backend.
282      * @throws UnknownEntityException if user account is not present.
283      */
284     public static AccessControlList getACL(User user)
285             throws DataBackendException, UnknownEntityException
286     {
287         return getService().getACL(user);
288     }
289 
290     /*-----------------------------------------------------------------------
291       Security management
292       -----------------------------------------------------------------------*/
293 
294     /**
295      * Grant an User a Role in a Group.
296      *
297      * @param user the user.
298      * @param group the group.
299      * @param role the role.
300      * @throws DataBackendException if there was an error accessing the data
301      *         backend.
302      * @throws UnknownEntityException if user account, group or role is not
303      *         present.
304      */
305     public static void grant(User user, Group group, Role role)
306             throws DataBackendException, UnknownEntityException
307     {
308         getService().grant(user, group, role);
309     }
310 
311     /**
312      * Revoke a Role in a Group from an User.
313      *
314      * @param user the user.
315      * @param group the group.
316      * @param role the role.
317      * @throws DataBackendException if there was an error accessing the data
318      *         backend.
319      * @throws UnknownEntityException if user account, group or role is not
320      *         present.
321      */
322     public static void revoke(User user, Group group, Role role)
323             throws DataBackendException, UnknownEntityException
324     {
325         getService().revoke(user, group, role);
326     }
327 
328     /**
329      * Revokes all roles from an User.
330      *
331      * This method is used when deleting an account.
332      *
333      * @param user the User.
334      * @throws DataBackendException if there was an error accessing the data
335      *         backend.
336      * @throws UnknownEntityException if the account is not present.
337      */
338     public static void revokeAll(User user)
339             throws DataBackendException, UnknownEntityException
340     {
341         getService().revokeAll(user);
342     }
343 
344     /**
345      * Grants a Role a Permission
346      *
347      * @param role the Role.
348      * @param permission the Permission.
349      * @throws DataBackendException if there was an error accessing the data
350      *         backend.
351      * @throws UnknownEntityException if role or permission is not present.
352      */
353     public static void grant(Role role, Permission permission)
354             throws DataBackendException, UnknownEntityException
355     {
356         getService().grant(role, permission);
357     }
358 
359     /**
360      * Revokes a Permission from a Role.
361      *
362      * @param role the Role.
363      * @param permission the Permission.
364      * @throws DataBackendException if there was an error accessing the data
365      *         backend.
366      * @throws UnknownEntityException if role or permission is not present.
367      */
368     public static void revoke(Role role, Permission permission)
369             throws DataBackendException, UnknownEntityException
370     {
371         getService().revoke(role, permission);
372     }
373 
374     /**
375      * Revokes all permissions from a Role.
376      *
377      * This method is user when deleting a Role.
378      *
379      * @param role the Role
380      * @throws DataBackendException if there was an error accessing the data
381      *         backend.
382      * @throws  UnknownEntityException if the Role is not present.
383      */
384     public static void revokeAll(Role role)
385             throws DataBackendException, UnknownEntityException
386     {
387         getService().revokeAll(role);
388     }
389 
390     /*-----------------------------------------------------------------------
391       Account management
392       -----------------------------------------------------------------------*/
393 
394     /**
395      * Creates new user account with specified attributes.
396      *
397      * <strong>TODO</strong> throw more specific exception<br>
398      *
399      * @param user the object describing account to be created.
400      * @param password password for the new user
401      * @throws DataBackendException if there was an error accessing the data
402      *         backend.
403      * @throws EntityExistsException if the user account already exists.
404      */
405     public static void addUser(User user, String password)
406             throws DataBackendException, EntityExistsException
407     {
408         getService().addUser(user, password);
409     }
410 
411     /**
412      * Removes an user account from the system.
413      *
414      * <strong>TODO</strong> throw more specific exception<br>
415      *
416      * @param user the object describing the account to be removed.
417      * @throws DataBackendException if there was an error accessing the data
418      *         backend.
419      * @throws UnknownEntityException if the user account is not present.
420      */
421     public static void removeUser(User user)
422             throws DataBackendException, UnknownEntityException
423     {
424         getService().removeUser(user);
425     }
426 
427     /*-----------------------------------------------------------------------
428       Group/Role/Permission management
429       -----------------------------------------------------------------------*/
430     /**
431      * Provides a reference to the Group object that represents the
432      * <a name="global">global group</a>.
433      *
434      * @return a Group object that represents the global group.
435      */
436     public static Group getGlobalGroup()
437     {
438         return getService().getGlobalGroup();
439     }
440 
441     /**
442      * Creates a new Group in the system. This is a convenience
443      * method.
444      *
445      * @param name The name of the new Group.
446      * @return An object representing the new Group.
447      * @throws FulcrumSecurityException if the Group could not be created.
448      */
449     public static Group createGroup(String name)
450             throws FulcrumSecurityException
451     {
452         return getService().addGroup(getGroupInstance(name));
453     }
454 
455     /**
456      * Creates a new Permission in the system. This is a convenience
457      * method.
458      *
459      * @param name The name of the new Permission.
460      * @return An object representing the new Permission.
461      * @throws FulcrumSecurityException if the Permission could not be created.
462      */
463     public static Permission createPermission(String name)
464             throws FulcrumSecurityException
465     {
466         return getService().addPermission(getPermissionInstance(name));
467     }
468 
469     /**
470      * Creates a new Role in the system. This is a convenience
471      * method.
472      *
473      * @param name The name of the Role.
474      *
475      * @return An object representing the new Role.
476      *
477      * @throws FulcrumSecurityException if the Role could not be created.
478      */
479     public static Role createRole(String name)
480         throws FulcrumSecurityException
481     {
482         return getService().addRole(getRoleInstance(name));
483     }
484 
485     /**
486      * Retrieve a Group object with specified name.
487      *
488      * @param groupName The name of the Group to be retrieved.
489      * @return an object representing the Group with specified name.
490      * @throws DataBackendException if there was an error accessing the data
491      *         backend.
492      * @throws UnknownEntityException if the Group is not present.
493      */
494     public static Group getGroupByName(String groupName)
495             throws DataBackendException, UnknownEntityException
496     {
497         return getService().getGroupByName(groupName);
498     }
499 
500     /**
501      * Retrieve a Group object with specified Id.
502      *
503      * @param groupId the id of the Group.
504      *
505      * @return an object representing the Group 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     public static Group getGroupById(int groupId)
513             throws DataBackendException,
514                    UnknownEntityException
515     {
516         return getService().getGroupById(groupId);
517     }
518 
519     /**
520      * Construct a blank Group object.
521      *
522      * This method calls getGroupClass, and then creates a new object using
523      * the default constructor.
524      *
525      * @param groupName The name of the Group
526      *
527      * @return an object implementing Group interface.
528      *
529      * @throws UnknownEntityException if the object could not be instantiated.
530      */
531     public static Group getGroupInstance(String groupName)
532             throws UnknownEntityException
533     {
534         return getService().getGroupInstance(groupName);
535     }
536 
537     /**
538      * Construct a blank Role object.
539      *
540      * This method calls getRoleClass, and then creates a new object using
541      * the default constructor.
542      *
543      * @param roleName The name of the role.
544      *
545      * @return an object implementing Role interface.
546      *
547      * @throws UnknownEntityException if the object could not be instantiated.
548      */
549     public static Role getRoleInstance(String roleName)
550             throws UnknownEntityException
551     {
552         return getService().getRoleInstance(roleName);
553     }
554 
555     /**
556      * Construct a blank Permission object.
557      *
558      * This method calls getPermissionClass, and then creates a new object using
559      * the default constructor.
560      *
561      * @param permName The name of the permission.
562      *
563      * @return an object implementing Permission interface.
564      * @throws UnknownEntityException if the object could not be instantiated.
565      */
566     public static Permission getPermissionInstance(String permName)
567             throws UnknownEntityException
568     {
569         return getService().getPermissionInstance(permName);
570     }
571 
572     /**
573      * Retrieve a Role object with specified name.
574      *
575      * @param roleName The name of the Role to be retrieved.
576      * @return an object representing the Role with specified name.
577      * @throws DataBackendException if there was an error accessing the data
578      *         backend.
579      * @throws UnknownEntityException if the Role is not present.
580      */
581     public static Role getRoleByName(String roleName)
582             throws DataBackendException, UnknownEntityException
583     {
584         return getService().getRoleByName(roleName);
585     }
586 
587     /**
588      * Retrieve a Role object with specified Id.
589      *
590      * @param roleId the id of the Role.
591      *
592      * @return an object representing the Role with specified name.
593      *
594      * @exception UnknownEntityException if the permission does not
595      *            exist in the database.
596      * @exception DataBackendException if there is a problem accessing the
597      *            storage.
598      */
599     public static Role getRoleById(int roleId)
600             throws DataBackendException,
601                    UnknownEntityException
602     {
603         return getService().getRoleById(roleId);
604     }
605 
606     /**
607      * Retrieve a Permission object with specified name.
608      *
609      * @param permissionName The name of the Permission to be retrieved.
610      * @return an object representing the Permission with specified name.
611      * @throws DataBackendException if there was an error accessing the data
612      *         backend.
613      * @throws UnknownEntityException if the Permission is not present.
614      */
615     public static Permission getPermissionByName(String permissionName)
616             throws DataBackendException, UnknownEntityException
617     {
618         return getService().getPermissionByName(permissionName);
619     }
620 
621     /**
622      * Retrieve a Permission object with specified Id.
623      *
624      * @param permissionId the id of the Permission.
625      *
626      * @return an object representing the Permission with specified name.
627      *
628      * @exception UnknownEntityException if the permission does not
629      *            exist in the database.
630      * @exception DataBackendException if there is a problem accessing the
631      *            storage.
632      */
633     public static Permission getPermissionById(int permissionId)
634             throws DataBackendException,
635                    UnknownEntityException
636     {
637         return getService().getPermissionById(permissionId);
638     }
639 
640     /**
641      * Retrieves all groups defined in the system.
642      *
643      * @return the names of all groups defined in the system.
644      * @throws DataBackendException if there was an error accessing the data
645      *         backend.
646      */
647     public static GroupSet getAllGroups()
648             throws DataBackendException
649     {
650         return getService().getAllGroups();
651     }
652 
653     /**
654      * Retrieves all roles defined in the system.
655      *
656      * @return the names of all roles defined in the system.
657      * @throws DataBackendException if there was an error accessing the data
658      *         backend.
659      */
660     public static RoleSet getAllRoles()
661             throws DataBackendException
662     {
663         return getService().getAllRoles();
664     }
665 
666     /**
667      * Retrieves all permissions defined in the system.
668      *
669      * @return the names of all roles defined in the system.
670      * @throws DataBackendException if there was an error accessing the data
671      *         backend.
672      */
673     public static PermissionSet getAllPermissions()
674             throws DataBackendException
675     {
676         return getService().getAllPermissions();
677     }
678 
679     /**
680      * Retrieves all permissions associated with a role.
681      *
682      * @param role the role name, for which the permissions are to be retrieved.
683      * @return the Permissions for the specified role
684      * @throws DataBackendException if there was an error accessing the data
685      *         backend.
686      * @throws UnknownEntityException if the role is not present.
687      */
688     public static PermissionSet getPermissions(Role role)
689             throws DataBackendException, UnknownEntityException
690     {
691         return getService().getPermissions(role);
692     }
693 
694     /**
695      * Creates a new group with specified attributes.
696      *
697      * @param group the object describing the group to be created.
698      * @throws DataBackendException if there was an error accessing the data
699      *         backend.
700      * @throws EntityExistsException if the group already exists.
701      */
702     public static void addGroup(Group group)
703             throws DataBackendException, EntityExistsException
704     {
705         getService().addGroup(group);
706     }
707 
708     /**
709      * Creates a new role with specified attributes.
710      *
711      * @param role the objects describing the role to be created.
712      * @throws DataBackendException if there was an error accessing the data
713      *         backend.
714      * @throws EntityExistsException if the role already exists.
715      */
716     public static void addRole(Role role)
717             throws DataBackendException, EntityExistsException
718     {
719         getService().addRole(role);
720     }
721 
722     /**
723      * Creates a new permission with specified attributes.
724      *
725      * @param permission the objects describing the permission to be created.
726      * @throws DataBackendException if there was an error accessing the data
727      *         backend.
728      * @throws EntityExistsException if the permission already exists.
729      */
730     public static void addPermission(Permission permission)
731             throws DataBackendException, EntityExistsException
732     {
733         getService().addPermission(permission);
734     }
735 
736     /**
737      * Removes a Group from the system.
738      *
739      * @param group the object describing group to be removed.
740      * @throws DataBackendException if there was an error accessing the data
741      *         backend.
742      * @throws UnknownEntityException if the group does not exist.
743      */
744     public static void removeGroup(Group group)
745             throws DataBackendException, UnknownEntityException
746     {
747         getService().removeGroup(group);
748     }
749 
750     /**
751      * Removes a Role from the system.
752      *
753      * @param role The object describing the role to be removed.
754      * @throws DataBackendException if there was an error accessing the data backend.
755      * @throws UnknownEntityException if the role does not exist.
756      */
757     public static void removeRole(Role role)
758             throws DataBackendException, UnknownEntityException
759     {
760         getService().removeRole(role);
761     }
762 
763     /**
764      * Removes a Permission from the system.
765      *
766      * @param permission The object describing the permission to be removed.
767      * @throws DataBackendException if there was an error accessing the data
768      *         backend.
769      * @throws UnknownEntityException if the permission does not exist.
770      */
771     public static void removePermission(Permission permission)
772             throws DataBackendException, UnknownEntityException
773     {
774         getService().removePermission(permission);
775     }
776 
777     /**
778      * Renames an existing Group.
779      *
780      * @param group The object describing the group to be renamed.
781      * @param name the new name for the group.
782      * @throws DataBackendException if there was an error accessing the data
783      *         backend.
784      * @throws UnknownEntityException if the group does not exist.
785      */
786     public static void renameGroup(Group group, String name)
787             throws DataBackendException, UnknownEntityException
788     {
789         getService().renameGroup(group, name);
790     }
791 
792     /**
793      * Renames an existing Role.
794      *
795      * @param role The object describing the role to be renamed.
796      * @param name the new name for the role.
797      * @throws DataBackendException if there was an error accessing the data
798      *         backend.
799      * @throws UnknownEntityException if the role does not exist.
800      */
801     public static void renameRole(Role role, String name)
802             throws DataBackendException, UnknownEntityException
803     {
804         getService().renameRole(role, name);
805     }
806 
807     /**
808      * Renames an existing Permission.
809      *
810      * @param permission The object describing the permission to be renamed.
811      * @param name the new name for the permission.
812      * @throws DataBackendException if there was an error accessing the data
813      *         backend.
814      * @throws UnknownEntityException if the permission does not exist.
815      */
816     public static void renamePermission(Permission permission, String name)
817             throws DataBackendException, UnknownEntityException
818     {
819         getService().renamePermission(permission, name);
820     }
821 }