Class AbstractUserDatabase

Direct Known Subclasses:

public abstract class AbstractUserDatabase extends Object
Abstract interface for an authentication user database.

This class defines the interface for managing user data related to authentication. You need to implement this interface to allow the authentication service classes (AuthService, PasswordService, OAuthService, and OidcService) to locate and update user credentials. Except for functions which do work on a single user, it is more convenient to use the User API. Obviously, you may have more data associated with a user, including roles for access control, other personal information, address information. This information cannot be accessed through the User class, but you should make it available through your own User class, which is then als the basis of this user database implementation.

The only assumption made by the authentication system is that an id uniquely defines the user. This is usually an internal identifier, for example an auto-incrementing primary key.

With a user, one or more other identities may be associated. These could be a login name (for password-based authentication), or id's used by third party providers (such as OAuth or LDAP).

The database implements a simple data store and does not contain any logic. The database can store data for different aspects of authentication, but most data fields are only relevant for optional functionality, and thus themeselves optional. The default implementation of these methods will log errors.

The authentication views and model classes assume a private instance of the database for each different session, and will try to wrap database access within a transaction. AbstractUserDatabase.Transaction support can thus be optionally provided by a database implementation.

This class is also used by OAuthAuthorizationEndpoint, OAuthTokenEndpoint, and OidcUserInfoEndpoint when implementing an OAuth/OpenID Connect provider to retrieve information not only about the User, but also the OAuthClient, and an IssuedToken.

