Abstract interface for an authentication user database. More...

#include <Wt/Auth/AbstractUserDatabase.h>

Inheritance diagram for Wt::Auth::AbstractUserDatabase:

Classes
class	Transaction
	An abstract transaction. More...

Public Member Functions
virtual	~AbstractUserDatabase ()
	Destructor.

virtual Transaction *	startTransaction ()
	Creates a new database transaction. More...

virtual User	findWithId (const std::string &id) const =0
	Finds a user with a given id. More...

virtual User	findWithIdentity (const std::string &provider, const WString &identity) const =0
	Finds a user with a given identity. More...

virtual void	addIdentity (const User &user, const std::string &provider, const WString &id)=0
	Adds an identify for the user. More...

virtual void	setIdentity (const User &user, const std::string &provider, const WString &id)
	Changes an identity for a user. More...

virtual WString	identity (const User &user, const std::string &provider) const =0
	Returns a user identity. More...

virtual void	removeIdentity (const User &user, const std::string &provider)=0
	Removes a user identity. More...

virtual User	registerNew ()
	Registers a new user. More...

virtual void	deleteUser (const User &user)
	Delete a user. More...

virtual AccountStatus	status (const User &user) const
	Returns the status for a user. More...

virtual void	setStatus (const User &user, AccountStatus status)
	Sets the user status. More...

Password authentication
virtual void	setPassword (const User &user, const PasswordHash &password)
	Sets a new user password. More...

virtual PasswordHash	password (const User &user) const
	Returns a user password. More...

Email addresses (for verification and lost passwords)
virtual bool	setEmail (const User &user, const std::string &address)
	Sets a user's email address. More...

virtual std::string	email (const User &user) const
	Returns a user's email address. More...

virtual void	setUnverifiedEmail (const User &user, const std::string &address)
	Sets a user's unverified email address. More...

virtual std::string	unverifiedEmail (const User &user) const
	Returns a user's unverified email address. More...

virtual User	findWithEmail (const std::string &address) const
	Finds a user with a given email address. More...

virtual void	setEmailToken (const User &user, const Token &token, EmailTokenRole role)
	Sets a new email token for a user. More...

virtual Token	emailToken (const User &user) const
	Returns an email token. More...

virtual EmailTokenRole	emailTokenRole (const User &user) const
	Returns the role of the current email token. More...

virtual User	findWithEmailToken (const std::string &hash) const
	Finds a user with a given email token. More...

Auth tokens (remember-me support)
virtual void	addAuthToken (const User &user, const Token &token)
	Adds an authentication token to a user. More...

virtual void	removeAuthToken (const User &user, const std::string &hash)
	Deletes an authentication token. More...

virtual User	findWithAuthToken (const std::string &hash) const
	Finds a user with an authentication token. More...

virtual int	updateAuthToken (const User &user, const std::string &oldhash, const std::string &newhash)
	Updates the authentication token with a new hash. More...

Authenticaton attempt throttling
virtual void	setFailedLoginAttempts (const User &user, int count)
	Sets the number of consecutive authentication failures. More...

virtual int	failedLoginAttempts (const User &user) const
	Returns the number of consecutive authentication failures. More...

virtual void	setLastLoginAttempt (const User &user, const WDateTime &t)
	Sets the time of the last login attempt. More...

virtual WDateTime	lastLoginAttempt (const User &user) const
	Returns the time of the last login. More...

Identity provider support
virtual Json::Value	idpJsonClaim (const User &user, const std::string &claim) const
	Returns the value of a claim for a user. More...

virtual Wt::Auth::IssuedToken	idpTokenAdd (const std::string &value, const WDateTime &expirationTime, const std::string &purpose, const std::string &scope, const std::string &redirectUri, const User &user, const OAuthClient &authClient)
	Adds a new Wt::Auth::IssuedToken to the database and returns it. S.

virtual void	idpTokenRemove (const IssuedToken &token)
	Removes an issued token from the database.

virtual IssuedToken	idpTokenFindWithValue (const std::string &purpose, const std::string &value) const
	Finds a token in the database with a given value.

virtual WDateTime	idpTokenExpirationTime (const IssuedToken &token) const
	Gets the expiration time for a token.

