Wt  4.11.0
Loading...
Searching...
No Matches
Public Member Functions | Protected Member Functions | List of all members
Wt::Auth::AuthService Class Reference

Basic authentication service. More...

#include <Wt/Auth/AuthService.h>

Public Member Functions

 AuthService ()
 Constructor.
 
virtual ~AuthService ()
 Destructor.
 
void setRandomTokenLength (int length)
 Sets the token length.
 
int randomTokenLength () const
 Returns the token length.
 
void setIdentityPolicy (IdentityPolicy policy)
 Configures the identity policy.
 
IdentityPolicy identityPolicy () const
 Returns the identity policy.
 
virtual User identifyUser (const Identity &identity, AbstractUserDatabase &users) const
 Tries to match the identity to an existing user.
 
Authentication token support
void setAuthTokensEnabled (bool enabled, const std::string &cookieName="wtauth", const std::string &cookieDomain=std::string())
 Configures authentication token support.
 
bool authTokensEnabled () const
 Returns whether authentication tokens are enabled.
 
void setAuthTokenUpdateEnabled (bool enabled)
 Set whether processAuthToken() updates the auth token.
 
bool authTokenUpdateEnabled () const
 Returns whether the auth token is updated.
 
std::string authTokenCookieName () const
 Returns the authentication token cookie name.
 
std::string authTokenCookieDomain () const
 Returns the authentication token cookie domain.
 
void setTokenHashFunction (std::unique_ptr< HashFunction > function)
 Sets the token hash function.
 
HashFunctiontokenHashFunction () const
 Returns the token hash function.
 
std::string createAuthToken (const User &user) const
 Creates and stores an authentication token for the user.
 
virtual AuthTokenResult processAuthToken (const std::string &token, AbstractUserDatabase &users) const
 Processes an authentication token.
 
void setAuthTokenValidity (int minutes)
 Configures the duration for an authenticaton to remain valid.
 
int authTokenValidity () const
 Returns the authentication token validity.
 
Email verification
void setEmailVerificationEnabled (bool enabled)
 Configures email verification.
 
bool emailVerificationEnabled () const
 Returns whether email verification is configured.
 
void setEmailVerificationRequired (bool enabled)
 Configure email verificiation to be required for login.
 
bool emailVerificationRequired () const
 
void setEmailRedirectInternalPath (const std::string &internalPath)
 Sets the internal path used to present tokens in emails.
 
std::string emailRedirectInternalPath () const
 Returns the internal path used for email tokens.
 
virtual std::string parseEmailToken (const std::string &internalPath) const
 Parses the emailtoken from an internal path.
 
virtual void verifyEmailAddress (const User &user, const std::string &emailAddress) const
 Verifies an email address.
 
virtual void lostPassword (const std::string &emailAddress, AbstractUserDatabase &users) const
 Implements lost password functionality.
 
virtual EmailTokenResult processEmailToken (const std::string &token, AbstractUserDatabase &users) const
 Processes an email token.
 
void setEmailTokenValidity (int minutes)
 Configures the duration for an email token to remain valid.
 
int emailTokenValidity () const
 Returns the duration for an email token to remain valid.
 
virtual void sendMail (const Mail::Message &message) const
 Sends an email.
 
Multi-factor authentication (Time-Based One-Time Password).
void setMfaProvider (const std::string &provider)
 Sets whether multiple factors are enabled when logging in.
 
const std::string & mfaProvider () const
 Returns the provider that manages the MFA step.
 
bool mfaEnabled () const
 Returns whether a second factor is enabled when logging in.
 
void setMfaRequired (bool required)
 Sets whether multiple factors are required when logging in.
 
bool mfaRequired () const
 Returns whether multiple factors are required when logging in.
 
void setMfaCodeLength (int length)
 Sets the length of the code that is expected for MFA.
 
int mfaCodeLength () const
 Returns the length of the expected MFA codes.
 
void setMfaTokenCookieName (const std::string &name)
 Sets the name of the cookie used for MFA "remember-me".
 
const std::string & mfaTokenCookieName () const
 Returns the name of the MFA "remember-me" cookie.
 
void setMfaTokenCookieDomain (const std::string &domain)
 Returns the domain of the MFA "remember-me" cookie.
 
const std::string & mfaTokenCookieDomain () const
 Returns the MFA token cookie domain.
 
void setMfaTokenValidity (int validity)
 Sets the validity duration of the MFA "remember-me" cookie.
 
int mfaTokenValidity () const
 Returns the validity span of the MFA "remember-me" cookie.
 
void setMfaThrottleEnabled (bool enabled)
 Sets whether throttling is enabled during the MFA process.
 
