View Javadoc

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