1 /**
2 * 2007, Digitalis Informatica. All rights reserved. Distribuicao e Gestao de Informatica, Lda. Estrada de Paco de Arcos
3 * num.9 - Piso -1 2780-666 Paco de Arcos Telefone: (351) 21 4408990 Fax: (351) 21 4408999 http://www.digitalis.pt
4 */
5
6 package pt.digitalis.dif.controller.security.managers;
7
8 import java.util.List;
9 import java.util.Map;
10 import java.util.Set;
11
12 import pt.digitalis.dif.controller.security.objects.IDIFGroup;
13 import pt.digitalis.dif.controller.security.objects.IDIFUser;
14 import pt.digitalis.dif.exception.security.IdentityManagerException;
15 import pt.digitalis.dif.utils.Pagination;
16
17 /**
18 * Defines the expected behavior for an identity manager. This manager supports users {@link IDIFUser} and groups
19 * {@link IDIFGroup}.
20 *
21 * @author Rodrigo Gon�alves <a href="mailto:rgoncalves@digitalis.pt">rgoncalves@digitalis.pt</a><br/>
22 * @author Luis Pinto <a href="lpinto@digitalis.pt">lpinto@digitalis.pt</a><br/>
23 * @author Pedro Viegas <a href="mailto:pviegas@digitalis.pt">pviegas@digitalis.pt</a><br/>
24 * @author Fábio Souto <a href="mailto:fsouto@digitalis.pt">fsouto@digitalis.pt</a><br/>
25 * @created 2007/12/04
26 */
27 public interface IIdentityManager {
28
29 // --------- User operations ---------
30
31 /**
32 * Adds a new group to the manager.
33 *
34 * @param newGroup
35 * the group to add
36 * @throws IdentityManagerException
37 * if the user can't be added
38 */
39 public void addGroup(IDIFGroup newGroup) throws IdentityManagerException;
40
41 /**
42 * Adds a managed attribute.
43 *
44 * @param attribute
45 * The attribute
46 */
47 public void addManagedAttribute(String attribute);
48
49 /**
50 * Adds a comma-separated list of managed attributes.
51 *
52 * @param attributes
53 * The comma-separated list of managed attributes.
54 */
55 public void addManagedAttributes(String attributes);
56
57 /**
58 * Adds a new user to the manager.
59 *
60 * @param newUser
61 * the new user to add to the manager
62 * @throws IdentityManagerException
63 * if the user can't be added
64 */
65 public void addUser(IDIFUser newUser) throws IdentityManagerException;
66
67 /**
68 * Adds an existing user to an existing group.
69 *
70 * @param groupID
71 * the group ID
72 * @param userID
73 * the user ID
74 * @throws IdentityManagerException
75 * if the user can't be added to the group
76 */
77 public void addUserToGroup(String userID, String groupID) throws IdentityManagerException;
78
79 /**
80 * Changes the password for the supplied user.
81 *
82 * @param userID
83 * the user ID
84 * @param newPassword
85 * the new password
86 * @throws IdentityManagerException
87 * if the password can't be changed
88 */
89 public void changePassword(String userID, String newPassword) throws IdentityManagerException;
90
91 /**
92 * Checks if a parameter exists.
93 *
94 * @param userID
95 * the user ID
96 * @param parameterID
97 * the parameter ID
98 * @return T if the parameter exists, F otherwise
99 */
100 public boolean containsUserParameter(String userID, String parameterID);
101
102 /**
103 * Counts the number of groups in the system
104 *
105 * @return The number of groups in the system
106 * @throws IdentityManagerException
107 * * If the operation cannot be executed
108 */
109 public int countAllGroups() throws IdentityManagerException;
110
111 /**
112 * Counts all groups of a given user.
113 *
114 * @param userId
115 * The user identifier
116 * @return The number of groups of this user.
117 * @throws IdentityManagerException
118 */
119 public int countAllGroupsOfUser(String userId) throws IdentityManagerException;
120
121 /**
122 * Counts all groups of a given user.
123 *
124 * @param userId
125 * The user identifier
126 * @param parseGroupHierarchy
127 * contemplates the group Hierarchy
128 * @return The number of groups of this user.
129 * @throws IdentityManagerException
130 */
131 public int countAllGroupsOfUser(String userId, boolean parseGroupHierarchy) throws IdentityManagerException;
132
133 /**
134 * Counts the number of users in the system
135 *
136 * @return The number of users on the system
137 * @throws IdentityManagerException
138 * If the operation cannot be executed
139 */
140 public int countAllUsers() throws IdentityManagerException;
141
142 /**
143 * Counts all users of a given group.
144 *
145 * @param groupId
146 * The group identifier
147 * @return The number of users of this group.
148 * @throws IdentityManagerException
149 */
150 public int countAllUsers(String groupId) throws IdentityManagerException;
151
152 /**
153 * Count the number of users in the system which match all of the provided attributes
154 *
155 * @param attributes
156 * The attributes
157 * @return The number of users in the system which match all of the provided attributes
158 * @throws IdentityManagerException
159 * If the operation cannot be executed
160 */
161 public int countUsers(Map<String, String> attributes) throws IdentityManagerException;
162
163 /**
164 * Gathers the managed attributes. This method must be used to initialize the managed attributes.
165 *
166 * @return The list containing the managed attributes
167 */
168 public List<String> gatherManagedAttributes();
169
170 /**
171 * Get all the groups registered in the system
172 *
173 * @return A set containing all the groups
174 * @throws IdentityManagerException
175 * If the operation cannot be executed
176 */
177 public Set<IDIFGroup> getAllGroups() throws IdentityManagerException;
178
179 /**
180 * Get all the users in the system
181 *
182 * @return A set containing all the users
183 * @throws IdentityManagerException
184 * If the operation cannot be executed
185 */
186 public Set<IDIFUser> getAllUsers() throws IdentityManagerException;
187
188 /**
189 * Get the exclusion charaters
190 *
191 * @return value
192 */
193 public String getExclusionCharaters();
194
195 /**
196 * Gets a group from its id, if it exists.
197 *
198 * @param groupID
199 * the group id
200 * @return the group with the given id if it exists, null otherwise
201 * @throws IdentityManagerException
202 * if the group can't be found
203 */
204 public IDIFGroup getGroup(String groupID) throws IdentityManagerException;
205
206 /**
207 * Gets the group attribute name
208 *
209 * @return The string containing the attribute name
210 */
211 public String getGroupAttributeName();
212
213 /**
214 * Returns the list of groups whose parent group is the given group
215 *
216 * @param parentGroupID
217 * the parent group to search for children groups
218 * @return the list of groups
219 * @throws IdentityManagerException
220 * if the group's groups can't be found
221 */
222 public Map<String, IDIFGroup> getGroupGroups(String parentGroupID) throws IdentityManagerException;
223
224 /**
225 * Returns a subset of all groups in the system, according to the parameters
226 *
227 * @param page
228 * The required page
229 * @return A set of groups containing the specified subset
230 * @throws IdentityManagerException
231 * If the operation can't be executed
232 */
233 public Set<IDIFGroup> getGroups(Pagination page) throws IdentityManagerException;
234
235 /**
236 * Returns the list of users of a given group
237 *
238 * @param groupID
239 * the group
240 * @return the list of users
241 * @throws IdentityManagerException
242 * if the operation can't be executed
243 */
244 public Map<String, IDIFUser> getGroupUsers(String groupID) throws IdentityManagerException;
245
246 /**
247 * Gets the mail attribute name
248 *
249 * @return The string containing the attribute name.
250 */
251 public String getMailAttributeName();
252
253 /**
254 * Gets the framework managed attributes.
255 *
256 * @return the managedAttributes value
257 */
258 public List<String> getManagedAttributes();
259
260 /**
261 * Gets the name attribute name
262 *
263 * @return The string containing the attribute name.
264 */
265 public String getNameAttributeName();
266
267 /**
268 * Gets an user from its id, if it exists.
269 *
270 * @param userID
271 * the user id
272 * @return the user that matches the supplied id if it exists, null otherwise
273 * @throws IdentityManagerException
274 * if the user can't be fetched
275 */
276 public IDIFUser getUser(String userID) throws IdentityManagerException;
277
278 /**
279 * Returns the list of groups of a given user
280 *
281 * @param userID
282 * the user
283 * @return the list of groups
284 * @throws IdentityManagerException
285 * if the group's users can't be found
286 */
287 public Map<String, IDIFGroup> getUserGroups(String userID) throws IdentityManagerException;
288
289 /**
290 * Returns the list of groups of a given user
291 *
292 * @param userID
293 * the user
294 * @param parseGroupHierarchy
295 * contemplates the group Hierarchy
296 * @return the list of groups
297 * @throws IdentityManagerException
298 * if the group's users can't be found
299 */
300 public Map<String, IDIFGroup> getUserGroups(String userID, boolean parseGroupHierarchy)
301 throws IdentityManagerException;
302
303 /**
304 * Returns the list of group IDs of a given user
305 *
306 * @param userID
307 * the user
308 * @return the list of groups
309 * @throws IdentityManagerException
310 * if the group's users can't be found
311 */
312 public Set<String> getUserGroupsIDs(String userID) throws IdentityManagerException;
313
314 /**
315 * Returns the list of group IDs of a given user
316 *
317 * @param userID
318 * the user
319 * @param parseGroupHierarchy
320 * contemplates the group Hierarchy
321 * @return the list of groups
322 * @throws IdentityManagerException
323 * if the group's users can't be found
324 */
325 public Set<String> getUserGroupsIDs(String userID, boolean parseGroupHierarchy) throws IdentityManagerException;
326
327 /**
328 * Returns the list of groups of a given user, with pagination. This method doesn't consider the profile as a group.
329 *
330 * @param userID
331 * the user
332 * @param page
333 * The page to be returned
334 * @return the list of groups
335 * @throws IdentityManagerException
336 * if the group's users can't be found
337 */
338 public Map<String, IDIFGroup> getUserGroupsPagination(String userID, Pagination page)
339 throws IdentityManagerException;
340
341 // --------- Group operations ---------
342
343 /**
344 * Returns the list of user IDs of a given group
345 *
346 * @param groupID
347 * the group
348 * @return the list of users
349 * @throws IdentityManagerException
350 * if the operation can't be executed
351 */
352 public Set<String> getUserIDsInGroup(String groupID) throws IdentityManagerException;
353
354 /**
355 * Gets the user login attribute name
356 *
357 * @return The string containing the attribute name.
358 */
359 public String getUserLoginAttributeName();
360
361 /**
362 * Gets a given parameter from a given user.
363 *
364 * @param userID
365 * @param parameterID
366 * @return the parameter value if it exists, null otherwise
367 */
368 public Object getUserParameter(String userID, String parameterID);
369
370 /**
371 * Gets all the parameters from a given user.
372 *
373 * @param userID
374 * the user ID
375 * @return the parameters map if it exists, null otherwise
376 */
377 public Map<String, Object> getUserParameters(String userID);
378
379 /**
380 * Returns the user parent group attribute name
381 *
382 * @return A string containing the user parent group attribute name
383 */
384 public String getUserParentGroupAttributeName();
385
386 /**
387 * Returns a subset of all users in the system, according to the parameters
388 *
389 * @param page
390 * The required page
391 * @return A set of users containing the specified subset
392 * @throws IdentityManagerException
393 * If the operation can't be executed
394 */
395 public Set<IDIFUser> getUsers(Pagination page) throws IdentityManagerException;
396
397 // --------- Relation operations ---------
398
399 /**
400 * Returns the list of users with a given attribute value.<br/>
401 * Supports partial matches by adding "%" or "*" before and/or after the attribute value
402 *
403 * @param attribute
404 * the attribute to search
405 * @param value
406 * the value for the attribute
407 * @return the LDAPUser with the given login name
408 * @throws IdentityManagerException
409 * if the operation cannot be executed
410 */
411 public Set<IDIFUser> getUsersByAttribute(String attribute, String value) throws IdentityManagerException;
412
413 /**
414 * Get users that match specified attributes.<br/>
415 * Supports partial matches by adding "%" or "*" before and/or after the attribute value
416 *
417 * @param attributes
418 * A map of attributes to be searched, where the keys are the attribute names, and the values are the
419 * attribute values.
420 * @return A set containing the users that obey all of the specified criteria
421 * @throws IdentityManagerException
422 * If the operation can't be executed
423 */
424 public Set<IDIFUser> getUsersByAttributes(Map<String, String> attributes) throws IdentityManagerException;
425
426 /**
427 * Get users that match specified attributes.<br/>
428 * Supports partial matches by adding "%" or "*" before and/or after the attribute value
429 *
430 * @param attributes
431 * A map of attributes to be searched, where the keys are the attribute names, and the values are the
432 * attribute values.
433 * @param page
434 * The page to be obtained
435 * @return A set containing the users that obey all of the specified criteria
436 * @throws IdentityManagerException
437 * If the operation can't be executed
438 */
439 public Set<IDIFUser> getUsersByAttributes(Map<String, String> attributes, Pagination page)
440 throws IdentityManagerException;
441
442 /**
443 * Returns the list of users with a given email attribute value.
444 *
445 * @param value
446 * the value for the attribute email
447 * @return the LDAPUser with the given login name
448 * @throws IdentityManagerException
449 * if the operation cannot be executed
450 */
451 public Set<IDIFUser> getUsersByEmail(String value) throws IdentityManagerException;
452
453 /**
454 * Checks if a group exists on the manager.
455 *
456 * @param groupID
457 * the ID of the group
458 * @return T if the group exists, F otherwise
459 * @throws IdentityManagerException
460 * if the operation can't be executed
461 */
462 public boolean groupExists(String groupID) throws IdentityManagerException;
463
464 /**
465 * Checks if the supplied password matches the one defined for a user with a given ID.
466 *
467 * @param userID
468 * the user ID
469 * @param suppliedPassword
470 * the supplied user password
471 * @return T if user if its identity is valid, F otherwise
472 * @throws IdentityManagerException
473 * if the group can't be added as member of the parent group
474 */
475 public boolean isIdentityValid(String userID, String suppliedPassword) throws IdentityManagerException;
476
477 /**
478 * Get the ldap readOnly configuration value.
479 *
480 * @return true or false
481 */
482 public boolean isReadOnly();
483
484 /**
485 * Checks if a given user belongs to a given group.
486 *
487 * @param userID
488 * the user ID
489 * @param groupID
490 * the group ID
491 * @return T if the user belongs to the group, F otherwise
492 * @throws IdentityManagerException
493 * if the operation can't be executed
494 */
495 public boolean isUserInGroup(String userID, String groupID) throws IdentityManagerException;
496
497 /**
498 * Checks if a given user belongs to a given group.
499 *
500 * @param userID
501 * the user ID
502 * @param groupID
503 * the group ID
504 * @param parseGroupHierarchy
505 * contemplates the group Hierarchy
506 * @return T if the user belongs to the group, F otherwise
507 * @throws IdentityManagerException
508 * if the operation can't be executed
509 */
510 public boolean isUserInGroup(String userID, String groupID, boolean parseGroupHierarchy)
511 throws IdentityManagerException;
512
513 // --------- Identity manager related operations ---------
514
515 /**
516 * Removes an existing group from the manager, if it exists.
517 *
518 * @param groupID
519 * the id of the group to remove
520 * @throws IdentityManagerException
521 * if the group can't be removed
522 */
523 public void removeGroup(String groupID) throws IdentityManagerException;
524
525 /**
526 * Removes an existing user from the manager, if it exists.
527 *
528 * @param userID
529 * the id of the user to remove
530 * @throws IdentityManagerException
531 * if the user can't be removed
532 */
533 public void removeUser(String userID) throws IdentityManagerException;
534
535 /**
536 * Removes an existing user from an existing group.
537 *
538 * @param groupID
539 * the group ID
540 * @param userID
541 * the user ID
542 * @throws IdentityManagerException
543 * if the user can't be removed from the group
544 */
545 public void removeUserFromGroup(String userID, String groupID) throws IdentityManagerException;
546
547 /**
548 * Removes a given parameter from a given user.
549 *
550 * @param userID
551 * the user ID
552 * @param parameterID
553 * the parameter ID
554 */
555 public void removeUserParameter(String userID, String parameterID);
556
557 /** Resets the identity manager. Different implementations will offer distinct types of reset. */
558 public void resetIdentityManager();
559
560 /**
561 * Sets an user parameter.
562 *
563 * @param userID
564 * the user ID
565 * @param parameterID
566 * the parameter ID
567 * @param parameterValue
568 * the parameter value
569 */
570 public void setUserParameter(String userID, String parameterID, Object parameterValue);
571
572 /**
573 * Sets the user parameters as an whole.
574 *
575 * @param userID
576 * the user ID
577 * @param parametersMap
578 * the parameters map
579 */
580 public void setUserParameters(String userID, Map<String, Object> parametersMap);
581
582 /**
583 * Updates an existing group. Does nothing if the group doesn't exist.
584 *
585 * @param existingGroup
586 * the group to update
587 * @throws IdentityManagerException
588 * if the group can't be updated
589 */
590 public void updateGroup(IDIFGroup existingGroup) throws IdentityManagerException;
591
592 /**
593 * Updates an existing user. Does nothing if the user doesn't exist.
594 *
595 * @param existingUser
596 * the user to update
597 * @param userID
598 * the user ID (must be supplied separately to ensure data integrity if the user ID is changed)
599 * @throws IdentityManagerException
600 * if the operation can't be executed
601 */
602 public void updateUser(IDIFUser existingUser, String userID) throws IdentityManagerException;
603
604 /**
605 * Updates an attribute value on a given user and persists it.
606 *
607 * @param userID
608 * the ID of the user to update
609 * @param attributeID
610 * the ID of the attribute to update
611 * @param attributeValue
612 * the value of the attribute to update
613 * @throws IdentityManagerException
614 * if the attribute can't be updated
615 */
616 public void updateUserAttribute(String userID, String attributeID, Object attributeValue)
617 throws IdentityManagerException;
618
619 /**
620 * Updates all of the user's attributes.
621 *
622 * @param userID
623 * the ID of the user to update
624 * @param attributes
625 * the attributes to update
626 * @throws IdentityManagerException
627 * if the attribute can't be updated
628 */
629 public void updateUserAttributes(String userID, Map<String, Object> attributes) throws IdentityManagerException;
630
631 /**
632 * Checks if a user exists on the manager.
633 *
634 * @param userID
635 * the ID of the user
636 * @return T if the user exists, F otherwise
637 * @throws IdentityManagerException
638 * if the operation can't be executed
639 */
640 public boolean userExists(String userID) throws IdentityManagerException;
641
642 }