bool mfaThrottleEnabled () const
 Returns if throttling is enabled during the MFA process.
 

Protected Member Functions

virtual void sendConfirmMail (const std::string &address, const User &user, const std::string &token) const
 Sends a confirmation email to the user to verify his email address.
 
virtual void sendLostPasswordMail (const std::string &address, const User &user, const std::string &token) const
 Sends an email to the user to enter a new password.
 

Detailed Description

Basic authentication service.

This class presents an basic authentication service, which offers authentication functionality that is not specific to an authentication mechanism (such as password authentication or OAuth authentication).

Like all service classes, this class holds only configuration state. Thus, once configured, it can be safely shared between multiple sessions since its state (the configuration) is read-only. A "const AuthService" object is thus thread-safe.

The class provides the following services (and relevant configuration):

Member Function Documentation

◆ authTokenCookieDomain()

std::string Wt::Auth::AuthService::authTokenCookieDomain ( ) const

Returns the authentication token cookie domain.

This is the domain used for the authentication cookie. By default this is empty, which means that a cookie will be set for this application.

You may want to set a more general domain if you are sharing the authentication with multiple applications.

See also
setAuthTokensEnabled()

◆ authTokenCookieName()

std::string Wt::Auth::AuthService::authTokenCookieName ( ) const

Returns the authentication token cookie name.

This is the default cookie name used for storing the authentication token in the user's browser.

See also
setAuthTokensEnabled()

◆ authTokensEnabled()

bool Wt::Auth::AuthService::authTokensEnabled ( ) const

Returns whether authentication tokens are enabled.

See also
setAuthTokensEnabled()

◆ authTokenUpdateEnabled()

bool Wt::Auth::AuthService::authTokenUpdateEnabled ( ) const

Returns whether the auth token is updated.

See also
setAuthTokenUpdateEnabled()

◆ authTokenValidity()

int Wt::Auth::AuthService::authTokenValidity ( ) const

Returns the authentication token validity.

See also
setAuthTokenValidity()

◆ createAuthToken()

std::string Wt::Auth::AuthService::createAuthToken ( const User user) const

Creates and stores an authentication token for the user.

This creates and stores a new authentication token for the given user.

The returned value is the token that may be used to re-identify the user in processAuthToken().

◆ emailRedirectInternalPath()

std::string Wt::Auth::AuthService::emailRedirectInternalPath ( ) const

Returns the internal path used for email tokens.

See also
setEmailRedirectInternalPath()

◆ emailTokenValidity()

int Wt::Auth::AuthService::emailTokenValidity ( ) const

Returns the duration for an email token to remain valid.

See also
setEmailTokenValidity()

◆ emailVerificationEnabled()

bool Wt::Auth::AuthService::emailVerificationEnabled ( ) const

Returns whether email verification is configured.

See also
setEmailVerificationEnabled()

◆ emailVerificationRequired()

bool Wt::Auth::AuthService::emailVerificationRequired ( ) const

\ Returns whether email verification is required for login.

See also
setEmailVerificationRequired()

◆ identifyUser()

User Wt::Auth::AuthService::identifyUser ( const Identity identity,
AbstractUserDatabase users 
) const
virtual

Tries to match the identity to an existing user.

When authenticating using a 3rd party Identity Provider, the identity is matched against the existing users, based on the id (with AbstractUserDatabase::findWithIdentity()), or if not matched, based on whether there is a user with the same verified email address as the one indicated by the identity.

◆ identityPolicy()

IdentityPolicy Wt::Auth::AuthService::identityPolicy ( ) const

Returns the identity policy.

See also
setIdentityPolicy()

◆ lostPassword()

void Wt::Auth::AuthService::lostPassword ( const std::string &  emailAddress,
AbstractUserDatabase users 
) const
virtual

Implements lost password functionality.

If email address verification is enabled, then a user may recover his password (or rather, chose a new password) using a procedure which involves sending an email to a verified email address.

This method triggers this process, starting from an email address, if this email address corresponds to a verified email address in the database. The current password is not invalidated.

See also
processEmailToken()

◆ mfaCodeLength()

int Wt::Auth::AuthService::mfaCodeLength ( ) const

Returns the length of the expected MFA codes.

See also
setMfaCodeLength()

◆ mfaEnabled()

bool Wt::Auth::AuthService::mfaEnabled ( ) const

Returns whether a second factor is enabled when logging in.

This marks that users can enable the MFA feature. This can be any implemenation of the Mfa::AbstractMfaProcess interface. Wt supplies a single default implementation, namely Mfa::TotpProcess.