See Also:
  • Constructor Details

    • AbstractUserDatabase

      protected AbstractUserDatabase()
  • Method Details

    • startTransaction

      public AbstractUserDatabase.Transaction startTransaction()
      Creates a new database transaction.

      If the underlying database does not support transactions, you can return null.

      Ownership of the transaction is transferred, and the transaction must be deleted after it has been committed or rolled back.

      The default implementation returns null (no transaction support).

    • findWithId

      public abstract User findWithId(String id)
      Finds a user with a given id.

      The id uniquely identifies a user.

      This should find the user with the given id, or return an invalid user if no user with that id exists.

    • findWithIdentity

      public abstract User findWithIdentity(String provider, String identity)
      Finds a user with a given identity.

      The identity uniquely identifies the user by the provider.

      This should find the user with the given identity, or return an invalid user if no user with that identity exists.

    • addIdentity

      public abstract void addIdentity(User user, String provider, String id)
      Adds an identify for the user.

      This adds an identity to the user.

      You are free to support only one identity per user, e.g. if you only use password-based authentication. But you may also want to support more than one if you allow the user to login using multiple methods (e.g. name/password, OAuth from one or more providers, LDAP, ...).

    • setIdentity

      public void setIdentity(User user, String provider, String id)
      Changes an identity for a user.

      The base implementation calls removeIdentity() followed by addIdentity().

    • getIdentity

      public abstract String getIdentity(User user, String provider)
      Returns a user identity.

      Returns a user identity for the given provider, or an empty string if the user has no identitfy set for this provider.

      See Also:
    • removeIdentity

      public abstract void removeIdentity(User user, String provider)
      Removes a user identity.

      This removes all identities of a provider from the user.

      See Also:
    • registerNew

      public User registerNew()
      Registers a new user.

      This adds a new user.

      This method is only used by view classes involved with registration (RegistrationWidget).

    • deleteUser

      public void deleteUser(User user)
      Delete a user.

      This deletes a user from the database.

    • getStatus

      public AccountStatus getStatus(User user)
      Returns the status for a user.

      If there is support for suspending accounts, then this method may be implemented to return whether a user account is disabled.

      The default implementation always returns AccountStatus.Normal.

    • setStatus

      public void setStatus(User user, AccountStatus status)
      Sets the user status.

      This sets the status for a user (if supported).

    • setPassword

      public void setPassword(User user, PasswordHash password)
      Sets a new user password.

      This updates the password for a user.

      This is used only by PasswordService.

    • getPassword

      public PasswordHash getPassword(User user)
      Returns a user password.

      This returns the stored password for a user, or a default constructed password hash if the user does not yet have password credentials.

      This is used only by PasswordService.

    • setEmail

      public boolean setEmail(User user, String address)
      Sets a user's email address.

      This is used only when email verification is enabled, or as a result of a 3rd party Identity Provider based registration process, if the provider also provides email address information with the identiy.

      Returns whether the user's email address could be set. This may fail when there is already a user registered that email address.

      See Also:
    • getEmail

      public String getEmail(User user)
      Returns a user's email address.

      This may be an unverified or verified email address, depending on whether email address verification is enabled in the model classes.

      This is an optional method, and currently not used by any of the included models or views.

    • setUnverifiedEmail

      public void setUnverifiedEmail(User user, String address)
      Sets a user's unverified email address.

      This is only used when email verification is enabled. It holds the currently unverified email address, while a mail is being sent for the user to confirm this email address.

    • getUnverifiedEmail

      public String getUnverifiedEmail(User user)
      Returns a user's unverified email address.

      This is an optional method, and currently not used by any of the included models or views.

    • findWithEmail

      public User findWithEmail(String address)
      Finds a user with a given email address.

      This is used to verify that a email addresses are unique, and to implement lost password functionality.

    • setEmailToken

      public void setEmailToken(User user, Token token, EmailTokenRole role)
      Sets a new email token for a user.

      This is only used when email verification is enabled or for lost password functionality.

    • getEmailToken

      public Token getEmailToken(User user)
      Returns an email token.

      This is only used when email verification is enabled and for lost password functionality. It should return the email token previously set with setEmailToken()

    • getEmailTokenRole

      public EmailTokenRole getEmailTokenRole(User user)
      Returns the role of the current email token.

      This is only used when email verification is enabled or for lost password functionality. It should return the role previously set with setEailToken().

    • findWithEmailToken

      public User findWithEmailToken(String hash)
      Finds a user with a given email token.

      This is only used when email verification is enabled or for lost password functionality.

    • addAuthToken

      public void addAuthToken(User user, Token token)
      Adds an authentication token to a user.

      Unless you want a user to only have remember-me support from a single computer at a time, you should support multiple authentication tokens per user.

    • removeAuthToken

      public void removeAuthToken(User user, String hash)
      Deletes an authentication token.

      Deletes an authentication token previously added with addAuthToken()

    • findWithAuthToken

      public User findWithAuthToken(String hash)
      Finds a user with an authentication token.

      Returns a user with an authentication token.

      This should find the user associated with a particular token hash, or return an invalid user if no user with that token hash exists.

    • updateAuthToken

      public int updateAuthToken(User user, String hash, String newHash)
      Updates the authentication token with a new hash.

      If successful, returns the validity of the updated token in seconds.

      Returns 0 if the token could not be updated because it wasn't found or is expired.

      Returns -1 if not implemented.

    • setFailedLoginAttempts

      public void setFailedLoginAttempts(User user, int count)
      Sets the number of consecutive authentication failures.

      This sets the number of consecutive authentication failures since the last valid login.

      This is used by the throttling logic to determine how much time a user needs to wait before he can do a new login attempt.

    • getFailedLoginAttempts

      public int getFailedLoginAttempts(User user)
      Returns the number of consecutive authentication failures.


    • setLastLoginAttempt

      public void setLastLoginAttempt(User user, WDate t)
      Sets the time of the last login attempt.

      This sets the time at which the user attempted to login.

    • getLastLoginAttempt

      public WDate getLastLoginAttempt(User user)
      Returns the time of the last login.

      See Also:
    • idpJsonClaim

      public idpJsonClaim(User user, String claim)
      Returns the value of a claim for a user.

      Should return a null Json value when the claim is unavailable.

    • idpTokenAdd

      public IssuedToken idpTokenAdd(String value, WDate expirationTime, String purpose, String scope, String redirectUri, User user, OAuthClient authClient)
      Adds a new IssuedToken to the database and returns it. S.
    • idpTokenRemove

      public void idpTokenRemove(IssuedToken token)
      Removes an issued token from the database.
    • idpTokenFindWithValue

      public IssuedToken idpTokenFindWithValue(String purpose, String value)
      Finds a token in the database with a given value.
    • idpTokenExpirationTime

      public WDate idpTokenExpirationTime(IssuedToken token)
      Gets the expiration time for a token.
    • idpTokenValue

      public String idpTokenValue(IssuedToken token)
      Gets the value for a token.
    • idpTokenPurpose

      public String idpTokenPurpose(IssuedToken token)
      Gets the token purpose (authorization_code, access_token, id_token, refresh_token).
    • idpTokenScope

      public String idpTokenScope(IssuedToken token)
      Gets the scope associated with the token.
    • idpTokenRedirectUri

      public String idpTokenRedirectUri(IssuedToken token)
      Returns the redirect URI that was used with the token request.
    • idpTokenUser

      public User idpTokenUser(IssuedToken token)
      Returns the user associated with the token.
    • idpTokenOAuthClient

      public OAuthClient idpTokenOAuthClient(IssuedToken token)
      Returns the authorization client (relying party) that is associated with the token.
    • idpClientFindWithId

      public OAuthClient idpClientFindWithId(String clientId)
      Finds the authorization client (relying party) with this identifier.
    • idpClientSecret

      public String idpClientSecret(OAuthClient client)
      Returns the secret for this client.
    • idpVerifySecret

      public boolean idpVerifySecret(OAuthClient client, String secret)
      Returns true if the given secret is correct for the given client.
    • idpClientRedirectUris

      public Set<String> idpClientRedirectUris(OAuthClient client)
      Returns the redirect URI for this client.
    • idpClientId

      public String idpClientId(OAuthClient client)
      Returns the identifier for this client.
    • idpClientConfidential

      public boolean idpClientConfidential(OAuthClient client)
      Returns whether the client is confidential or public.
    • idpClientAuthMethod

      public ClientSecretMethod idpClientAuthMethod(OAuthClient client)
      Returns the client authentication method (see OIDC Core chapter 9)
    • idpClientAdd

      public OAuthClient idpClientAdd(String clientId, boolean confidential, Set<String> redirectUris, ClientSecretMethod authMethod, String secret)
      Add a new client to the database and returns it.