virtual std::string	idpTokenValue (const IssuedToken &token) const
	Gets the value for a token.

virtual std::string	idpTokenPurpose (const IssuedToken &token) const
	Gets the token purpose (authorization_code, access_token, id_token, refresh_token).

virtual std::string	idpTokenScope (const IssuedToken &token) const
	Gets the scope associated with the token.

virtual std::string	idpTokenRedirectUri (const IssuedToken &token) const
	Returns the redirect URI that was used with the token request.

virtual User	idpTokenUser (const IssuedToken &token) const
	Returns the user associated with the token.

virtual OAuthClient	idpTokenOAuthClient (const IssuedToken &token) const
	Returns the authorization client (relying party) that is associated with the token.

virtual OAuthClient	idpClientFindWithId (const std::string &clientId) const
	Finds the authorization client (relying party) with this identifier.

virtual std::string	idpClientSecret (const OAuthClient &client) const
	Returns the secret for this client.

virtual bool	idpVerifySecret (const OAuthClient &client, const std::string &secret) const
	Returns true if the given secret is correct for the given client.

virtual std::set< std::string >	idpClientRedirectUris (const OAuthClient &client) const
	Returns the redirect URI for this client.

virtual std::string	idpClientId (const OAuthClient &client) const
	Returns the identifier for this client.

virtual bool	idpClientConfidential (const OAuthClient &client) const
	Returns whether the client is confidential or public.

virtual ClientSecretMethod	idpClientAuthMethod (const OAuthClient &client) const
	Returns the client authentication method (see OIDC Core chapter 9)

virtual Wt::Auth::OAuthClient	idpClientAdd (const std::string &clientId, bool confidential, const std::set< std::string > &redirectUris, ClientSecretMethod authMethod, const std::string &secret)
	Add a new client to the database and returns it.

Detailed Description

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 Auth::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. 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

Member Function Documentation

◆ addAuthToken()

void Wt::Auth::AbstractUserDatabase::addAuthToken	(	const User &	user,
		const Token &	token
	)

virtual

Adds an authentication token to a user.

An authentication token enables a user to not always type out their full username/password (see AuthWidget) or enter their MFA code (see TotpProcess). An authentication token will remember the user by placing a cookie in their browser and tracking the user's token in a local table in the database (by default called "auth_token").

The token itself is not aware of which use-case it serves. That being either for the regular username/password login, or for MFA. However, in the browser this cookie is given a name, based on the name set by AuthService::setAuthTokensEnabled() or AuthService::setMfaTokenCookieName(). This name can be used to match to the correct type.

Enabling either of these (by calling AuthService::setAuthTokensEnabled) will also enable the other, but their name and validity can be set separately.

See also: findWithAuthToken.

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

Reimplemented in Wt::Auth::Dbo::UserDatabase< DboType >.

◆ addIdentity()

virtual void Wt::Auth::AbstractUserDatabase::addIdentity	(	const User &	user,
		const std::string &	provider,
		const WString &	id
	)

pure virtual

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, ...).

Implemented in Wt::Auth::Dbo::UserDatabase< DboType >.

◆ deleteUser()

void Wt::Auth::AbstractUserDatabase::deleteUser ( const User & user )

virtual

Delete a user.

This deletes a user from the database.

Reimplemented in Wt::Auth::Dbo::UserDatabase< DboType >.

◆ email()

std::string Wt::Auth::AbstractUserDatabase::email ( const User & user ) const

virtual

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.

Reimplemented in Wt::Auth::Dbo::UserDatabase< DboType >.

◆ emailToken()

Token Wt::Auth::AbstractUserDatabase::emailToken ( const User & user ) const

virtual

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

Reimplemented in Wt::Auth::Dbo::UserDatabase< DboType >.

◆ emailTokenRole()

EmailTokenRole Wt::Auth::AbstractUserDatabase::emailTokenRole ( const User & user ) const

virtual

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().

Reimplemented in Wt::Auth::Dbo::UserDatabase< DboType >.

◆ failedLoginAttempts()

int Wt::Auth::AbstractUserDatabase::failedLoginAttempts ( const User & user ) const

virtual

Returns the number of consecutive authentication failures.

setFailedLoginAttempts()