For the default Wt implementation, this means that developers can generate a TOTP secret key (Mfa::generateSecretKey()) which can be used for MFA, by means of the Mfa::TotpProcess.

See also
mfaRequired(), mfaCodeLength()

◆ mfaProvider()

const std::string & Wt::Auth::AuthService::mfaProvider ( ) const

Returns the provider that manages the MFA step.

See also
setMfaProvider()

◆ mfaRequired()

bool Wt::Auth::AuthService::mfaRequired ( ) const

Returns whether multiple factors are required when logging in.

This marks that the MFA feature is enforced for all users.

For Wt's default implementation this means that upon logging in they will have to provide a TOTP code for verification.

See also
setMfaRequired()

◆ mfaThrottleEnabled()

bool Wt::Auth::AuthService::mfaThrottleEnabled ( ) const

Returns if throttling is enabled during the MFA process.

See also
setMfaThrottleEnabled()

◆ mfaTokenCookieDomain()

const std::string & Wt::Auth::AuthService::mfaTokenCookieDomain ( ) const

Returns the MFA token cookie domain.

See also
setMfaTokenCookieDomain()

◆ mfaTokenCookieName()

const std::string & Wt::Auth::AuthService::mfaTokenCookieName ( ) const

Returns the name of the MFA "remember-me" cookie.

This can be configured by the developer, or otherwise uses the same name as authTokenCookieName() with the "-mfa" suffix. If nothing is changed, the default is "wtauth-mfa".

◆ mfaTokenValidity()

int Wt::Auth::AuthService::mfaTokenValidity ( ) const

Returns the validity span of the MFA "remember-me" cookie.

See also
setMfaTokenValidity()

◆ parseEmailToken()

std::string Wt::Auth::AuthService::parseEmailToken ( const std::string &  internalPath) const
virtual

Parses the emailtoken from an internal path.

This method parses an internal path and if it matches the email redirection path, it returns the token contained.

It returns an empty string if the internal path does not contain an email token.

◆ processAuthToken()

AuthTokenResult Wt::Auth::AuthService::processAuthToken ( const std::string &  token,
AbstractUserDatabase users 
) const
virtual

Processes an authentication token.

This verifies an authentication token, and considers whether it matches with a token hash value stored in database. This indicates that the cookie a User has in their browser is still valid, and can be used to uniquely identify them.

If it matches and auth token update is enabled (setAuthTokenUpdateEnabled()), the token is updated with a new hash.

See also
setAuthTokensEnabled()
AbstractUserDatabase::updateAuthToken()

◆ processEmailToken()

EmailTokenResult Wt::Auth::AuthService::processEmailToken ( const std::string &  token,
AbstractUserDatabase users 
) const
virtual

Processes an email token.

This processes a token received through an email. If it is an email verification token, the token is removed from the database.

This may return two successful results:

Note
Since Wt 4.3.0, the behavior of this function changed. The lost password token is no longer removed by processEmailToken(). Instead, it is now removed in User::setPassword().
See also
verifyEmailAddress()
lostPassword()

◆ randomTokenLength()

int Wt::Auth::AuthService::randomTokenLength ( ) const

Returns the token length.

See also
setRandomTokenLength()

◆ sendConfirmMail()

void Wt::Auth::AuthService::sendConfirmMail ( const std::string &  address,
const User user,
const std::string &  token 
) const
protectedvirtual

Sends a confirmation email to the user to verify his email address.

Sends a confirmation email to the given address.

The email content is provided by the following string keys:

  • subject: tr("Wt.auth.verification-mail.subject")
  • body: tr("Wt.auth.verification-mail.body") with {1} a place holder for the identity, and {2} a placeholder for the redirection URL.
  • HTML body: tr("Wt.auth.verification-mail.htmlbody") with the same place holders.

◆ sendLostPasswordMail()

void Wt::Auth::AuthService::sendLostPasswordMail ( const std::string &  address,
const User user,
const std::string &  token 
) const
protectedvirtual

Sends an email to the user to enter a new password.

This sends a lost password email to the given address, with a given token.

The default implementation will call sendMail() with the following message:

  • tr("Wt.Auth.lost-password-mail.subject") as subject,
  • tr("Wt.Auth.lost-password-mail.body") as body to which it passes user.identity() and token as arguments.
  • tr("Wt.Auth.lost-password-mail.htmlbody") as HTML body to which it passes user.identity() and token as arguments.

◆ sendMail()

void Wt::Auth::AuthService::sendMail ( const Mail::Message message) const
virtual

Sends an email.

Sends an email to the given address with subject and body.

