1 package com.atlassian.sal.api.user;
2
3 import java.security.Principal;
4 import javax.annotation.Nullable;
5 import javax.servlet.http.HttpServletRequest;
6
7 /**
8 * Interface providing user based operations across various apps.
9 *
10 * @since 2.0
11 */
12 @SuppressWarnings ("UnusedDeclaration")
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 {@link #getRemoteUsername(HttpServletRequest)}.
17 *
18 * @return The user name of the logged in user or null
19 * @deprecated since 2.10, use {@link #getRemoteUser()} or {@link #getRemoteUserKey()} instead
20 */
21 @Deprecated
22 @Nullable
23 String getRemoteUsername();
24
25 /**
26 * Returns the profile of the currently logged in user or null if no user can be found.
27 * <p/>
28 * Getting the full {@link UserProfile} may have performance implications in some applications. Consider using {@link #getRemoteUserKey()} if you don't need the full object.
29 *
30 * @return the {@link UserProfile} of the logged in user or null
31 * @see #getRemoteUserKey()
32 * @since 2.10
33 */
34 @Nullable
35 UserProfile getRemoteUser();
36
37 /**
38 * Returns the key of the currently logged in user or null if no user can be found.
39 *
40 * @return the {@link UserKey} of the logged in user or null
41 * @see #getRemoteUser()
42 * @since 2.10
43 */
44 @Nullable
45 UserKey getRemoteUserKey();
46
47 /**
48 * Returns the username of the currently logged in user or null if no user can be found.
49 * <p/>
50 * * Note: Implementing applications might not actually be using the {@link HttpServletRequest}, but actually using an internal {@link ThreadLocal} authentication context.
51 * @param request The request to retrieve the username from
52 * @return The user name of the logged in user or null
53 * @deprecated since 2.10, use {@link #getRemoteUser(javax.servlet.http.HttpServletRequest)} instead.
54 */
55 @Deprecated
56 @Nullable
57 String getRemoteUsername(HttpServletRequest request);
58
59 /**
60 * Returns the {@link UserProfile} of the currently logged in user or null if no user can be found.
61 * <p/>
62 * Getting the full {@link UserProfile} may have performance implications in some applications. Consider using {@link #getRemoteUserKey()} if you don't need the full object.
63 * <p/>
64 * * Note: Implementing applications might not actually be using the {@link HttpServletRequest}, but actually using an internal {@link ThreadLocal} authentication context.
65 * @param request The request to retrieve the username from
66 * @return The currently logged in user or null
67 * @see #getRemoteUser()
68 * @see #getRemoteUserKey(javax.servlet.http.HttpServletRequest)
69 * @since 2.10
70 */
71 @Nullable
72 UserProfile getRemoteUser(HttpServletRequest request);
73
74 /**
75 * Returns the {@link UserKey} of the currently logged in user or null if no user can be found.
76 * <p/>
77 * Note: Implementing applications might not actually be using the {@link HttpServletRequest}, but actually using an internal {@link ThreadLocal} authentication context.
78 *
79 * @param request The request to retrieve the username from
80 * @return The key of the currently logged in user or null
81 * @see #getRemoteUserKey()
82 * @see #getRemoteUser(javax.servlet.http.HttpServletRequest)
83 * @since 2.10
84 */
85 @Nullable
86 UserKey getRemoteUserKey(HttpServletRequest request);
87
88 /**
89 * Returns a {@code UserProfile object} for the specified user or null if no user can be found
90 *
91 * @param username The username of the user whose profile is requested
92 * @return The user's profile or null
93 * @since 2.2.0
94 */
95 @Nullable
96 UserProfile getUserProfile(@Nullable String username);
97
98 /**
99 * Returns a {@code UserProfile object} for the specified user or null if no user can be found
100 *
101 * @param userKey The userKey of the user whose profile is requested
102 * @return The user's profile or null
103 * @since 2.10
104 */
105 @Nullable
106 UserProfile getUserProfile(@Nullable UserKey userKey);
107
108 /**
109 * Returns whether the user is in the specify group
110 *
111 * @param username The username to check
112 * @param group The group to check
113 * @return {@code true} if the user is in the specified group
114 * @deprecated since 2.10, use {@link #isUserInGroup(UserKey, String)} instead
115 */
116 @Deprecated
117 boolean isUserInGroup(@Nullable String username, @Nullable String group);
118
119 /**
120 * Returns whether the given user is in the given group
121 *
122 * @param userKey The user
123 * @param group The group
124 * @return {@code true} if the user is in the specified group
125 * @since 2.10
126 */
127 boolean isUserInGroup(@Nullable UserKey userKey, @Nullable String group);
128
129 /**
130 * Returns {@code true} or {@code false} depending on whether a user has been granted the system administrator permission. A system administrator has full administrative permissions in the
131 * application, including permission to perform operations that may affect the underlying operating system, such as specifying filesystem paths, installing plugins, configuring mail servers and
132 * logging, performing backups and restores, etc. Only check for system administrator when performing this type of operation. Operations that do not affect the underlying system should use {@link
133 * #isAdmin(String)} instead.
134 *
135 * @param username The username of the user to check
136 * @return {@code true} or {@code false} depending on whether a user has been granted the system admin permission.
137 * @see <a href="http://confluence.atlassian.com/display/JIRA/Managing+Global+Permissions#ManagingGlobalPermissions-About%27JIRASystemAdministrators%27and%27JIRAAdministrators%27">About 'JIRA
138 * System Administrators' and 'JIRA Administrators'</a>
139 * @see <a href="http://confluence.atlassian.com/display/DOC/Global+Permissions+Overview#GlobalPermissionsOverview-confluenceadmin">Comparing the System Administrator with the Confluence
140 * Administrator Permission</a>
141 * @deprecated since 2.10, use {@link #isSystemAdmin(UserKey)} instead
142 */
143 @Deprecated
144 boolean isSystemAdmin(@Nullable String username);
145
146 /**
147 * Returns {@code true} or {@code false} depending on whether a user has been granted the system administrator permission. A system administrator has full administrative permissions in the
148 * application, including permission to perform operations that may affect the underlying operating system, such as specifying filesystem paths, installing plugins, configuring mail servers and
149 * logging, performing backups and restores, etc. Only check for system administrator when performing this type of operation. Operations that do not affect the underlying system should use {@link
150 * #isAdmin(String)} instead.
151 *
152 * @param userKey The key of the user to check
153 * @return {@code true} or {@code false} depending on whether a user has been granted the system admin permission.
154 * @see <a href="http://confluence.atlassian.com/display/JIRA/Managing+Global+Permissions#ManagingGlobalPermissions-About%27JIRASystemAdministrators%27and%27JIRAAdministrators%27">About 'JIRA
155 * System Administrators' and 'JIRA Administrators'</a>
156 * @see <a href="http://confluence.atlassian.com/display/DOC/Global+Permissions+Overview#GlobalPermissionsOverview-confluenceadmin">Comparing the System Administrator with the Confluence
157 * Administrator Permission</a>
158 * @since 2.10
159 */
160 boolean isSystemAdmin(@Nullable UserKey userKey);
161
162 /**
163 * Returns {@code true} or {@code false} depending on whether a user has been granted the administrator permission. An administrator may have restricted administrative permissions that only apply
164 * to application-level configuration that cannot affect the underlying operating system. Only check for administrator permission when performing this type of operation. Operations that can affect
165 * security, the filesystem, or allow arbitrary code execution must check {@link #isSystemAdmin(String)} instead.
166 * <p/>
167 * Note that system administrator permission implies administrator permission. That is, any username for which {@code userManager.isSystemAdmin(username)} returns {@code true} will also return
168 * {@code true} for {@code userManager.isAdmin(username)}.
169 *
170 * @param username The username of the user to check
171 * @return {@code true} or {@code false} depending on whether the user has been granted the admin permission
172 * @see <a href="http://confluence.atlassian.com/display/JIRA/Managing+Global+Permissions#ManagingGlobalPermissions-About%27JIRASystemAdministrators%27and%27JIRAAdministrators%27">About 'JIRA
173 * System Administrators' and 'JIRA Administrators'</a>
174 * @see <a href="http://confluence.atlassian.com/display/DOC/Global+Permissions+Overview#GlobalPermissionsOverview-confluenceadmin">Comparing the System Administrator with the Confluence
175 * Administrator Permission</a>
176 * @deprecated since 2.10, use {@link #isAdmin(UserKey)} instead
177 */
178 @Deprecated
179 boolean isAdmin(@Nullable String username);
180
181 /**
182 * Returns {@code true} or {@code false} depending on whether a user has been granted the administrator permission. An administrator may have restricted administrative permissions that only apply
183 * to application-level configuration that cannot affect the underlying operating system. Only check for administrator permission when performing this type of operation. Operations that can affect
184 * security, the filesystem, or allow arbitrary code execution must check {@link #isSystemAdmin(String)} instead.
185 * <p/>
186 * Note that system administrator permission implies administrator permission. That is, any username for which {@code userManager.isSystemAdmin(username)} returns {@code true} will also return
187 * {@code true} for {@code userManager.isAdmin(username)}.
188 *
189 * @param userKey The user of the user to check
190 * @return {@code true} or {@code false} depending on whether the user has been granted the admin permission
191 * @see <a href="http://confluence.atlassian.com/display/JIRA/Managing+Global+Permissions#ManagingGlobalPermissions-About%27JIRASystemAdministrators%27and%27JIRAAdministrators%27">About 'JIRA
192 * System Administrators' and 'JIRA Administrators'</a>
193 * @see <a href="http://confluence.atlassian.com/display/DOC/Global+Permissions+Overview#GlobalPermissionsOverview-confluenceadmin">Comparing the System Administrator with the Confluence
194 * Administrator Permission</a>
195 * @since 2.10
196 */
197 boolean isAdmin(@Nullable UserKey userKey);
198
199 /**
200 * Given a username & password, this method checks whether or not the provided user can be authenticated
201 *
202 * @param username Username of the user
203 * @param password Password of the user
204 * @return {@code true} if the user can be authenticated, {@code false} otherwise
205 */
206 boolean authenticate(String username, String password);
207
208 /**
209 * Returns the user that made this request or {@code null} if this application does not have such a user.
210 *
211 * @param username Username of the user a consumer is making a request on behalf of
212 * @return {@code Principal} corresponding to the username, {@code null} if the user does not exist
213 * @throws UserResolutionException thrown if there is a problem resolving the user, such as a failure when accessing an external user store
214 */
215 @Nullable
216 Principal resolve(String username) throws UserResolutionException;
217
218 /**
219 * Returns a list of group names.
220 *
221 * @param prefix only return groups with names matching this prefix
222 * @param startIndex don't return the first startIndex results
223 * @param maxResults return at most this many results
224 * @return an Iterable of names of groups
225 */
226 Iterable<String> findGroupNamesByPrefix(String prefix, int startIndex, int maxResults);
227 }