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 * <p>
42 * The Security Service manages Users, Groups Roles and Permissions in the
43 * system.
44 * </p>
45 *
46 * <p>
47 * The task performed by the security service include creation and removal of
48 * accounts, groups, roles, and permissions; assigning users roles in groups;
49 * assigning roles specific permissions and construction of objects
50 * representing these logical entities.
51 * </p>
52 *
53 * <p>
54 * Because of pluggable nature of the Services, it is possible to create
55 * multiple implementations of SecurityService, for example employing database
56 * and directory server as the data backend.
57 * </p>
58 *
59 * @author <a href="mailto:Rafal.Krzewski@e-point.pl">Rafal Krzewski</a>
60 * @author <a href="mailto:hps@intermeta.de">Henning P. Schmiedehausen</a>
61 * @author <a href="mailto:marco@intermeta.de">Marco Knüttel</a>
62 * @version $Id$
63 */
64 public interface SecurityService
65 extends Service
66 {
67 /** The name of the service */
68 String SERVICE_NAME = "SecurityService";
69
70 /**
71 * the key within services's properties for user manager implementation
72 * classname (user.manager)
73 */
74 String USER_MANAGER_KEY = "user.manager";
75
76 /**
77 * the default implementation of UserManager interface
78 * (org.apache.turbine.services.security.passive.PassiveUserManager)
79 */
80 String USER_MANAGER_DEFAULT
81 = PassiveUserManager.class.getName();
82
83 /**
84 * the key within services's properties for user implementation
85 * classname (wrapper.class)
86 */
87 String USER_WRAPPER_KEY = "wrapper.class";
88
89 /**
90 * the default implementation of {@link User} interface
91 * (org.apache.turbine.om.security.DefaultUserImpl)
92 */
93 String USER_WRAPPER_DEFAULT
94 = DefaultUserImpl.class.getName();
95
96
97 /*-----------------------------------------------------------------------
98 Management of User objects
99 -----------------------------------------------------------------------*/
100
101 /**
102 * Construct a blank User object.
103 *
104 * @param <U> user class
105 * @return an object implementing User interface.
106 * @throws UnknownEntityException if the object could not be instantiated.
107 */
108 <U extends User> U getUserInstance()
109 throws UnknownEntityException;
110
111 /**
112 * Construct a blank User object.
113 *
114 * @param <U> user class
115 * @param userName The name of the user.
116 *
117 * @return an object implementing User interface.
118 * @throws UnknownEntityException if the object could not be instantiated.
119 */
120 <U extends User> U getUserInstance(String userName)
121 throws UnknownEntityException;
122
123 /**
124 * Construct a blank Group object.
125 *
126 * @param <G> group class
127 * @return an object implementing Group interface.
128 * @throws UnknownEntityException if the object could not be instantiated.
129 */
130 <G extends Group> G getGroupInstance()
131 throws UnknownEntityException;
132
133 /**
134 * Construct a blank Group object.
135 *
136 * @param <G> group class
137 * @param groupName The name of the Group
138 *
139 * @return an object implementing Group interface.
140 * @throws UnknownEntityException if the object could not be instantiated.
141 */
142 <G extends Group> G getGroupInstance(String groupName)
143 throws UnknownEntityException;
144
145 /**
146 * Construct a blank Permission object.
147 *
148 * @param <P> permission class
149 * @return an object implementing Permission interface.
150 * @throws UnknownEntityException if the object could not be instantiated.
151 */
152 <P extends Permission> P getPermissionInstance()
153 throws UnknownEntityException;
154
155 /**
156 * Construct a blank Permission object.
157 *
158 * @param <P> permission class
159 * @param permName The name of the Permission
160 *
161 * @return an object implementing Permission interface.
162 * @throws UnknownEntityException if the object could not be instantiated.
163 */
164 <P extends Permission> P getPermissionInstance(String permName)
165 throws UnknownEntityException;
166
167 /**
168 * Construct a blank Role object.
169 *
170 * @param <R> role class
171 * @return an object implementing Role interface.
172 * @throws UnknownEntityException if the object could not be instantiated.
173 */
174 <R extends Role> R getRoleInstance()
175 throws UnknownEntityException;
176
177 /**
178 * Construct a blank Role object.
179 *
180 * @param <R> role class
181 * @param roleName The name of the Role
182 *
183 * @return an object implementing Role interface.
184 * @throws UnknownEntityException if the object could not be instantiated.
185 */
186 <R extends Role> R getRoleInstance(String roleName)
187 throws UnknownEntityException;
188
189 /**
190 * Returns the configured UserManager.
191 *
192 * @return An UserManager object
193 */
194 UserManager getUserManager();
195
196 /**
197 * Check whether a specified user's account exists.
198 *
199 * The login name is used for looking up the account.
200 *
201 * @param userName The user to be checked.
202 * @return true if the specified account exists
203 * @throws DataBackendException if there was an error accessing the data
204 * backend.
205 */
206 boolean accountExists(String userName)
207 throws DataBackendException;
208
209 /**
210 * Check whether a specified user's account exists.
211 * An User object is used for looking up the account.
212 *
213 * @param user The user object to be checked.
214 * @return true if the specified account exists
215 * @throws DataBackendException if there was an error accessing the data
216 * backend.
217 */
218 boolean accountExists(User user)
219 throws DataBackendException;
220
221 /**
222 * Authenticates an user, and constructs an User object to represent
223 * him/her.
224 *
225 * @param <U> user class
226 * @param username The user name.
227 * @param password The user password.
228 * @return An authenticated 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 * @throws PasswordMismatchException if the supplied password was incorrect.
233 */
234 <U extends User> U getAuthenticatedUser(String username, String password)
235 throws DataBackendException, UnknownEntityException,
236 PasswordMismatchException;
237
238 /**
239 * Constructs an User object to represent a registered user of the
240 * application.
241 *
242 * @param <U> user class
243 * @param username The user name.
244 * @return A Turbine User.
245 * @throws DataBackendException if there was an error accessing the data
246 * backend.
247 * @throws UnknownEntityException if user account is not present.
248 */
249 <U extends User> U getUser(String username)
250 throws DataBackendException, UnknownEntityException;
251
252 /**
253 * Constructs an User object to represent an anonymous user of the
254 * application.
255 *
256 * @param <U> user class
257 * @return An anonymous Turbine User.
258 * @throws UnknownEntityException if the anonymous User object couldn't be
259 * constructed.
260 */
261 <U extends User> U getAnonymousUser()
262 throws UnknownEntityException;
263
264 /**
265 * Checks whether a passed user object matches the anonymous user pattern
266 * according to the configured user manager
267 *
268 * @param u a user object
269 * @return True if this is an anonymous user
270 *
271 */
272 boolean isAnonymousUser(User u);
273
274 /**
275 * Saves User's data in the permanent storage. The user account is required
276 * to exist in the storage.
277 *
278 * @param user the user object to save
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 storage.
282 */
283 void saveUser(User user)
284 throws UnknownEntityException, DataBackendException;
285
286 /**
287 * Saves User data when the session is unbound. The user account is required
288 * to exist in the storage.
289 *
290 * LastLogin, AccessCounter, persistent pull tools, and any data stored
291 * in the permData hashtable that is not mapped to a column will be saved.
292 *
293 * @param user the user object
294 *
295 * @throws UnknownEntityException if the user's account does not
296 * exist in the database.
297 * @throws DataBackendException if there is a problem accessing the
298 * storage.
299 */
300 void saveOnSessionUnbind(User user)
301 throws UnknownEntityException, DataBackendException;
302
303 /*-----------------------------------------------------------------------
304 Account management
305 -----------------------------------------------------------------------*/
306
307 /**
308 * Creates new user account with specified attributes.
309 *
310 * @param user the object describing account to be created.
311 * @param password The password to use.
312 * @throws DataBackendException if there was an error accessing the data
313 * backend.
314 * @throws EntityExistsException if the user account already exists.
315 * @throws UnknownEntityException if the provided user does not exist (is null)
316 */
317 void addUser(User user, String password)
318 throws DataBackendException, EntityExistsException, UnknownEntityException;
319
320 /**
321 * Removes an user account from the system.
322 *
323 * @param user the object describing the account to be removed.
324 * @throws DataBackendException if there was an error accessing the data
325 * backend.
326 * @throws UnknownEntityException if the user account is not present.
327 */
328 void removeUser(User user)
329 throws DataBackendException, UnknownEntityException;
330
331 /*-----------------------------------------------------------------------
332 Management of passwords
333 -----------------------------------------------------------------------*/
334
335 /**
336 * Change the password for an User.
337 *
338 * @param user an User to change password for.
339 * @param oldPassword the current password supplied by the user.
340 * @param newPassword the current password requested by the user.
341 * @throws PasswordMismatchException if the supplied password was
342 * incorrect.
343 * @throws UnknownEntityException if the user's record does not
344 * exist in the database.
345 * @throws DataBackendException if there is a problem accessing the
346 * storage.
347 */
348 void changePassword(User user, String oldPassword,
349 String newPassword)
350 throws PasswordMismatchException, UnknownEntityException,
351 DataBackendException;
352
353 /**
354 * Forcibly sets new password for an User.
355 *
356 * This is supposed by the administrator to change the forgotten or
357 * compromised passwords. Certain implementatations of this feature
358 * would require administrative level access to the authenticating
359 * server / program.
360 *
361 * @param user an User to change password for.
362 * @param password the new password.
363 * @throws UnknownEntityException if the user's record does not
364 * exist in the database.
365 * @throws DataBackendException if there is a problem accessing the
366 * storage.
367 */
368 void forcePassword(User user, String password)
369 throws UnknownEntityException, DataBackendException;
370
371 /*-----------------------------------------------------------------------
372 Retrieval of security information
373 -----------------------------------------------------------------------*/
374
375 /**
376 * Constructs an AccessControlList for a specific user.
377 *
378 * @param <A> ACL class
379 * @param user the user for whom the AccessControlList are to be retrieved
380 * @return A new AccessControlList object.
381 * @throws DataBackendException if there was an error accessing the data backend.
382 * @throws UnknownEntityException if user account is not present.
383 */
384 <A extends AccessControlList> A getACL(User user)
385 throws DataBackendException, UnknownEntityException;
386
387 /**
388 * Retrieves all permissions associated with a role.
389 *
390 * @param role the role name, for which the permissions are to be retrieved.
391 * @return the permissions associated with the role
392 * @throws DataBackendException if there was an error accessing the data
393 * backend.
394 * @throws UnknownEntityException if the role is not present.
395 */
396 PermissionSet getPermissions(Role role)
397 throws DataBackendException, UnknownEntityException;
398
399 /*-----------------------------------------------------------------------
400 Manipulation of security information
401 -----------------------------------------------------------------------*/
402
403 /**
404 * Grant an User a Role in a Group.
405 *
406 * @param user the user.
407 * @param group the group.
408 * @param role the role.
409 * @throws DataBackendException if there was an error accessing the data
410 * backend.
411 * @throws UnknownEntityException if user account, group or role is not
412 * present.
413 */
414 void grant(User user, Group group, Role role)
415 throws DataBackendException, UnknownEntityException;
416
417 /**
418 * Revoke a Role in a Group from an User.
419 *
420 * @param user the user.
421 * @param group the group.
422 * @param role the role.
423 * @throws DataBackendException if there was an error accessing the data
424 * backend.
425 * @throws UnknownEntityException if user account, group or role is not
426 * present.
427 */
428 void revoke(User user, Group group, Role role)
429 throws DataBackendException, UnknownEntityException;
430
431 /**
432 * Revokes all roles from an User.
433 *
434 * This method is used when deleting an account.
435 *
436 * @param user the User.
437 * @throws DataBackendException if there was an error accessing the data
438 * backend.
439 * @throws UnknownEntityException if the account is not present.
440 */
441 void revokeAll(User user)
442 throws DataBackendException, UnknownEntityException;
443
444 /**
445 * Grants a Role a Permission
446 *
447 * @param role the Role.
448 * @param permission the Permission.
449 * @throws DataBackendException if there was an error accessing the data
450 * backend.
451 * @throws UnknownEntityException if role or permission is not present.
452 */
453 void grant(Role role, Permission permission)
454 throws DataBackendException, UnknownEntityException;
455
456 /**
457 * Revokes a Permission from a Role.
458 *
459 * @param role the Role.
460 * @param permission the Permission.
461 * @throws DataBackendException if there was an error accessing the data
462 * backend.
463 * @throws UnknownEntityException if role or permission is not present.
464 */
465 void revoke(Role role, Permission permission)
466 throws DataBackendException, UnknownEntityException;
467
468 /**
469 * Revokes all permissions from a Role.
470 *
471 * This method is user when deleting a Role.
472 *
473 * @param role the Role
474 * @throws DataBackendException if there was an error accessing the data
475 * backend.
476 * @throws UnknownEntityException if the Role is not present.
477 */
478 void revokeAll(Role role)
479 throws DataBackendException, UnknownEntityException;
480
481 /**
482 * Revokes by default all permissions from a Role and if flag is set
483 * all groups and users for this role
484 *
485 * This method is used when deleting a Role.
486 *
487 * @param role
488 * the Role
489 * @param cascadeDelete
490 * if <code>true </code> removes all groups and user for this role.
491 * @throws DataBackendException
492 * if there was an error accessing the data backend.
493 * @throws UnknownEntityException
494 * if the Role is not present.
495 */
496 void revokeAll( Role role, boolean cascadeDelete )
497 throws DataBackendException, UnknownEntityException;
498
499 /*-----------------------------------------------------------------------
500 Retrieval & storage of SecurityObjects
501 -----------------------------------------------------------------------*/
502
503 /**
504 * Provides a reference to the Group object that represents the
505 * <a href="#global">global group</a>.
506 *
507 * @param <G> group class
508 * @return A Group object that represents the global group.
509 */
510 <G extends Group> G getGlobalGroup();
511
512 /**
513 * Retrieve a Group object with specified name.
514 *
515 * @param <G> group class
516 * @param name the name of the Group.
517 * @return an object representing the Group with specified name.
518 * @throws DataBackendException if there was an error accessing the data
519 * backend.
520 * @throws UnknownEntityException if the group does not exist.
521 */
522 <G extends Group> G getGroupByName(String name)
523 throws DataBackendException, UnknownEntityException;
524
525 /**
526 * Retrieve a Group object with specified Id.
527 *
528 * @param <G> group class
529 * @param id the id of the Group.
530 *
531 * @return an object representing the Group with specified name.
532 *
533 * @throws UnknownEntityException if the permission does not
534 * exist in the database.
535 * @throws DataBackendException if there is a problem accessing the
536 * storage.
537 */
538 <G extends Group> G getGroupById(int id)
539 throws DataBackendException,
540 UnknownEntityException;
541
542 /**
543 * Retrieve a Role object with specified name.
544 *
545 * @param <R> role class
546 * @param name the name of the Role.
547 * @return an object representing the Role with specified name.
548 * @throws DataBackendException if there was an error accessing the data
549 * backend.
550 * @throws UnknownEntityException if the role does not exist.
551 */
552 <R extends Role> R getRoleByName(String name)
553 throws DataBackendException, UnknownEntityException;
554
555 /**
556 * Retrieve a Role object with specified Id.
557 *
558 * @param <R> role class
559 * @param id the id of the Role.
560 *
561 * @return an object representing the Role with specified name.
562 *
563 * @throws UnknownEntityException if the permission does not
564 * exist in the database.
565 * @throws DataBackendException if there is a problem accessing the
566 * storage.
567 */
568 <R extends Role> R getRoleById(int id)
569 throws DataBackendException,
570 UnknownEntityException;
571
572 /**
573 * Retrieve a Permission object with specified name.
574 *
575 * @param <P> permission class
576 * @param name the name of the Permission.
577 * @return an object representing the Permission with specified name.
578 * @throws DataBackendException if there was an error accessing the data
579 * backend.
580 * @throws UnknownEntityException if the permission does not exist.
581 */
582 <P extends Permission> P getPermissionByName(String name)
583 throws DataBackendException, UnknownEntityException;
584
585 /**
586 * Retrieve a Permission object with specified Id.
587 *
588 * @param <P> permission class
589 * @param id the id of the Permission.
590 *
591 * @return an object representing the Permission with specified name.
592 *
593 * @throws UnknownEntityException if the permission does not
594 * exist in the database.
595 * @throws DataBackendException if there is a problem accessing the
596 * storage.
597 */
598 <P extends Permission> P getPermissionById(int id)
599 throws DataBackendException,
600 UnknownEntityException;
601
602 /**
603 * Retrieves all groups defined in the system.
604 *
605 * @return the names of all groups defined in the system.
606 * @throws DataBackendException if there was an error accessing the data
607 * backend.
608 */
609 GroupSet getAllGroups()
610 throws DataBackendException;
611
612 /**
613 * Retrieves all roles defined in the system.
614 *
615 * @return the names of all roles defined in the system.
616 * @throws DataBackendException if there was an error accessing the data
617 * backend.
618 */
619 RoleSet getAllRoles()
620 throws DataBackendException;
621
622 /**
623 * Retrieves all permissions defined in the system.
624 *
625 * @return the names of all roles defined in the system.
626 * @throws DataBackendException if there was an error accessing the data
627 * backend.
628 */
629 PermissionSet getAllPermissions()
630 throws DataBackendException;
631
632 /*-----------------------------------------------------------------------
633 Group/Role/Permission management
634 -----------------------------------------------------------------------*/
635
636 /**
637 * Creates a new group with specified attributes.
638 *
639 * @param <G> group class
640 * @param group the object describing the group to be created.
641 * @return the new Group object.
642 * @throws DataBackendException if there was an error accessing the data
643 * backend.
644 * @throws EntityExistsException if the group already exists.
645 */
646 <G extends Group> G addGroup(G group)
647 throws DataBackendException, EntityExistsException;
648
649 /**
650 * Creates a new role with specified attributes.
651 *
652 * @param <R> role class
653 * @param role The object describing the role to be created.
654 * @return the new Role object.
655 * @throws DataBackendException if there was an error accessing the data
656 * backend.
657 * @throws EntityExistsException if the role already exists.
658 */
659 <R extends Role> R addRole(R role)
660 throws DataBackendException, EntityExistsException;
661
662 /**
663 * Creates a new permission with specified attributes.
664 *
665 * @param <P> permission class
666 * @param permission The object describing the permission to be created.
667 * @return the new Permission object.
668 * @throws DataBackendException if there was an error accessing the data
669 * backend.
670 * @throws EntityExistsException if the permission already exists.
671 */
672 <P extends Permission> P addPermission(P permission)
673 throws DataBackendException, EntityExistsException;
674
675 /**
676 * Removes a Group from the system.
677 *
678 * @param group The object describing the group to be removed.
679 * @throws DataBackendException if there was an error accessing the data
680 * backend.
681 * @throws UnknownEntityException if the group does not exist.
682 */
683 void removeGroup(Group group)
684 throws DataBackendException, UnknownEntityException;
685
686 /**
687 * Removes a Role from the system.
688 *
689 * @param role The object describing the role to be removed.
690 * @throws DataBackendException if there was an error accessing the data
691 * backend.
692 * @throws UnknownEntityException if the role does not exist.
693 */
694 void removeRole(Role role)
695 throws DataBackendException, UnknownEntityException;
696
697 /**
698 * Removes a Permission from the system.
699 *
700 * @param permission The object describing the permission to be removed.
701 * @throws DataBackendException if there was an error accessing the data
702 * backend.
703 * @throws UnknownEntityException if the permission does not exist.
704 */
705 void removePermission(Permission permission)
706 throws DataBackendException, UnknownEntityException;
707
708 /**
709 * Renames an existing Group.
710 *
711 * @param group The object describing the group to be renamed.
712 * @param name the new name for the group.
713 * @throws DataBackendException if there was an error accessing the data
714 * backend.
715 * @throws UnknownEntityException if the group does not exist.
716 */
717 void renameGroup(Group group, String name)
718 throws DataBackendException, UnknownEntityException;
719
720 /**
721 * Renames an existing Role.
722 *
723 * @param role The object describing the role to be renamed.
724 * @param name the new name for the role.
725 * @throws DataBackendException if there was an error accessing the data
726 * backend.
727 * @throws UnknownEntityException if the role does not exist.
728 */
729 void renameRole(Role role, String name)
730 throws DataBackendException, UnknownEntityException;
731
732 /**
733 * Renames an existing Permission.
734 *
735 * @param permission The object describing the permission to be renamed.
736 * @param name the new name for the permission.
737 * @throws DataBackendException if there was an error accessing the data
738 * backend.
739 * @throws UnknownEntityException if the permission does not exist.
740 */
741 void renamePermission(Permission permission, String name)
742 throws DataBackendException, UnknownEntityException;
743 /**
744 * Replaces transactionally the first given role with the second role for the given user.
745 *
746 * @param user the user.
747 * @param role the old role
748 * @param newRole the new role
749 *
750 * @throws DataBackendException if there was an error accessing the data
751 * backend.
752 * @throws UnknownEntityException if the permission does not exist.
753 */
754 void replaceRole( User user, Role role, Role newRole )
755 throws DataBackendException, UnknownEntityException;
756
757 }