The default implementation will consult configuration properties to add a sender address if it hasn't already been set:

  • "auth-mail-sender-name": the sender name, with default value "Wt Auth module"
  • "auth-mail-sender-address": the sender email address, with default value "noreply-auth@www.webtoolkit.eu"

Then it uses Mail::Client to send the message, using default the default client settings.

◆ setAuthTokensEnabled()

void Wt::Auth::AuthService::setAuthTokensEnabled ( bool  enabled,
const std::string &  cookieName = "wtauth",
const std::string &  cookieDomain = std::string() 
)

Configures authentication token support.

This method allows you to configure whether authentication tokens are in use. Authentication tokens are used for the user to bypass a more elaborate authentication method, and are a secret shared with the user's user agent, usually in a cookie. They are typically presented in the user interfaces as a "remember me" option.

Whenever a valid authentication token is presented in processToken(), it is invalidated a new token is generated and stored for the user.

The tokens are generated and subsequently hashed using the token hash function. Only the hash values are stored in the user database so that a compromised user database does not compromise these tokens.

Authentication tokens are disabled by default.

The default name for these cookies is wtauth, and if MFA is enabled, their corresponding name will be wtauth-mfa. The name of these tokens can be changed (setMfaTokenCookieName()).

See also
setTokenHashFunction(), setAuthTokenValidity()

◆ setAuthTokenUpdateEnabled()

void Wt::Auth::AuthService::setAuthTokenUpdateEnabled ( bool  enabled)

Set whether processAuthToken() updates the auth token.

If this option is enabled, processAuthToken() will replace the auth token with a new token. This is a bit more secure, because an auth token can only be used once. This is enabled by default.

However, this means that if a user concurrently opens multiple sessions within the same browsers (e.g. multiple tabs being restored at the same time) or refreshes before they receive the new cookie, the user will be logged out, unless the AbstractUserDatabase implementation takes this into account (e.g. keeps the old token valid for a little bit longer)

The default Dbo::UserDatabase does not handle concurrent token updates well, so disable this option if you want to prevent that issue.

Note
If using MFA, processAuthToken() will also use this functionality.
See also
processAuthToken()
authTokenUpdateEnabled()

◆ setAuthTokenValidity()

void Wt::Auth::AuthService::setAuthTokenValidity ( int  minutes)

Configures the duration for an authenticaton to remain valid.

The default duration is two weeks (14 * 24 * 60 minutes).

◆ setEmailRedirectInternalPath()

void Wt::Auth::AuthService::setEmailRedirectInternalPath ( const std::string &  internalPath)

Sets the internal path used to present tokens in emails.

The default path is "/auth/mail/".

◆ setEmailTokenValidity()

void Wt::Auth::AuthService::setEmailTokenValidity ( int  minutes)

Configures the duration for an email token to remain valid.

The default duration is three days (3 * 24 * 60 minutes). Three is a divine number.

◆ setEmailVerificationEnabled()

void Wt::Auth::AuthService::setEmailVerificationEnabled ( bool  enabled)

Configures email verification.

Email verification is useful for a user to recover a lost password, or to be able to confidently confirm other events with this user (such as order processing).

◆ setEmailVerificationRequired()

void Wt::Auth::AuthService::setEmailVerificationRequired ( bool  enabled)

Configure email verificiation to be required for login.

When enabled, a user will not be able to login if the email-address was not verified.

◆ setIdentityPolicy()

void Wt::Auth::AuthService::setIdentityPolicy ( IdentityPolicy  policy)

Configures the identity policy.

The identity policy has an impact on the login and registration procedure.

◆ setMfaCodeLength()

void Wt::Auth::AuthService::setMfaCodeLength ( int  length)

Sets the length of the code that is expected for MFA.

This function does not make sense for all implementations of MFA.

Currently Wt ships with a TOTP implementation, in which case the code can be any length in the range [6-16]. Of course longer is "better" generally speaking.

By default the length is 6.

Note
Due to the TOTP algorithm a longer code may not always make too much sense, as the code can start with a lot of leading zeroes. Generally a length of 6 is most often seen.
See also
setMfaProvider(), setMfaRequired()

◆ setMfaProvider()

void Wt::Auth::AuthService::setMfaProvider ( const std::string &  provider)

Sets whether multiple factors are enabled when logging in.

If this is set to any value that isn't empty, a second factor (currently only TOTP as a default implementation) will be enabled. Instead of logging the User in with the LoginState::Strong (when authenticating with a password), the state will be set to LoginState::RequiresMfa.