Reimplemented in Wt::Auth::Dbo::UserDatabase< DboType >.

◆ findWithAuthToken()

User Wt::Auth::AbstractUserDatabase::findWithAuthToken ( const std::string & hash ) const

virtual

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.

The authentication token can be used for two means:

used for the normal authentication, denoting a regular username/password login. If the "remember-me" functionality is enabled for it, and selected, a token will be produced, named according to AuthService::authTokenCookieName(), and valid for AuthService::authTokenValidity() (in minutes). Both can be set by enabling authentication tokens with AuthService::setAuthTokensEnabled(). By default the cookie will be called "wtauth" and will be valid for two weeks.
used for the multi-factor verification, currently this is to be implemented by the developer if they want anything other than Wt's default of TOTP (see Mfa::TotpProcess). This functions identical to the other authentication token, and is enabled the same way. The name can be changed by AuthService::setMfaTokenCookieName, and its duration by AuthService::setMfaTokenValidity() (in minutes). By default the cookie will be called "wtauth-mfa" and it will be valid indefinitely.

Reimplemented in Wt::Auth::Dbo::UserDatabase< DboType >.

◆ findWithEmail()

User Wt::Auth::AbstractUserDatabase::findWithEmail ( const std::string & address ) const

virtual

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.

Reimplemented in Wt::Auth::Dbo::UserDatabase< DboType >.

◆ findWithEmailToken()

User Wt::Auth::AbstractUserDatabase::findWithEmailToken ( const std::string & hash ) const

virtual

Finds a user with a given email token.

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

Reimplemented in Wt::Auth::Dbo::UserDatabase< DboType >.

◆ findWithId()

virtual User Wt::Auth::AbstractUserDatabase::findWithId ( const std::string & id ) const

pure virtual

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.

Implemented in Wt::Auth::Dbo::UserDatabase< DboType >.

◆ findWithIdentity()

virtual User Wt::Auth::AbstractUserDatabase::findWithIdentity	(	const std::string &	provider,
		const WString &	identity
	)		const

pure virtual

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.

Implemented in Wt::Auth::Dbo::UserDatabase< DboType >.

◆ identity()

virtual WString Wt::Auth::AbstractUserDatabase::identity	(	const User &	user,
		const std::string &	provider
	)		const

pure virtual

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: addIdentity()

Implemented in Wt::Auth::Dbo::UserDatabase< DboType >.

◆ idpJsonClaim()

Json::Value Wt::Auth::AbstractUserDatabase::idpJsonClaim	(	const User &	user,
		const std::string &	claim
	)		const

virtual

Returns the value of a claim for a user.

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

◆ lastLoginAttempt()

WDateTime Wt::Auth::AbstractUserDatabase::lastLoginAttempt ( const User & user ) const

virtual

Returns the time of the last login.

See also: setLastLoginAttempt()

Reimplemented in Wt::Auth::Dbo::UserDatabase< DboType >.

◆ password()

PasswordHash Wt::Auth::AbstractUserDatabase::password ( const User & user ) const

virtual

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.

Reimplemented in Wt::Auth::Dbo::UserDatabase< DboType >.

◆ registerNew()

User Wt::Auth::AbstractUserDatabase::registerNew ( )

virtual

Registers a new user.

This adds a new user.

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

Reimplemented in Wt::Auth::Dbo::UserDatabase< DboType >.

◆ removeAuthToken()

void Wt::Auth::AbstractUserDatabase::removeAuthToken	(	const User &	user,
		const std::string &	hash
	)

virtual

Deletes an authentication token.

Deletes an authentication token previously added with addAuthToken().

Note: This deletes the local entry in the database (in table "auth_token"). It will not remove the cookie from the User's browser.

Reimplemented in Wt::Auth::Dbo::UserDatabase< DboType >.

◆ removeIdentity()

virtual void Wt::Auth::AbstractUserDatabase::removeIdentity	(	const User &	user,
		const std::string &	provider
	)

pure virtual

Removes a user identity.

This removes all identities of a provider from the user.

See also: addIdentity()

Implemented in Wt::Auth::Dbo::UserDatabase< DboType >.

◆ setEmail()

bool Wt::Auth::AbstractUserDatabase::setEmail	(	const User &	user,
		const std::string &	address
	)

