Package com.complexible.stardog.security

# Interface UserManager

public interface UserManager
API for managing users in Stardog.

Since:
  0.9
Version:
  2.0
Author:
  Blazej Bulka, Hector Perez-Urbina

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `addUser(String theUsername, boolean theSuperuser, char[] thePassword)`
  Adds a new user.
  `void`
  `addUserRole(String theUserName, String theRole)`
  Assigns a role to a user.
  `void`
  `changePassword(String theUsername, char[] theCurrentPassword, char[] theNewPassword)`
  Changes the password for the user.
  `void`
  `deleteUser(String theUsername)`
  Removes an existing user.
  `void`
  `deleteUserRole(String theUserName, String theRole)`
  Unassigns a role from a user.
  `Collection<String>`
  `getAllUsers()`
  Gets the names of all users in the system that the authenticated user is allowed to see.
  `Collection<String>`
  `getUserRoles(String theUsername)`
  Retrieves all roles of the specified user.
  `boolean`
  `isSuperUser(String theUsername)`
  Checks whether the specified user is a super user
  `boolean`
  `isUserAutoCreated(String theUsername)`
  Checks whether the specified user was auto-created as a result the OAuth jwt authentication process.
  `boolean`
  `isUserEnabled(String theUsername)`
  Checks whether the specified user is enabled
  `void`
  `setUserEnabled(String theUsername, boolean theEnabled)`
  Enables/disables the user.
  `void`
  `setUserRoles(String theUserName, Collection<String> theRoles)`
  Changes the user roles.

