public interface

UserAdminService

com.atlassian.bitbucket.user.UserAdminService

Class Overview

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

Summary

Public Methods
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.
@Nonnull DetailedGroup createGroup(String groupName)
Creates a new group.
@Nonnull 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.
@Nonnull DetailedGroup deleteGroup(String groupName)
Deletes a group.
@Nonnull DetailedUser deleteUser(String username)
Deletes a user.
@Nonnull String eraseUser(String username)
Erases personally identifying user data for a deleted user.
@Nonnull Page<DetailedGroup> findGroups(PageRequest pageRequest)
Retrieves a page of groups with full details.
@Nonnull 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.
@Nonnull 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.
@Nonnull 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.
@Nullable DetailedUser findUserByPasswordResetToken(String token)
Find a password reset request using the token generated by requestPasswordReset(String).
@Nonnull Page<DetailedUser> findUsers(PageRequest pageRequest)
Retrieves a page of users with full details.
@Nonnull Page<DetailedUser> findUsersByName(String username, PageRequest pageRequest)
Retrieves a page of users, optionally filtering the returned results to those containing the specified username.
@Nonnull Page<DetailedUser> findUsersWithGroup(String groupName, String username, PageRequest pageRequest)
Find the users within a group that match the page request.
@Nonnull Page<DetailedUser> findUsersWithoutGroup(String groupName, String username, PageRequest pageRequest)
Find the users outside a group that match the page request.
@Nonnull DetailedUser getUserDetails(ApplicationUser user)
Retrieves full details for the specified user.
@Nullable 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.
@Nonnull 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.
@Nonnull ServiceUser updateServiceUser(ServiceUserUpdateRequest request)
Updates the details of the specified user
@Nonnull 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.

Public Methods

public void addMembersToGroup (String groupName, Set<String> usernames)

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

public void addUserToGroups (String username, Set<String> groupNames)

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

public 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

public 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

public 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

public 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

public void clearCaptchaChallenge (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

@Nonnull public DetailedGroup createGroup (String groupName)

Creates a new group.

Parameters
groupName the name for the new group
Throws
IntegrityException if a group with the same already exists

@Nonnull public ServiceUser createServiceUser (ServiceUserCreateRequest userRequest)

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

public void createUser (String username, String password, String displayName, String emailAddress)

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

public 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.

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
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

public void createUserWithGeneratedPassword (String username, String displayName, String emailAddress)

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

@Nonnull public DetailedGroup deleteGroup (String groupName)

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

@Nonnull public DetailedUser deleteUser (String username)

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

@Nonnull public String eraseUser (String username)

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
See Also

@Nonnull public Page<DetailedGroup> findGroups (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

@Nonnull public 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. 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

@Nonnull public 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. 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

@Nonnull public 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. 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

@Nullable public DetailedUser findUserByPasswordResetToken (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

@Nonnull public Page<DetailedUser> findUsers (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

@Nonnull public Page<DetailedUser> findUsersByName (String username, 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:

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

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

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

Parameters
groupName name of the group the users must belong to
pageRequest page request
Returns

@Nonnull public Page<DetailedUser> findUsersWithoutGroup (String groupName, String username, 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
pageRequest page request
Returns

@Nonnull public DetailedUser getUserDetails (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

@Nullable public DetailedUser getUserDetails (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

public boolean newUserCanResetPassword ()

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

Returns
  • {code true} if user is able to set a password; otherwise false

public void removeUserFromGroup (String groupName, String username)

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

@Nonnull public DetailedUser renameUser (String currentUsername, 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

public 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.

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

public void resetPassword (String token, String password)

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

public void updatePassword (String username, 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

@Nonnull public ServiceUser updateServiceUser (ServiceUserUpdateRequest request)

Updates the details of the specified user

Parameters
request the user's new details

@Nonnull public DetailedUser updateUser (String username, String displayName, 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

public void validateErasable (String username)

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