com.atlassian.bitbucket.user

Interface UserAdminService

public interface UserAdminService

Provides methods for querying, creating and updating users and groups.

Many of the queries provided by this service are also provided by UserService. The queries provided here are specifically geared toward administration, retrieving detailed groups and detailed groups. For non-administrative usages, like group and user pickers, the "normal" queries from UserService should be used instead.

See Also:

UserService

Method Summary

Modifier and Type	Method and Description
void	addMembersToGroup(String groupName, Set<String> usernames) Adds one or more users to a group.
void	addUserToGroups(String username, Set<String> groupNames) Adds a user to one or more groups.
boolean	canCreateGroups() Retrieves a flag indicating whether it is possible to create a group.
boolean	canCreateUsers() Retrieves a flag indicating whether it is possible to create a user.
boolean	canDeleteGroups() Retrieves a flag indicating whether it is possible to delete a group.
boolean	canUpdateGroups() Retrieves a flag indicating whether it is possible to update groups.
void	clearCaptchaChallenge(String username) Clears any CAPTCHA challenge that may constrain the user with the supplied username when they authenticate.
DetailedGroup	createGroup(String groupName) Creates a new group.
ServiceUser	createServiceUser(ServiceUserCreateRequest userRequest) Creates a new service user.
void	createUser(String username, String password, String displayName, String emailAddress) Creates a new user and adds them to the default group, if it exists.
void	createUser(String username, String password, String displayName, String emailAddress, boolean addToDefaultGroup) Creates a new user and optionally adds them to the default group, if it exists.
void	createUserWithGeneratedPassword(String username, String displayName, String emailAddress) Creates a new user with a randomly-generated password.
DetailedGroup	deleteGroup(String groupName) Deletes a group.
DetailedUser	deleteUser(String username) Deletes a user.
String	eraseUser(String username) Erases personally identifying user data for a deleted user.
Page<DetailedGroup>	findGroups(PageRequest pageRequest) Retrieves a page of groups with full details.
Page<DetailedGroup>	findGroupsByName(String groupName, PageRequest pageRequest) Retrieves a page of groups with full details, optionally filtering the returned results to those containing the specified groupName.
Page<DetailedGroup>	findGroupsWithoutUser(String username, String groupName, PageRequest pageRequest) Retrieves a page of groups which the specified user is not a member of, with full details, optionally filtering the returned results to those containing the specified groupName.
Page<DetailedGroup>	findGroupsWithUser(String username, String groupName, PageRequest pageRequest) Retrieves a page of groups which the specified user is a member of, with full details, optionally filtering the returned results to those containing the specified groupName.
DetailedUser	findUserByPasswordResetToken(String token) Find a password reset request using the token generated by requestPasswordReset(String).
Page<DetailedUser>	findUsers(PageRequest pageRequest) Retrieves a page of users with full details.
Page<DetailedUser>	findUsersByName(String username, PageRequest pageRequest) Retrieves a page of users, optionally filtering the returned results to those containing the specified username.
Page<DetailedUser>	findUsersWithGroup(String groupName, String username, PageRequest pageRequest) Find the users within a group that match the page request.
Page<DetailedUser>	findUsersWithoutGroup(String groupName, String username, PageRequest pageRequest) Find the users outside a group that match the page request.
DetailedUser	getUserDetails(ApplicationUser user) Retrieves full details for the specified user.
DetailedUser	getUserDetails(String username) Retrieves full details for the user with the specified username, or null if no such user exists.
boolean	newUserCanResetPassword() Retrieves a flag indicating whether the new user is able to set a password or not
void	removeUserFromGroup(String groupName, String username) Removes a user from a group.
DetailedUser	renameUser(String currentUsername, String newUsername) Change the name of a user
void	requestPasswordReset(String username) Generates a unique token which can be used to perform a password reset for the specified user and e-mails it to the address associated with their account.
void	resetPassword(String token, String password) Resets the password for the user associated with the specified token to the provided value.
void	updatePassword(String username, String newPassword) Updates the password of the specified user.
ServiceUser	updateServiceUser(ServiceUserUpdateRequest request) Updates the details of the specified user
DetailedUser	updateUser(String username, String displayName, String emailAddress) Updates the display name and e-mail address of the specified user.
void	validateErasable(String username) Validate if a username can be erased.

Method Detail

addUserToGroups

void addUserToGroups(@Nonnull
                     String username,
                     @Nonnull
                     Set<String> groupNames)
              throws ForbiddenException,
                     LicenseLimitException,
                     NoSuchGroupException,
                     NoSuchUserException

