Wt  4.11.0
Loading...
Searching...
No Matches
Public Member Functions | List of all members
Wt::Auth::Dbo::UserDatabase< DboType > Class Template Reference

A default implementation for an authentication user database. More...

#include <Wt/Auth/Dbo/UserDatabase.h>

Inheritance diagram for Wt::Auth::Dbo::UserDatabase< DboType >:
[legend]

Public Member Functions

 UserDatabase (Wt::Dbo::Session &session, const AuthService *authService=0)
 Constructor.
 
void setNewUserStatus (AccountStatus status)
 Sets the initial status for a new user.
 
virtual TransactionstartTransaction () override
 Creates a new database transaction.
 
Wt::Dbo::ptr< DboTypefind (const User &user) const
 Returns the Dbo user type corresponding to an Auth::User.
 
User find (const Wt::Dbo::ptr< DboType > user) const
 Returns the Auth::User corresponding to a Dbo user.
 
virtual User findWithId (const std::string &id) const override
 Finds a user with a given id.
 
virtual User findWithIdentity (const std::string &provider, const WString &identity) const override
 Finds a user with a given identity.
 
virtual WString identity (const User &user, const std::string &provider) const override
 Returns a user identity.
 
virtual void removeIdentity (const User &user, const std::string &provider) override
 Removes a user identity.
 
virtual User registerNew () override
 Registers a new user.
 
virtual void deleteUser (const User &user) override
 Delete a user.
 
virtual AccountStatus status (const User &user) const override
 Returns the status for a user.
 
virtual void setStatus (const User &user, AccountStatus status) override
 Sets the user status.
 
virtual void setPassword (const User &user, const PasswordHash &password) override
 Sets a new user password.
 
virtual PasswordHash password (const User &user) const override
 Returns a user password.
 
virtual void addIdentity (const User &user, const std::string &provider, const WString &identity) override
 Adds an identify for the user.
 
virtual void setIdentity (const User &user, const std::string &provider, const WString &identity) override
 Changes an identity for a user.
 
virtual bool setEmail (const User &user, const std::string &address) override
 Sets a user's email address.
 
virtual std::string email (const User &user) const override
 Returns a user's email address.
 
virtual void setUnverifiedEmail (const User &user, const std::string &address) override
 Sets a user's unverified email address.
 
virtual std::string unverifiedEmail (const User &user) const override
 Returns a user's unverified email address.
 
virtual User findWithEmail (const std::string &address) const override
 Finds a user with a given email address.
 
virtual void setEmailToken (const User &user, const Token &token, EmailTokenRole role) override
 Sets a new email token for a user.
 
virtual Token emailToken (const User &user) const override
 Returns an email token.
 
virtual EmailTokenRole emailTokenRole (const User &user) const override
 Returns the role of the current email token.
 
virtual User findWithEmailToken (const std::string &hash) const override
 Finds a user with a given email token.
 
virtual void addAuthToken (const User &user, const Token &token) override
 Adds an authentication token to a user.
 
virtual void removeAuthToken (const User &user, const std::string &hash) override
 Deletes an authentication token.
 
virtual int updateAuthToken (const User &user, const std::string &hash, const std::string &newHash) override
 Updates the authentication token with a new hash.
 
virtual User findWithAuthToken (const std::string &hash) const override
 Finds a user with an authentication token.
 
virtual void setFailedLoginAttempts (const User &user, int count) override
 Sets the number of consecutive authentication failures.
 
virtual int failedLoginAttempts (const User &user) const override
 Returns the number of consecutive authentication failures.
 
virtual void setLastLoginAttempt (const User &user, const WDateTime &t) override
 Sets the time of the last login attempt.
 
virtual WDateTime lastLoginAttempt (const User &user) const override
 Returns the time of the last login.
 
unsigned maxAuthTokensPerUser () const
 Returns max number of tokens user can have in the database.
 
void setMaxAuthTokensPerUser (unsigned maxAuthTokensPerUser)
 Sets max number of tokens user can have in the database.
 
- Public Member Functions inherited from Wt::Auth::AbstractUserDatabase
virtual ~AbstractUserDatabase ()
 Destructor.
 
virtual Json::Value idpJsonClaim (const User &user, const std::string &claim) const
 Returns the value of a claim for a user.
 
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

template<class DboType>
class Wt::Auth::Dbo::UserDatabase< DboType >

A default implementation for an authentication user database.

This is a template class, and needs as parameter the Dbo type which models the authentication information. A suitable implementation, which stores authentication information outside the "user" class, is provided by AuthInfo.

See also
AuthInfo

Constructor & Destructor Documentation

