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ü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 }