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 }