◆ UserDatabase()

template<class DboType >
Wt::Auth::Dbo::UserDatabase< DboType >::UserDatabase ( Wt::Dbo::Session session,
const AuthService authService = 0 
)

Constructor.

The AuthService parameter is optional, and decides some of the UserDatabase's behaviour. Currently, this decides whether findWithIdentity() should be case sensitive or not. If the identity policy of the AuthService is EmailAddressIdentity, then findWithIdentity() will be case insensitive. Otherwise it is case sensitive.

Member Function Documentation

◆ addAuthToken()

template<class DboType >
virtual void Wt::Auth::Dbo::UserDatabase< DboType >::addAuthToken ( const User user,
const Token token 
)
overridevirtual

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 from Wt::Auth::AbstractUserDatabase.

◆ addIdentity()

template<class DboType >
virtual void Wt::Auth::Dbo::UserDatabase< DboType >::addIdentity ( const User user,
const std::string &  provider,
const WString id 
)
overridevirtual

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

Implements Wt::Auth::AbstractUserDatabase.

◆ deleteUser()

template<class DboType >
virtual void Wt::Auth::Dbo::UserDatabase< DboType >::deleteUser ( const User user)
overridevirtual

Delete a user.

This deletes a user from the database.

Reimplemented from Wt::Auth::AbstractUserDatabase.

◆ email()

template<class DboType >
virtual std::string Wt::Auth::Dbo::UserDatabase< DboType >::email ( const User user) const
overridevirtual

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 from Wt::Auth::AbstractUserDatabase.

◆ emailToken()

template<class DboType >
virtual Token Wt::Auth::Dbo::UserDatabase< DboType >::emailToken ( const User user) const
overridevirtual

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 from Wt::Auth::AbstractUserDatabase.

◆ emailTokenRole()

template<class DboType >
virtual EmailTokenRole Wt::Auth::Dbo::UserDatabase< DboType >::emailTokenRole ( const User user) const
overridevirtual

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 from Wt::Auth::AbstractUserDatabase.

◆ failedLoginAttempts()

template<class DboType >
virtual int Wt::Auth::Dbo::UserDatabase< DboType >::failedLoginAttempts ( const User user) const
overridevirtual

Returns the number of consecutive authentication failures.

setFailedLoginAttempts()

Reimplemented from Wt::Auth::AbstractUserDatabase.

◆ findWithAuthToken()

template<class DboType >
virtual User Wt::Auth::Dbo::UserDatabase< DboType >::findWithAuthToken ( const std::string &  hash) const
overridevirtual

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 from Wt::Auth::AbstractUserDatabase.

◆ findWithEmail()

template<class DboType >
virtual User Wt::Auth::Dbo::UserDatabase< DboType >::findWithEmail ( const std::string &  address) const
overridevirtual

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 from Wt::Auth::AbstractUserDatabase.

◆ findWithEmailToken()

template<class DboType >
virtual User Wt::Auth::Dbo::UserDatabase< DboType >::findWithEmailToken ( const std::string &  hash) const
overridevirtual

Finds a user with a given email token.

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

Reimplemented from Wt::Auth::AbstractUserDatabase.

◆ findWithId()

template<class DboType >
virtual User Wt::Auth::Dbo::UserDatabase< DboType >::findWithId ( const std::string &  id) const
overridevirtual

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.

Implements Wt::Auth::AbstractUserDatabase.

◆ findWithIdentity()

template<class DboType >
virtual User Wt::Auth::Dbo::UserDatabase< DboType >::findWithIdentity ( const std::string &  provider,
const WString identity 
) const
overridevirtual

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.

Implements Wt::Auth::AbstractUserDatabase.

◆ identity()

template<class DboType >
virtual WString Wt::Auth::Dbo::UserDatabase< DboType >::identity ( const User user,
const std::string &  provider 
) const
overridevirtual

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

Implements Wt::Auth::AbstractUserDatabase.

◆ lastLoginAttempt()

template<class DboType >
virtual WDateTime Wt::Auth::Dbo::UserDatabase< DboType >::lastLoginAttempt ( const User user) const
overridevirtual

Returns the time of the last login.

See also
setLastLoginAttempt()

Reimplemented from Wt::Auth::AbstractUserDatabase.

◆ maxAuthTokensPerUser()

template<class DboType >
unsigned Wt::Auth::Dbo::UserDatabase< DboType >::maxAuthTokensPerUser ( ) const

Returns max number of tokens user can have in the database.

Default value is 50.

◆ password()

template<class DboType >
virtual PasswordHash Wt::Auth::Dbo::UserDatabase< DboType >::password ( const User user) const
overridevirtual

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 from Wt::Auth::AbstractUserDatabase.

