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