Adds a user to one or more groups.

Parameters:

username - name of the user who will receive the new group memberships

groupNames - names of the groups to add to the user

Throws:

ForbiddenException - if one of the groups would grant SYS_ADMIN permission and the current user isn't a SYS_ADMIN; only SYS_ADMINs can grant SYS_ADMIN permission

LicenseLimitException - if one of the groups would grant LICENSED_USER permission to more users than the active license allows

NoSuchGroupException - if any of the specified groups does not exist

NoSuchUserException - if the specified user does not exist

addMembersToGroup

void addMembersToGroup(@Nonnull
                       String groupName,
                       @Nonnull
                       Set<String> usernames)
                throws ForbiddenException,
                       LicenseLimitException,
                       NoSuchGroupException,
                       NoSuchUserException

Adds one or more users to a group.

Parameters:

groupName - names of the group to which the users will be added

usernames - names of the users who will receive the new group membership

Throws:

ForbiddenException - if the group would grant SYS_ADMIN permission and the current user isn't a SYS_ADMIN; only SYS_ADMINs can grant SYS_ADMIN permission

LicenseLimitException - if the additions would grant LICENSED_USER permission to more users than the active license allows

NoSuchGroupException - if the specified group does not exist

NoSuchUserException - if any of the specified users does not exist

canCreateGroups

boolean canCreateGroups()

Retrieves a flag indicating whether it is possible to create a group.

Returns:

true if any directory exists in which a group can be created; otherwise, false

canUpdateGroups

boolean canUpdateGroups()

Retrieves a flag indicating whether it is possible to update groups.

Returns:

true if any directory exists in which a group can be updated; otherwise, false

canCreateUsers

boolean canCreateUsers()

Retrieves a flag indicating whether it is possible to create a user.

Returns:

true if any directory exists in which a user can be created; otherwise, false

canDeleteGroups

boolean canDeleteGroups()

Retrieves a flag indicating whether it is possible to delete a group.

Returns:

true if any directory exists in which a group can be deleted; otherwise false

newUserCanResetPassword

boolean newUserCanResetPassword()

Retrieves a flag indicating whether the new user is able to set a password or not

Returns:

true if user is able to set a password; otherwise false

clearCaptchaChallenge

void clearCaptchaChallenge(@Nonnull
                           String username)

Clears any CAPTCHA challenge that may constrain the user with the supplied username when they authenticate. Additionally any counter or metric that contributed towards the user being issued the CAPTCHA challenge (for instance too many consecutive failed logins) will also be reset.

Parameters:

username - the user whose CAPTCHA challenge should be cleared

createGroup

@Nonnull
DetailedGroup createGroup(@Nonnull
                                   String groupName)
                            throws IntegrityException

Creates a new group.

Parameters:

groupName - the name for the new group

Returns:

the new group

Throws:

IntegrityException - if a group with the same already exists

createServiceUser

@Nonnull
ServiceUser createServiceUser(@Nonnull
                                       ServiceUserCreateRequest userRequest)
                                throws IntegrityException

Creates a new service user. Service users cannot be added to any groups. The user is created without any permissions.

It is suggested that consumers use the ID of the user created as the foreign key for related content because their name, slug and other properties can be updated.

Parameters:

userRequest - the user's details

Returns:

the newly created service user

Throws:

IntegrityException - if a service user with the provided username already exists

createUser

void createUser(@Nonnull
                String username,
                @Nonnull
                String password,
                @Nonnull
                String displayName,
                @Nonnull
                String emailAddress)
         throws IntegrityException,
                LicenseLimitException

Creates a new user and adds them to the default group, if it exists. If the user should be created without being added to the default group, use createUser(String, String, String, String, boolean) instead.

A non-null, non-blank password must be provided. It may be further vetted by the user store, for example by applying complexity restrictions. Alternatively, if an e-mail server has been configured, new users can be created with generated passwords, allowing new users to set their own password when they first access the system.

Parameters:

username - the username for the new user

password - the user's initial password, which may not be null or empty

displayName - the display name for the new user

emailAddress - the e-mail address for the new user

Throws:

IntegrityException - if a user with the same username already exists

LicenseLimitException - if the new user can not be added to the default group because it would grant LICENSED_USER permission to more users than the active license allows

See Also:

createUser(String, String, String, String, boolean)

createUser

void createUser(@Nonnull
                String username,
                @Nonnull
                String password,
                @Nonnull
                String displayName,
                @Nonnull
                String emailAddress,
                boolean addToDefaultGroup)
         throws IntegrityException,
                LicenseLimitException