◆ registerNew()

template<class DboType >
virtual User Wt::Auth::Dbo::UserDatabase< DboType >::registerNew ( )
overridevirtual

Registers a new user.

This adds a new user.

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

Reimplemented from Wt::Auth::AbstractUserDatabase.

◆ removeAuthToken()

template<class DboType >
virtual void Wt::Auth::Dbo::UserDatabase< DboType >::removeAuthToken ( const User user,
const std::string &  hash 
)
overridevirtual

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 from Wt::Auth::AbstractUserDatabase.

◆ removeIdentity()

template<class DboType >
virtual void Wt::Auth::Dbo::UserDatabase< DboType >::removeIdentity ( const User user,
const std::string &  provider 
)
overridevirtual

Removes a user identity.

This removes all identities of a provider from the user.

See also
addIdentity()

Implements Wt::Auth::AbstractUserDatabase.

◆ setEmail()

template<class DboType >
virtual bool Wt::Auth::Dbo::UserDatabase< DboType >::setEmail ( const User user,
const std::string &  address 
)
overridevirtual

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 from Wt::Auth::AbstractUserDatabase.

◆ setEmailToken()

template<class DboType >
virtual void Wt::Auth::Dbo::UserDatabase< DboType >::setEmailToken ( const User user,
const Token token,
EmailTokenRole  role 
)
overridevirtual

Sets a new email token for a user.

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

Reimplemented from Wt::Auth::AbstractUserDatabase.

◆ setFailedLoginAttempts()

template<class DboType >
virtual void Wt::Auth::Dbo::UserDatabase< DboType >::setFailedLoginAttempts ( const User user,
int  count 
)
overridevirtual

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 from Wt::Auth::AbstractUserDatabase.

◆ setIdentity()

template<class DboType >
virtual void Wt::Auth::Dbo::UserDatabase< DboType >::setIdentity ( const User user,
const std::string &  provider,
const WString id 
)
overridevirtual

Changes an identity for a user.

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

Reimplemented from Wt::Auth::AbstractUserDatabase.

◆ setLastLoginAttempt()

template<class DboType >
virtual void Wt::Auth::Dbo::UserDatabase< DboType >::setLastLoginAttempt ( const User user,
const WDateTime t 
)
overridevirtual

Sets the time of the last login attempt.

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

Reimplemented from Wt::Auth::AbstractUserDatabase.

◆ setNewUserStatus()

template<class DboType >
void Wt::Auth::Dbo::UserDatabase< DboType >::setNewUserStatus ( AccountStatus  status)

Sets the initial status for a new user.

This status is set on a user that just registered.

The default value is AccountStatus::Normal.

◆ setPassword()

template<class DboType >
virtual void Wt::Auth::Dbo::UserDatabase< DboType >::setPassword ( const User user,
const PasswordHash password 
)
overridevirtual

Sets a new user password.

This updates the password for a user.

This is used only by PasswordService.

Reimplemented from Wt::Auth::AbstractUserDatabase.

◆ setStatus()

template<class DboType >
virtual void Wt::Auth::Dbo::UserDatabase< DboType >::setStatus ( const User user,
AccountStatus  status 
)
overridevirtual

Sets the user status.

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

Reimplemented from Wt::Auth::AbstractUserDatabase.

◆ setUnverifiedEmail()

template<class DboType >
virtual void Wt::Auth::Dbo::UserDatabase< DboType >::setUnverifiedEmail ( const User user,
const std::string &  address 
)
overridevirtual

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 from Wt::Auth::AbstractUserDatabase.

◆ startTransaction()

template<class DboType >
virtual Transaction * Wt::Auth::Dbo::UserDatabase< DboType >::startTransaction ( )
overridevirtual

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 from Wt::Auth::AbstractUserDatabase.

◆ status()

template<class DboType >
virtual AccountStatus Wt::Auth::Dbo::UserDatabase< DboType >::status ( const User user) const
overridevirtual

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 from Wt::Auth::AbstractUserDatabase.

◆ unverifiedEmail()

template<class DboType >
virtual std::string Wt::Auth::Dbo::UserDatabase< DboType >::unverifiedEmail ( const User user) const
overridevirtual

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 from Wt::Auth::AbstractUserDatabase.

◆ updateAuthToken()

template<class DboType >
virtual int Wt::Auth::Dbo::UserDatabase< DboType >::updateAuthToken ( const User user,
const std::string &  oldhash,
const std::string &  newhash 
)
overridevirtual

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 from Wt::Auth::AbstractUserDatabase.