This indicates that the user is still required to provide an additional login step. This applied to the regular login only. Login via OAuth does not make use of MFA. The authenticator should be sufficiently secure in itself, and should be trusted.

By default Wt offers TOTP (Time-based One-time password) as a second factor. This is a code that any authenticator app/extension can generate.

By default this feature is disabled.

Note
If a value for a provider is set here, MFA will be enabled. This will use TOTP by default. Any custom implementation (using Mfa::AbstractMfaProcess) will require more changes.
See also
AuthWidget::createMfaProcess(), AuthWidget::createMfaView(), and AuthModel::hasMfaStep().
setMfaRequired(), setMfaCodeLength(), setMfaTokenValidity()

◆ setMfaRequired()

void Wt::Auth::AuthService::setMfaRequired ( bool  required)

Sets whether multiple factors are required when logging in.

If this is set to true, a second factor (defaulting to TOTP) will be required on login. Instead of logging the User in with the LoginState::Strong (when authenticating with a password), the state will be set to LoginState::RequiresMfa.

This will only take effect is mfaEnabled() is true as well (and thus if an MFA provider has been configured (setMfaProvider()). If this is the case, all users will be enforced to verify their login with an extra step, for more security.

By Wt's default implementation this will boil down to providing a TOTP code. Either this will be the first time they do this. In which case they will be given the secret key both in QR code format (using Mfa::AbstractMfaWidgget::createSetupView()), and as a string. When they enter a correct generated code, the secret will be attached to the User record as an Identity, and will be used for subsequent login attempts (using Mfa::AbstractMfaProcess::createInputView()).

See also
setMfaProvider(), setMfaCodeLength(), setMfaTokenValidity()

◆ setMfaThrottleEnabled()

void Wt::Auth::AuthService::setMfaThrottleEnabled ( bool  enabled)

Sets whether throttling is enabled during the MFA process.

By default this is not enabled.

See also
mfaThrottleEnabled(), AbstractMfaProcess::setMfaThrottle()

◆ setMfaTokenCookieDomain()

void Wt::Auth::AuthService::setMfaTokenCookieDomain ( const std::string &  domain)

Returns the domain of the MFA "remember-me" cookie.

This can be configured by the developer, or otherwise uses the same name as authTokenCookieDomain(). If nothing is changed, the default is an empty string.

This should best be used if multiple applications are living on the same

◆ setMfaTokenCookieName()

void Wt::Auth::AuthService::setMfaTokenCookieName ( const std::string &  name)

Sets the name of the cookie used for MFA "remember-me".

This name can be changed to any name the developer desires, that is a valid name for a cookie. By default this name is the same name as authTokenCookieName() with "-mfa" appended. If this name is not changed from the default, this will result in the "wtauth-mfa" name.

Note
No check is performed for clashing names, so this can potentially override existing cookies.
See also
setMfaTokenValidity(), setAuthTokensEnabled()

◆ setMfaTokenValidity()

void Wt::Auth::AuthService::setMfaTokenValidity ( int  validity)

Sets the validity duration of the MFA "remember-me" cookie.

The duration is specified in minutes. So a validity of 1440 will keep the cookie valid for a whole day. This ensures that there is a limit on how long the User's MFA verification can be bypassed.

From a security aspect, this value should be kept on the lower side so that a user will be required to demonstrate a TOTP code often to the application, by which they validate their identity.

See also
Mfa::AbstractMfaProcess.

The default duration is 90 days.

Note
There are limits on the validity of a cookie in some browsers, so it cannot be guaranteed that "forever" is actually applicable.

◆ setRandomTokenLength()

void Wt::Auth::AuthService::setRandomTokenLength ( int  length)

Sets the token length.

Configures the length used for random tokens. Random tokens are generated for authentication tokens, and email tokens.

The default length is 32 characters.

See also
WRandom::generateId()

◆ setTokenHashFunction()

void Wt::Auth::AuthService::setTokenHashFunction ( std::unique_ptr< HashFunction function)

Sets the token hash function.

Sets the hash function used to safely store authentication tokens in the database. Ownership of the hash function is transferred.

The default token hash function is an MD5HashFunction.

◆ tokenHashFunction()

HashFunction * Wt::Auth::AuthService::tokenHashFunction ( ) const

Returns the token hash function.

See also
setTokenHashFunction()

◆ verifyEmailAddress()

void Wt::Auth::AuthService::verifyEmailAddress ( const User user,
const std::string &  emailAddress 
) const
virtual

Verifies an email address.

This registers a new email token with the user.

Then it sends an email to the user's unverified email address with instructions that redirect him to this site, using sendConfirmEmail().

See also
processEmailToken()