Creates a new user and optionally adds them to the default group, if it exists.

A non-null, non-blank password must be provided. It may be further vetted by the user store, for example by applying complexity restrictions. Alternatively, if an e-mail server has been configured, new users can be created with generated passwords, allowing new users to set their own password when they first access the system.

This method is not intended to be exposed via services like REST for general consumption. It exists to satisfy specific use cases where the system, or a plugin, may wish to create a user without adding them to the default group. Generally it is expected that new users should be added to the default group, as it defines the set of "common" permissions for all users of the system.

Parameters:

username - the username for the new user

password - the user's initial password, which may not be null or empty

displayName - the display name for the new user

emailAddress - the e-mail address for the new user

addToDefaultGroup - true if the new user should be added to the default group

Throws:

IntegrityException - if a user with the same username already exists

LicenseLimitException - if the new user can not be added to the default group because it would grant LICENSED_USER permission to more users than the active license allows

See Also:

createUser(String, String, String, String)

createUserWithGeneratedPassword

void createUserWithGeneratedPassword(@Nonnull
                                     String username,
                                     @Nonnull
                                     String displayName,
                                     @Nonnull
                                     String emailAddress)
                              throws IntegrityException,
                                     LicenseLimitException,
                                     MailException

Creates a new user with a randomly-generated password. An e-mail notification will be sent to the new user's e-mail address with instructions on how to reset their password and finish activating their account.

Parameters:

username - the username for the new user

displayName - the display name for the new user

emailAddress - the e-mail address for the new user

Throws:

IntegrityException - if a user with the same username already exists or if the user will be created in a directory that does not allow passwords to be reset

LicenseLimitException - if the new user can not be added to the default group because it would grant LICENSED_USER permission to more users than the active license allows

MailException - if the e-mail notification could not be sent to the created user to allow them to set their initial password

NoMailHostConfigurationException - if no e-mail server has been configured

deleteGroup

@Nonnull
DetailedGroup deleteGroup(@Nonnull
                                   String groupName)
                            throws ForbiddenException,
                                   IntegrityException,
                                   NoSuchGroupException

Deletes a group. Deleting a group will also revoke all permissions which had been granted to that group.

Note: Future releases may remove the return value from this method. For best portability across versions, the return value for this method should not be used.

Parameters:

groupName - the name of the group to delete

Returns:

details for the deleted group

Throws:

ForbiddenException - if the group grants SYS_ADMIN permission but the current user is not a SYS_ADMIN

IntegrityException - if deleting the group would revoke the ADMIN or SYS_ADMIN permissions of the current user

NoSuchGroupException - if the group does not exist

deleteUser

@Nonnull
DetailedUser deleteUser(@Nonnull
                                 String username)
                          throws ForbiddenException,
                                 IntegrityException,
                                 NoSuchUserException

Deletes a user. Deleting a user will also revoke all permissions which had been granted to that user, as well as invalidating any cached authentication tokens they may have.

Note: Future releases may remove the return value from this method. For best portability across versions, the return value for this method should not be used.

Parameters:

username - the username of the user to delete

Returns:

details for the deleted user

Throws:

ForbiddenException - if the user to delete is a SYS_ADMIN and the current user is not

IntegrityException - if the user to delete is the current user

NoSuchUserException - if the user does not exist

eraseUser

@Nonnull
String eraseUser(@Nonnull
                          String username)
                   throws IllegalUserStateException,
                          NoSuchUserException,
                          UserErasureException

Erases personally identifying user data for a deleted user. References in the application to the original username will be either removed or updated to a new non-identifying username.

A UserErasedEvent is then raised once erasure has completed.

Erasing user data is irreversible and may lead to a degraded user experience. This method should not be used as part of a standard user deletion and cleanup process.

Parameters:

username - the username of the user to erase data for

Returns:

the new identifier for the erased user

Throws:

IllegalUserStateException - if the supplied username is the username of a non-deleted user

NoSuchUserException - if the supplied username does not exist

UserErasureException - if some of the delegated user erasure operations failed

Since:

5.16

See Also:

UserErasedEvent

findGroups

@Nonnull
Page<DetailedGroup> findGroups(@Nonnull
                                        PageRequest pageRequest)

Retrieves a page of groups with full details.

Note: To filter the retrieved groups by name, use findGroupsByName(String, PageRequest) instead.

Parameters:

pageRequest - defines the page of groups to retrieve

Returns:

the requested page of groups, which may be empty but never null

