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