Wt: Wt::Auth::AuthService Class Reference

Wt 4.10.4

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.
HashFunction * | tokenHashFunction () 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.

## 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):

- settings for generating random tokens:
  - setRandomTokenLength()
- authentication tokens, used by e.g. remember-me functionality:
  - setAuthTokensEnabled()
  - processAuthToken()
- email tokens, for email verification and lost password functions:
  - setEmailVerificationEnabled()
  - lostPassword()
  - verifyEmailAddress()
  - processEmailToken()

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

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

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

## ◆ parseEmailToken()

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

virtual 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. If it matches and auth token update is enabled, the token is updated with a new hash.

See also
  setAuthTokenUpdateEnabled()
  AbstractUserDatabase::updateAuthToken()

## ◆ processEmailToken()

virtual 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:

- EmailTokenState::EmailConfirmed: a token was presented which proves that the user is tied to the email address.
- EmailTokenState::UpdatePassword: a token was presented which requires the user to enter a new password.

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

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

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

virtual 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.

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.

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.

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

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