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 }