- ## Method Details

  - ### addUser

    void addUser(String theUsername, boolean theSuperuser, char[] thePassword) throws com.complexible.stardog.security.StardogSecurityException, com.complexible.stardog.security.ResourceExistsException, com.complexible.stardog.security.IllegalPasswordException, StardogAuthorizationException
    Adds a new user.
    Parameters:
      `theUsername` - the username of the new user
      `theSuperuser` - true, if the new user should be a super user; false, otherwise
      `thePassword` - the initial password for the user
    Throws:
      `com.complexible.stardog.security.ResourceExistsException` - if there is already a user with that name
      `StardogAuthorizationException` - if the current user does not have a permission to create the new user
      `com.complexible.stardog.security.IllegalPasswordException` - if the password is invalid
      `com.complexible.stardog.security.StardogSecurityException` - if the operation should fail for any other reason

  - ### deleteUser

    void deleteUser(String theUsername) throws com.complexible.stardog.security.StardogSecurityException, com.complexible.stardog.security.ResourceNotFoundException, com.complexible.stardog.security.OperationNotSupportedException, StardogAuthorizationException
    Removes an existing user. It is not possible to remove the last active (enabled) super user from the system.
    Parameters:
      `theUsername` - the user to be removed.
    Throws:
      `com.complexible.stardog.security.ResourceNotFoundException` - if there is no such username
      `com.complexible.stardog.security.OperationNotSupportedException` - if the operation is not supported for this user (e.g., it is the last active super user in the system).
      `StardogAuthorizationException` - if the current user does not have a permission to remove the user
      `com.complexible.stardog.security.StardogSecurityException` - if the operation should fail for any other reason

  - ### getAllUsers

    Collection<String> getAllUsers() throws com.complexible.stardog.security.StardogSecurityException
    Gets the names of all users in the system that the authenticated user is allowed to see.
    Throws:
      `com.complexible.stardog.security.StardogSecurityException` - if the operation should fail for any other reason

  - ### changePassword

    void changePassword(String theUsername, char[] theCurrentPassword, char[] theNewPassword) throws com.complexible.stardog.security.StardogSecurityException, com.complexible.stardog.security.ResourceNotFoundException, StardogAuthorizationException, IllegalArgumentException, com.complexible.stardog.security.IllegalPasswordException
    Changes the password for the user. The user needs to have the permission `write:user:USERNAME` to be able to change password for that user. By default, every user is granted this permission automatically, so they are allowed to change their own password unless that permission has been revoked by the system administrator. The current password for the user has to be provided as input. Superusers can change the password for another user without specifying the current password.
    Parameters:
      `theUsername` - the name of the user whose password should be changed
      `theCurrentPassword` - the current password for the user
      `theNewPassword` - the new password for the user
    Throws:
      `com.complexible.stardog.security.ResourceNotFoundException` - if there is no user with the specified name
      `StardogAuthorizationException` - if the current user does not have the permission to change the password for the specified user
      `com.complexible.stardog.security.StardogSecurityException` - if the operation should fail for any other reason
      `IllegalArgumentException` - if the password is empty
      `com.complexible.stardog.security.IllegalPasswordException` - if the password is invalid

  - ### getUserRoles

    Collection<String> getUserRoles(String theUsername) throws com.complexible.stardog.security.StardogSecurityException, com.complexible.stardog.security.ResourceNotFoundException, StardogAuthorizationException
    Retrieves all roles of the specified user.
    Parameters:
      `theUsername` - the user name whose roles should be retrieved
    Returns:
      a collection of all role names for the user
    Throws:
      `com.complexible.stardog.security.ResourceNotFoundException` - if there is no user with the specified name
      `StardogAuthorizationException` - if the current user does not have the permission to retrieve the roles of the specified user
      `com.complexible.stardog.security.StardogSecurityException` - if the operation should fail for any other reason

  - ### setUserRoles

    void setUserRoles(String theUserName, Collection<String> theRoles) throws com.complexible.stardog.security.StardogSecurityException, com.complexible.stardog.security.ResourceNotFoundException, StardogAuthorizationException
    Changes the user roles.
    Parameters:
      `theUserName` - the user name whose roles should be changed
      `theRoles` - a new set of roles for the user (this set will replace the existing set of roles for the user)
    Throws:
      `com.complexible.stardog.security.ResourceNotFoundException` - if one of the resources (username or role name) does not exist
      `StardogAuthorizationException` - if the current user does not have the permission to set the roles for the specified user
      `com.complexible.stardog.security.StardogSecurityException` - if the operation should fail for any other reason

  - ### addUserRole

    void addUserRole(String theUserName, String theRole) throws com.complexible.stardog.security.StardogSecurityException, com.complexible.stardog.security.ResourceNotFoundException, StardogAuthorizationException
    Assigns a role to a user.
    Parameters:
      `theUserName` - the user name
      `theRole` - a new role for the user
    Throws:
      `com.complexible.stardog.security.ResourceNotFoundException` - if one of the resources (username or role name) does not exist
      `StardogAuthorizationException` - if the current user does not have the permission to set the roles for the specified user
      `com.complexible.stardog.security.StardogSecurityException` - if the operation should fail for any other reason

  - ### deleteUserRole

    void deleteUserRole(String theUserName, String theRole) throws com.complexible.stardog.security.StardogSecurityException, com.complexible.stardog.security.ResourceNotFoundException, StardogAuthorizationException
    Unassigns a role from a user.
    Parameters:
      `theUserName` - the user name
      `theRole` - the role name
    Throws:
      `com.complexible.stardog.security.ResourceNotFoundException` - if one of the resources (username or role name) does not exist
      `StardogAuthorizationException` - if the current user does not have the permission to set the roles for the specified user
      `com.complexible.stardog.security.StardogSecurityException` - if the operation should fail for any other reason

  - ### isSuperUser

    boolean isSuperUser(String theUsername) throws com.complexible.stardog.security.StardogSecurityException, StardogAuthorizationException
    Checks whether the specified user is a super user
    Parameters:
      `theUsername` - the username to be checked
    Returns:
      true, if the user is a super user; false otherwise
    Throws:
      `StardogAuthorizationException` - if the current user does not have the permission to perform this operation
      `com.complexible.stardog.security.StardogSecurityException` - if the operation should fail for any other reason

  - ### isUserEnabled

    boolean isUserEnabled(String theUsername) throws com.complexible.stardog.security.StardogSecurityException, StardogAuthorizationException
    Checks whether the specified user is enabled
    Parameters:
      `theUsername` - the username to be checked
    Returns:
      true, if the user is enabled; false otherwise
    Throws:
      `StardogAuthorizationException` - if the current user does not have the permission to perform this operation
      `com.complexible.stardog.security.StardogSecurityException` - if the operation should fail for any other reason

  - ### setUserEnabled

    void setUserEnabled(String theUsername, boolean theEnabled) throws com.complexible.stardog.security.StardogSecurityException, com.complexible.stardog.security.ResourceNotFoundException, com.complexible.stardog.security.OperationNotSupportedException, StardogAuthorizationException
    Enables/disables the user. This operation must not disable the last active super user in the system.
    Parameters:
      `theUsername` - the name of the user to be enabled/disabled
      `theEnabled` - true if the user is to become a enabled (active); false if the user should become disabled
    Throws:
      `com.complexible.stardog.security.ResourceNotFoundException` - if there is no such user name
      `com.complexible.stardog.security.OperationNotSupportedException` - if the operation would disable the last super user
      `StardogAuthorizationException` - if the current user does not have the permission to perform this operation
      `com.complexible.stardog.security.StardogSecurityException` - if the operation should fail for any other reason

  - ### isUserAutoCreated

    boolean isUserAutoCreated(String theUsername)
    Checks whether the specified user was auto-created as a result the OAuth jwt authentication process.
    Parameters:
      `theUsername` - the username to be checked
    Returns:
      true, if the user was auto-created; false otherwise
    Throws:
      `StardogAuthorizationException` - if the current user does not have the permission to perform this operation
      `com.complexible.stardog.security.StardogSecurityException` - if the operation should fail for any other reason