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

  • Method Details

    • 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

      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:

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

    • 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

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

    • 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

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

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

    • 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

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

    • 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