See Also:

findGroupsByName(String, PageRequest), UserService.findGroups(PageRequest)

findGroupsByName

@Nonnull
Page<DetailedGroup> findGroupsByName(@Nullable
                                              String groupName,
                                              @Nonnull
                                              PageRequest pageRequest)

Retrieves a page of groups with full details, optionally filtering the returned results to those containing the specified groupName. If the provided groupName is null, this method behaves identically to findGroups(PageRequest).

Parameters:

groupName - 0 or more characters to apply as a filter on returned groups

pageRequest - defines the page of groups to retrieve

Returns:

the requested page of groups, potentially filtered, which may be empty but never null

See Also:

findGroups(PageRequest), UserService.findGroupsByName(String, PageRequest)

findGroupsWithUser

@Nonnull
Page<DetailedGroup> findGroupsWithUser(@Nonnull
                                                String username,
                                                @Nullable
                                                String groupName,
                                                @Nonnull
                                                PageRequest pageRequest)

Retrieves a page of groups which the specified user is a member of, with full details, optionally filtering the returned results to those containing the specified groupName. If the provided groupName is null or empty groups will not be filtered. If no user exists with the specified username, no groups will be returned.

Parameters:

username - the exact name of the user to retrieve groups for

groupName - 0 or more characters to apply as a filter on returned groups

pageRequest - defines the page of groups to retrieve

Returns:

the requested page of groups, which may be empty but never null

See Also:

findGroupsWithoutUser(String, String, PageRequest), findUsersWithGroup(String, String, PageRequest), UserService.findGroupsByUser(String, PageRequest)

findGroupsWithoutUser

@Nonnull
Page<DetailedGroup> findGroupsWithoutUser(@Nonnull
                                                   String username,
                                                   @Nullable
                                                   String groupName,
                                                   @Nonnull
                                                   PageRequest pageRequest)

Retrieves a page of groups which the specified user is not a member of, with full details, optionally filtering the returned results to those containing the specified groupName. If the provided groupName is null or empty groups will not be filtered. If no user exists with the specified username, no groups will be returned.

Parameters:

username - the exact name of the user to retrieve groups for

groupName - 0 or more characters to apply as a filter on returned groups

pageRequest - defines the page of groups to retrieve

Returns:

the requested page of groups, which may be empty but never null

See Also:

findGroupsWithUser(String, String, PageRequest), findUsersWithGroup(String, String, PageRequest), UserService.findGroupsByUser(String, PageRequest)

findUserByPasswordResetToken

@Nullable
DetailedUser findUserByPasswordResetToken(@Nonnull
                                                    String token)

Find a password reset request using the token generated by requestPasswordReset(String).

Parameters:

token - token identifying the password reset request

Returns:

the user matching the password reset request or null if no request matches the token or if the request has expired

See Also:

requestPasswordReset(String)

findUsers

@Nonnull
Page<DetailedUser> findUsers(@Nonnull
                                      PageRequest pageRequest)

Retrieves a page of users with full details.

Note: To filter the retrieved users by name, use findUsersByName(String, PageRequest) instead.

Parameters:

pageRequest - defines the page of users to retrieve

Returns:

the requested page of users, which may be empty but never null

See Also:

findUsersByName(String, PageRequest), UserService.findUsers(PageRequest)

findUsersByName

@Nonnull
Page<DetailedUser> findUsersByName(@Nullable
                                            String username,
                                            @Nonnull
                                            PageRequest pageRequest)

Retrieves a page of users, optionally filtering the returned results to those containing the specified username. If the provided username is null, this method behaves identically to findUsers(PageRequest). Otherwise, the username is matched against:

• Display names
• E-mail addresses
• Usernames

Parameters:

username - 0 or more characters to apply as a filter on returned users

pageRequest - defines the page of users to retrieve

Returns:

the requested page of users, potentially filtered, which may be empty but never null

See Also:

findUsers(PageRequest), UserService.findUsersByName(String, PageRequest)

findUsersWithGroup

@Nonnull
Page<DetailedUser> findUsersWithGroup(@Nonnull
                                               String groupName,
                                               @Nullable
                                               String username,
                                               @Nonnull
                                               PageRequest pageRequest)

Find the users within a group that match the page request.

Parameters:

groupName - name of the group the users must belong to

username - 0 or more characters to apply as a filter on returned users

pageRequest - page request

Returns:

page of users matching search criteria

findUsersWithoutGroup

