1 package com.atlassian.sal.api.user;
2
3 import java.security.Principal;
4 import java.util.List;
5
6 import javax.servlet.http.HttpServletRequest;
7
8 /**
9 * Interface providing user based operations across various apps.
10 *
11 * @since 2.0
12 */
13 public interface UserManager
14 {
15 /**
16 * Returns the username of the currently logged in user or null if no user can be found. If possible, please use
17 * {@link #getRemoteUsername(HttpServletRequest)}.
18 *
19 * @return The user name of the logged in user or null
20 */
21 String getRemoteUsername();
22
23 /**
24 * Returns the username of the currently logged in user or null if no user can be found.
25 *
26 * @param request The request to retrieve the username from
27 * @return The user name of the logged in user or null
28 */
29 String getRemoteUsername(HttpServletRequest request);
30
31 /**
32 * Returns a {@code UserProfile object} for the specified user or null if no user can be found
33 * @param username The username of the user whose profile is requested
34 * @return The user's profile or null
35 * @since 2.2.0
36 */
37 UserProfile getUserProfile(String username);
38
39 /**
40 * Returns whether the user is in the specify group
41 *
42 * @param username The username to check
43 * @param group The group to check
44 * @return {@code true} if the user is in the specified group
45 */
46 boolean isUserInGroup(String username, String group);
47
48 /**
49 * Returns {@code true} or {@code false} depending on whether a user has been granted the system administrator
50 * permission. A system administrator has full administrative permissions in the application, including permission
51 * to perform operations that may affect the underlying operating system, such as specifying filesystem paths,
52 * installing plugins, configuring mail servers and logging, performing backups and restores, etc. Only check for
53 * system administrator when performing this type of operation. Operations that do not affect the underlying system
54 * should use {@link #isAdmin(String)} instead.
55 *
56 * @param username The username of the user to check
57 * @return {@code true} or {@code false} depending on whether a user has been granted the system admin permission.
58 * @see <a href="http://confluence.atlassian.com/display/JIRA/Managing+Global+Permissions#ManagingGlobalPermissions-About%27JIRASystemAdministrators%27and%27JIRAAdministrators%27">About 'JIRA System Administrators' and 'JIRA Administrators'</a>
59 * @see <a href="http://confluence.atlassian.com/display/DOC/Global+Permissions+Overview#GlobalPermissionsOverview-confluenceadmin">Comparing the System Administrator with the Confluence Administrator Permission</a>
60 */
61 boolean isSystemAdmin(String username);
62
63 /**
64 * Returns {@code true} or {@code false} depending on whether a user has been granted the administrator permission.
65 * An administrator may have restricted administrative permissions that only apply to application-level
66 * configuration that cannot affect the underlying operating system. Only check for administrator permission when
67 * performing this type of operation. Operations that can affect security, the filesystem, or allow arbitrary code
68 * execution must check {@link #isSystemAdmin(String)} instead.
69 * <p/>
70 * Note that system administrator permission implies administrator permission. That is, any username for which
71 * {@code userManager.isSystemAdmin(username)} returns {@code true} will also return {@code true} for
72 * {@code userManager.isAdmin(username)}.
73 *
74 * @param username The username of the user to check
75 * @return {@code true} or {@code false} depending on whether the user has been granted the admin permission
76 * @see <a href="http://confluence.atlassian.com/display/JIRA/Managing+Global+Permissions#ManagingGlobalPermissions-About%27JIRASystemAdministrators%27and%27JIRAAdministrators%27">About 'JIRA System Administrators' and 'JIRA Administrators'</a>
77 * @see <a href="http://confluence.atlassian.com/display/DOC/Global+Permissions+Overview#GlobalPermissionsOverview-confluenceadmin">Comparing the System Administrator with the Confluence Administrator Permission</a>
78 */
79 boolean isAdmin(String username);
80
81 /**
82 * Given a username & password, this method checks whether or not the provided user can
83 * be authenticated
84 *
85 * @param username Username of the user
86 * @param password Password of the user
87 * @return {@code true} if the user can be authenticated, {@code false} otherwise
88 */
89 boolean authenticate(String username, String password);
90
91 /**
92 * Returns the user that made this request or {@code null} if this application does not have such a user.
93 *
94 * @param username Username of the user a consumer is making a request on behalf of
95 * @return {@code Principal} corresponding to the username, {@code null} if the user does not exist
96 * @throws UserResolutionException thrown if there is a problem resolving the user, such as a failure when accessing
97 * an external user store
98 */
99 Principal resolve(String username) throws UserResolutionException;
100
101 /**
102 * Returns a list of group names.
103 *
104 * @param prefix only return groups with names matching this prefix
105 * @param startIndex don't return the first startIndex results
106 * @param maxResults return at most this many results
107 * @return an Iterable of names of groups
108 */
109 Iterable<String> findGroupNamesByPrefix(String prefix, int startIndex, int maxResults);
110 }