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