@Nonnull
Page<DetailedUser> findUsersWithoutGroup(@Nonnull
                                                  String groupName,
                                                  @Nullable
                                                  String username,
                                                  @Nonnull
                                                  PageRequest pageRequest)

Find the users outside a group that match the page request.

Parameters:

groupName - name of the group the users must not belong to

username - 0 or more characters to apply as a filter on returned users

pageRequest - page request

Returns:

a page of ApplicationUser

getUserDetails

@Nullable
DetailedUser getUserDetails(@Nonnull
                                      String username)

Retrieves full details for the user with the specified username, or null if no such user exists.

Parameters:

username - the exact username of the user to retrieve

Returns:

full details for the specified user, or null if no user

getUserDetails

@Nonnull
DetailedUser getUserDetails(@Nonnull
                                     ApplicationUser user)

Retrieves full details for the specified user. This method is intended to "promote" from a ApplicationUser to a DetailedUser, providing access to mutability details and other information for the user.

Parameters:

user - the user to retrieve details for

Returns:

full details for the specified user

Throws:

NoSuchUserException - if the specified user does not exist in the underlying user store

removeUserFromGroup

void removeUserFromGroup(@Nonnull
                         String groupName,
                         @Nonnull
                         String username)
                  throws ForbiddenException,
                         IntegrityException,
                         NoSuchGroupException,
                         NoSuchUserException

Removes a user from a group.

Parameters:

groupName - name of the group the user will be removed from

username - name of the user to remove from the group

Throws:

ForbiddenException - if the group grants SYS_ADMIN permission but the current user is not a SYS_ADMIN

IntegrityException - if the current user belongs to the specified group and removing them from the group would revoke their SYS_ADMIN or ADMIN permission

NoSuchGroupException - if the specified group does not exist

NoSuchUserException - if the specified user does not exist

renameUser

@Nonnull
DetailedUser renameUser(@Nonnull
                                 String currentUsername,
                                 @Nonnull
                                 String newUsername)

Change the name of a user

Parameters:

currentUsername - the current name of the user

newUsername - the new name of the user

Returns:

the newly renamed user

Throws:

NoSuchUserException - if the specified user does not exist

IntegrityException - if a user already exists in the directory with the new name

ForbiddenException - if renaming is not supported by the directory the target user belongs to

requestPasswordReset

void requestPasswordReset(@Nonnull
                          String username)
                   throws MailException,
                          NoSuchUserException

Generates a unique token which can be used to perform a password reset for the specified user and e-mails it to the address associated with their account.

Parameters:

username - username of the user

Throws:

MailException - if the e-mail notification could not be sent to the user (ex: the mail server is down)

NoMailHostConfigurationException - if no e-mail server has been configured

NoSuchUserException - if the user does not exist

resetPassword

void resetPassword(@Nonnull
                   String token,
                   @Nonnull
                   String password)
            throws InvalidPasswordResetTokenException,
                   NoSuchEntityException

Resets the password for the user associated with the specified token to the provided value.

Parameters:

token - the token identifying the user whose password should be reset

password - the new password for the user

Throws:

InvalidPasswordResetTokenException - if no user matches the specified token

NoSuchEntityException

updatePassword

void updatePassword(@Nonnull
                    String username,
                    @Nonnull
                    String newPassword)

Updates the password of the specified user.

Note: A ADMIN cannot update the password of a SYS_ADMIN.

Parameters:

username - the user's username

newPassword - the user's new password

updateServiceUser

@Nonnull
ServiceUser updateServiceUser(@Nonnull
                                       ServiceUserUpdateRequest request)

Updates the details of the specified user

Parameters:

request - the user's new details

Returns:

the updated user

updateUser

@Nonnull
DetailedUser updateUser(@Nonnull
                                 String username,
                                 @Nonnull
                                 String displayName,
                                 @Nonnull
                                 String emailAddress)

Updates the display name and e-mail address of the specified user.

Note: A ADMIN cannot update the details of a SYS_ADMIN.

Parameters:

username - the user's username

displayName - the user's new display name

emailAddress - the user's new email address

Returns:

the updated user

validateErasable

void validateErasable(@Nonnull
                      String username)
               throws IllegalUserStateException,
                      NoSuchUserException

Validate if a username can be erased.

A username is only valid for erasure if it exists as the username of a deleted user. This method will throw an appropriate exception if the user for the supplied username is invalid for erasure.

Parameters:

username - the username of the user to validate erasability for

Throws:

IllegalUserStateException - if the supplied username is the username of a non-deleted user

NoSuchUserException - if the supplied username does not exist

Since:

5.16