Class AbstractUserDatabase
- Direct Known Subclasses:
UserDatabase
public abstract class AbstractUserDatabase
extends java.lang.Object
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:
User
-
Nested Class Summary
Nested Classes Modifier and Type Class Description static interface
AbstractUserDatabase.Transaction
An abstract transaction. -
Constructor Summary
Constructors Modifier Constructor Description protected
AbstractUserDatabase()
-
Method Summary
Modifier and Type Method Description void
addAuthToken(User user, Token token)
Adds an authentication token to a user.abstract void
addIdentity(User user, java.lang.String provider, java.lang.String id)
Adds an identify for the user.void
deleteUser(User user)
Delete a user.User
findWithAuthToken(java.lang.String hash)
Finds a user with an authentication token.User
findWithEmail(java.lang.String address)
Finds a user with a given email address.User
findWithEmailToken(java.lang.String hash)
Finds a user with a given email token.abstract User
findWithId(java.lang.String id)
Finds a user with a given id.abstract User
findWithIdentity(java.lang.String provider, java.lang.String identity)
Finds a user with a given identity.java.lang.String
getEmail(User user)
Returns a user's email address.Token
getEmailToken(User user)
Returns an email token.User.EmailTokenRole
getEmailTokenRole(User user)
Returns the role of the current email token.int
getFailedLoginAttempts(User user)
Returns the number of consecutive authentication failures.abstract java.lang.String
getIdentity(User user, java.lang.String provider)
Returns a user identity.WDate
getLastLoginAttempt(User user)
Returns the time of the last login.PasswordHash
getPassword(User user)
Returns a user password.User.Status
getStatus(User user)
Returns the status for a user.java.lang.String
getUnverifiedEmail(User user)
Returns a user's unverified email address.OAuthClient
idpClientAdd(java.lang.String clientId, boolean confidential, java.util.Set<java.lang.String> redirectUris, ClientSecretMethod authMethod, java.lang.String secret)
Add a new client to the database and returns it.ClientSecretMethod
idpClientAuthMethod(OAuthClient client)
Returns the client authentication method (see OIDC Core chapter 9)boolean
idpClientConfidential(OAuthClient client)
Returns whether the client is confidential or public.OAuthClient
idpClientFindWithId(java.lang.String clientId)
Finds the authorization client (relying party) with this identifier.java.lang.String
idpClientId(OAuthClient client)
Returns the identifier for this client.java.util.Set<java.lang.String>
idpClientRedirectUris(OAuthClient client)
Returns the redirect URI for this client.java.lang.String
idpClientSecret(OAuthClient client)
Returns the secret for this client.com.google.gson.JsonElement
idpJsonClaim(User user, java.lang.String claim)
Returns the value of a claim for a user.IssuedToken
idpTokenAdd(java.lang.String value, WDate expirationTime, java.lang.String purpose, java.lang.String scope, java.lang.String redirectUri, User user, OAuthClient authClient)
Adds a newIssuedToken
to the database and returns it.WDate
idpTokenExpirationTime(IssuedToken token)
Gets the expiration time for a token.IssuedToken
idpTokenFindWithValue(java.lang.String purpose, java.lang.String value)
Finds a token in the database with a given value.OAuthClient
idpTokenOAuthClient(IssuedToken token)
Returns the authorization client (relying party) that is associated with the token.java.lang.String
idpTokenPurpose(IssuedToken token)
Gets the token purpose (authorization_code, access_token, id_token, refresh_token).java.lang.String
idpTokenRedirectUri(IssuedToken token)
Returns the redirect URI that was used with the token request.void
idpTokenRemove(IssuedToken token)
Removes an issued token from the database.java.lang.String
idpTokenScope(IssuedToken token)
Gets the scope associated with the token.User
idpTokenUser(IssuedToken token)
Returns the user associated with the token.java.lang.String
idpTokenValue(IssuedToken token)
Gets the value for a token.boolean
idpVerifySecret(OAuthClient client, java.lang.String secret)
Returns true if the given secret is correct for the given client.User
registerNew()
Registers a new user.void
removeAuthToken(User user, java.lang.String hash)
Deletes an authentication token.abstract void
removeIdentity(User user, java.lang.String provider)
Removes a user identity.boolean
setEmail(User user, java.lang.String address)
Sets a user's email address.void
setEmailToken(User user, Token token, User.EmailTokenRole role)
Sets a new email token for a user.void
setFailedLoginAttempts(User user, int count)
Sets the number of consecutive authentication failures.void
setIdentity(User user, java.lang.String provider, java.lang.String id)
Changes an identity for a user.void
setLastLoginAttempt(User user, WDate t)
Sets the time of the last login attempt.void
setPassword(User user, PasswordHash password)
Sets a new user password.void
setStatus(User user, User.Status status)
Sets the user status.void
setUnverifiedEmail(User user, java.lang.String address)
Sets a user's unverified email address.AbstractUserDatabase.Transaction
startTransaction()
Creates a new database transaction.int
updateAuthToken(User user, java.lang.String hash, java.lang.String newHash)
Updates the authentication token with a new hash.Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
-
Constructor Details
-
AbstractUserDatabase
protected AbstractUserDatabase()
-
-
Method Details
-
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
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
Finds a user with a given identity.The
identity
uniquely identifies the user by theprovider
.This should find the user with the given
identity
, or return an invalid user if no user with that identity exists. -
addIdentity
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
Changes an identity for a user.The base implementation calls
removeIdentity()
followed byaddIdentity()
. -
getIdentity
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.
-
removeIdentity
Removes a user identity.This removes all identities of a
provider
from theuser
. -
registerNew
Registers a new user.This adds a new user.
This method is only used by view classes involved with registration (
RegistrationWidget
). -
deleteUser
Delete a user.This deletes a user from the database.
-
getStatus
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
Status#Normal
. -
setStatus
Sets the user status.This sets the status for a user (if supported).
-
setPassword
Sets a new user password.This updates the password for a user.
This is used only by
PasswordService
. -
getPassword
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
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:
findWithEmail(String address)
-
getEmail
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
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
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
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
Sets a new email token for a user.This is only used when email verification is enabled or for lost password functionality.
-
getEmailToken
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
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
Finds a user with a given email token.This is only used when email verification is enabled or for lost password functionality.
-
addAuthToken
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
Deletes an authentication token.Deletes an authentication token previously added with
addAuthToken()
-
findWithAuthToken
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
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
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
Returns the number of consecutive authentication failures. -
setLastLoginAttempt
Sets the time of the last login attempt.This sets the time at which the user attempted to login.
-
getLastLoginAttempt
Returns the time of the last login.- See Also:
setLastLoginAttempt(User user, WDate t)
-
idpJsonClaim
Returns the value of a claim for a user.Should return a null Json value when the claim is unavailable.
-
idpTokenAdd
public IssuedToken idpTokenAdd(java.lang.String value, WDate expirationTime, java.lang.String purpose, java.lang.String scope, java.lang.String redirectUri, User user, OAuthClient authClient)Adds a newIssuedToken
to the database and returns it. S. -
idpTokenRemove
Removes an issued token from the database. -
idpTokenFindWithValue
Finds a token in the database with a given value. -
idpTokenExpirationTime
Gets the expiration time for a token. -
idpTokenValue
Gets the value for a token. -
idpTokenPurpose
Gets the token purpose (authorization_code, access_token, id_token, refresh_token). -
idpTokenScope
Gets the scope associated with the token. -
idpTokenRedirectUri
Returns the redirect URI that was used with the token request. -
idpTokenUser
Returns the user associated with the token. -
idpTokenOAuthClient
Returns the authorization client (relying party) that is associated with the token. -
idpClientFindWithId
Finds the authorization client (relying party) with this identifier. -
idpClientSecret
Returns the secret for this client. -
idpVerifySecret
Returns true if the given secret is correct for the given client. -
idpClientRedirectUris
Returns the redirect URI for this client. -
idpClientId
Returns the identifier for this client. -
idpClientConfidential
Returns whether the client is confidential or public. -
idpClientAuthMethod
Returns the client authentication method (see OIDC Core chapter 9) -
idpClientAdd
public OAuthClient idpClientAdd(java.lang.String clientId, boolean confidential, java.util.Set<java.lang.String> redirectUris, ClientSecretMethod authMethod, java.lang.String secret)Add a new client to the database and returns it.
-