virtual

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

Reimplemented in Wt::Auth::Dbo::UserDatabase< DboType >.

◆ setEmailToken()

void Wt::Auth::AbstractUserDatabase::setEmailToken	(	const User &	user,
		const Token &	token,
		EmailTokenRole	role
	)

virtual

Sets a new email token for a user.

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

Reimplemented in Wt::Auth::Dbo::UserDatabase< DboType >.

◆ setFailedLoginAttempts()

void Wt::Auth::AbstractUserDatabase::setFailedLoginAttempts	(	const User &	user,
		int	count
	)

virtual

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.

Reimplemented in Wt::Auth::Dbo::UserDatabase< DboType >.

◆ setIdentity()

void Wt::Auth::AbstractUserDatabase::setIdentity	(	const User &	user,
		const std::string &	provider,
		const WString &	id
	)

virtual

Changes an identity for a user.

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

Reimplemented in Wt::Auth::Dbo::UserDatabase< DboType >.

◆ setLastLoginAttempt()

void Wt::Auth::AbstractUserDatabase::setLastLoginAttempt	(	const User &	user,
		const WDateTime &	t
	)

virtual

Sets the time of the last login attempt.

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

Reimplemented in Wt::Auth::Dbo::UserDatabase< DboType >.

◆ setPassword()

void Wt::Auth::AbstractUserDatabase::setPassword	(	const User &	user,
		const PasswordHash &	password
	)

virtual

Sets a new user password.

This updates the password for a user.

This is used only by PasswordService.

Reimplemented in Wt::Auth::Dbo::UserDatabase< DboType >.

◆ setStatus()

void Wt::Auth::AbstractUserDatabase::setStatus	(	const User &	user,
		AccountStatus	status
	)

virtual

Sets the user status.

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

Reimplemented in Wt::Auth::Dbo::UserDatabase< DboType >.

◆ setUnverifiedEmail()

void Wt::Auth::AbstractUserDatabase::setUnverifiedEmail	(	const User &	user,
		const std::string &	address
	)

virtual

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.

Reimplemented in Wt::Auth::Dbo::UserDatabase< DboType >.

◆ startTransaction()

AbstractUserDatabase::Transaction * Wt::Auth::AbstractUserDatabase::startTransaction ( )

virtual

Creates a new database transaction.

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

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

The default implementation returns nullptr (no transaction support).

Reimplemented in Wt::Auth::Dbo::UserDatabase< DboType >.

◆ status()

AccountStatus Wt::Auth::AbstractUserDatabase::status ( const User & user ) const

virtual

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.

See also: Login::loginState()

Reimplemented in Wt::Auth::Dbo::UserDatabase< DboType >.

◆ unverifiedEmail()

std::string Wt::Auth::AbstractUserDatabase::unverifiedEmail ( const User & user ) const

virtual

Returns a user's unverified email address.

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

Reimplemented in Wt::Auth::Dbo::UserDatabase< DboType >.

◆ updateAuthToken()

int Wt::Auth::AbstractUserDatabase::updateAuthToken	(	const User &	user,
		const std::string &	oldhash,
		const std::string &	newhash
	)

virtual

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.

Reimplemented in Wt::Auth::Dbo::UserDatabase< DboType >.

Classes

Public Member Functions

Detailed Description

Member Function Documentation

◆ addAuthToken()

◆ addIdentity()

◆ deleteUser()

◆ email()

◆ emailToken()

◆ emailTokenRole()

◆ failedLoginAttempts()

◆ findWithAuthToken()

◆ findWithEmail()

◆ findWithEmailToken()

◆ findWithId()

◆ findWithIdentity()

◆ identity()

◆ idpJsonClaim()

◆ lastLoginAttempt()

◆ password()

◆ registerNew()

◆ removeAuthToken()

◆ removeIdentity()

◆ setEmail()

◆ setEmailToken()

◆ setFailedLoginAttempts()

◆ setIdentity()

◆ setLastLoginAttempt()

◆ setPassword()

◆ setStatus()

◆ setUnverifiedEmail()

◆ startTransaction()

◆ status()

◆ unverifiedEmail()

◆ updateAuthToken()