Safe Haskell	None
Language	Haskell2010

Yesod.Auth.Email

Contents

Plugin
Routes
Types
Misc
Default handlers
Default helpers

Description

A Yesod plugin for Authentication via e-mail

This plugin works out of the box by only setting a few methods on the type class that tell the plugin how to interoperate with your user data storage (your database). However, almost everything is customizeable by setting more methods on the type class. In addition, you can send all the form submissions via JSON and completely control the user's flow.

This is a standard registration e-mail flow

A user registers a new e-mail address, and an e-mail is sent there
The user clicks on the registration link in the e-mail. Note that at this point they are actually logged in (without a password). That means that when they log out they will need to reset their password.
The user sets their password and is redirected to the site.
The user can now
- logout and sign in
- reset their password

Using JSON Endpoints

We are assuming that you have declared auth route as follows

   /auth AuthR Auth getAuth

If you are using a different route, then you have to adjust the endpoints accordingly.

Registration

      Endpoint: /auth/page/email/register
      Method: POST
      JSON Data: {
                     "email": "myemail@domain.com",
                     "password": "myStrongPassword" (optional)
                 }

Forgot password

      Endpoint: /auth/page/email/forgot-password
      Method: POST
      JSON Data: { "email": "myemail@domain.com" }

Login

      Endpoint: /auth/page/email/login
      Method: POST
      JSON Data: { 
                     "email": "myemail@domain.com",
                     "password": "myStrongPassword"
                 }

Set new password

      Endpoint: /auth/page/email/set-password
      Method: POST
      JSON Data: {
                      "new": "newPassword",
                      "confirm": "newPassword",
                      "current": "currentPassword"
                 }

Note that in the set password endpoint, the presence of the key "current" is dependent on how the needOldPassword is defined in the instance for YesodAuthEmail.

Synopsis

authEmail :: YesodAuthEmail m => AuthPlugin m
class (YesodAuth site, PathPiece (AuthEmailId site), RenderMessage site AuthMessage) => YesodAuthEmail site where
- type AuthEmailId site
- addUnverified :: Email -> VerKey -> AuthHandler site (AuthEmailId site)
- addUnverifiedWithPass :: Email -> VerKey -> SaltedPass -> AuthHandler site (AuthEmailId site)
- sendVerifyEmail :: Email -> VerKey -> VerUrl -> AuthHandler site ()
- sendForgotPasswordEmail :: Email -> VerKey -> VerUrl -> AuthHandler site ()
- getVerifyKey :: AuthEmailId site -> AuthHandler site (Maybe VerKey)
- setVerifyKey :: AuthEmailId site -> VerKey -> AuthHandler site ()
- hashAndSaltPassword :: Text -> AuthHandler site SaltedPass
- verifyPassword :: Text -> SaltedPass -> AuthHandler site Bool
- verifyAccount :: AuthEmailId site -> AuthHandler site (Maybe (AuthId site))
- getPassword :: AuthId site -> AuthHandler site (Maybe SaltedPass)
- setPassword :: AuthId site -> SaltedPass -> AuthHandler site ()
- getEmailCreds :: Identifier -> AuthHandler site (Maybe (EmailCreds site))
- getEmail :: AuthEmailId site -> AuthHandler site (Maybe Email)
- randomKey :: site -> IO VerKey
- afterPasswordRoute :: site -> Route site
- afterVerificationWithPass :: site -> Route site
- needOldPassword :: AuthId site -> AuthHandler site Bool
- checkPasswordSecurity :: AuthId site -> Text -> AuthHandler site (Either Text ())
- confirmationEmailSentResponse :: Text -> AuthHandler site TypedContent
- emailPreviouslyRegisteredResponse :: MonadAuthHandler site m => Text -> Maybe (m TypedContent)
- normalizeEmailAddress :: site -> Text -> Text
- emailLoginHandler :: (Route Auth -> Route site) -> WidgetFor site ()
- registerHandler :: AuthHandler site Html
- forgotPasswordHandler :: AuthHandler site Html
- setPasswordHandler :: Bool -> AuthHandler site TypedContent
- registerHelper :: Route Auth -> AuthHandler site TypedContent
- passwordResetHelper :: Route Auth -> AuthHandler site TypedContent
data EmailCreds site = EmailCreds {
- emailCredsId :: AuthEmailId site
- emailCredsAuthId :: Maybe (AuthId site)
- emailCredsStatus :: VerStatus
- emailCredsVerkey :: Maybe VerKey
- emailCredsEmail :: Email
}
saltPass :: Text -> IO Text
loginR :: AuthRoute
registerR :: AuthRoute
forgotPasswordR :: AuthRoute
setpassR :: AuthRoute
verifyR :: Text -> Text -> Bool -> AuthRoute
isValidPass :: Text -> SaltedPass -> Bool
type Email = Text
type VerKey = Text
type VerUrl = Text
type SaltedPass = Text
type VerStatus = Bool
type Identifier = Text
loginLinkKey :: Text
setLoginLinkKey :: (MonadHandler m, YesodAuthEmail (HandlerSite m)) => AuthId (HandlerSite m) -> m ()
defaultEmailLoginHandler :: YesodAuthEmail master => (Route Auth -> Route master) -> WidgetFor master ()
defaultRegisterHandler :: YesodAuthEmail master => AuthHandler master Html
defaultForgotPasswordHandler :: YesodAuthEmail master => AuthHandler master Html
defaultSetPasswordHandler :: YesodAuthEmail master => Bool -> AuthHandler master TypedContent
defaultRegisterHelper :: YesodAuthEmail master => Bool -> Bool -> Route Auth -> AuthHandler master TypedContent

Plugin

authEmail :: YesodAuthEmail m => AuthPlugin m Source #

class (YesodAuth site, PathPiece (AuthEmailId site), RenderMessage site AuthMessage) => YesodAuthEmail site where Source #

Minimal complete definition

addUnverified, sendVerifyEmail, getVerifyKey, setVerifyKey, verifyAccount, getPassword, setPassword, getEmailCreds, getEmail, afterPasswordRoute

Associated Types

type AuthEmailId site Source #

Methods

addUnverified :: Email -> VerKey -> AuthHandler site (AuthEmailId site) Source #

Add a new email address to the database, but indicate that the address has not yet been verified.

Since: 1.1.0

addUnverifiedWithPass :: Email -> VerKey -> SaltedPass -> AuthHandler site (AuthEmailId site) Source #

Similar to addUnverified, but comes with the registered password.

The default implementation is just addUnverified, which ignores the password.

You may override this to save the salted password to your database.

Since: 1.6.4

sendVerifyEmail :: Email -> VerKey -> VerUrl -> AuthHandler site () Source #

Send an email to the given address to verify ownership.

Since: 1.1.0

sendForgotPasswordEmail :: Email -> VerKey -> VerUrl -> AuthHandler site () Source #

Send an email to the given address to re-verify ownership in the case of a password reset. This can be used to send a different email when a user goes through the 'forgot password' flow as opposed to the 'account registration' flow.

Default: Will call sendVerifyEmail, resulting in the same email getting sent for both registrations and password resets.

Since: 1.6.10

getVerifyKey :: AuthEmailId site -> AuthHandler site (Maybe VerKey) Source #

Get the verification key for the given email ID.

Since: 1.1.0

setVerifyKey :: AuthEmailId site -> VerKey -> AuthHandler site () Source #

Set the verification key for the given email ID.

Since: 1.1.0

hashAndSaltPassword :: Text -> AuthHandler site SaltedPass Source #

Hash and salt a password

Default: saltPass.

Since: 1.4.20

verifyPassword :: Text -> SaltedPass -> AuthHandler site Bool Source #

Verify a password matches the stored password for the given account.

Default: Fetch a password with getPassword and match using verifyPassword.

Since: 1.4.20

verifyAccount :: AuthEmailId site -> AuthHandler site (Maybe (AuthId site)) Source #

Verify the email address on the given account.

Warning! If you have persisted the AuthEmailId site somewhere, this method should delete that key, or make it unusable in some fashion. Otherwise, the same key can be used multiple times!

See https://github.com/yesodweb/yesod/issues/1222.

Since: 1.1.0

getPassword :: AuthId site -> AuthHandler site (Maybe SaltedPass) Source #

Get the salted password for the given account.

Since: 1.1.0

setPassword :: AuthId site -> SaltedPass -> AuthHandler site () Source #

Set the salted password for the given account.

Since: 1.1.0

getEmailCreds :: Identifier -> AuthHandler site (Maybe (EmailCreds site)) Source #

Get the credentials for the given Identifier, which may be either an email address or some other identification (e.g., username).

Since: 1.2.0

getEmail :: AuthEmailId site -> AuthHandler site (Maybe Email) Source #

Get the email address for the given email ID.

Since: 1.1.0

randomKey :: site -> IO VerKey Source #

Generate a random alphanumeric string.

Since: 1.1.0

afterPasswordRoute :: site -> Route site Source #

Route to send user to after password has been set correctly.

Since: 1.2.0

afterVerificationWithPass :: site -> Route site Source #

Route to send user to after verification with a password

Since: 1.6.4

needOldPassword :: AuthId site -> AuthHandler site Bool Source #

Does the user need to provide the current password in order to set a new password?

Default: if the user logged in via an email link do not require a password.

Since: 1.2.1

checkPasswordSecurity :: AuthId site -> Text -> AuthHandler site (Either Text ()) Source #

Check that the given plain-text password meets minimum security standards.

Default: password is at least three characters.

confirmationEmailSentResponse :: Text -> AuthHandler site TypedContent Source #

Response after sending a confirmation email.

Since: 1.2.2

emailPreviouslyRegisteredResponse :: MonadAuthHandler site m => Text -> Maybe (m TypedContent) Source #

If a response is set, it will be used when an already-verified email tries to re-register. Otherwise, confirmationEmailSentResponse will be used.

Since: 1.6.4

normalizeEmailAddress :: site -> Text -> Text Source #

Additional normalization of email addresses, besides standard canonicalization.

Default: Lower case the email address.

Since: 1.2.3

emailLoginHandler :: (Route Auth -> Route site) -> WidgetFor site () Source #

Handler called to render the login page. The default works fine, but you may want to override it in order to have a different DOM.

Default: defaultEmailLoginHandler.

Since: 1.4.17

registerHandler :: AuthHandler site Html Source #

Handler called to render the registration page. The default works fine, but you may want to override it in order to have a different DOM.

Default: defaultRegisterHandler.

@since: 1.2.6

forgotPasswordHandler :: AuthHandler site Html Source #

Handler called to render the "forgot password" page. The default works fine, but you may want to override it in order to have a different DOM.

Default: defaultForgotPasswordHandler.

@since: 1.2.6

setPasswordHandler Source #

Arguments

:: Bool	Whether the old password is needed. If `True`, a field for the old password should be presented. Otherwise, just two fields for the new password are needed.
-> AuthHandler site TypedContent

Handler called to render the "set password" page. The default works fine, but you may want to override it in order to have a different DOM.

Default: defaultSetPasswordHandler.

@since: 1.2.6

registerHelper Source #

Arguments

:: Route Auth	Where to sent the user in the event that registration fails
-> AuthHandler site TypedContent

Helper that controls what happens after a user registration request is submitted. This method can be overridden to completely customize what happens during the user registration process, such as for handling additional fields in the registration form.

The default implementation is in terms of defaultRegisterHelper.

@since: 1.6.9

passwordResetHelper Source #

Arguments

:: Route Auth	Where to sent the user in the event that the password reset fails
-> AuthHandler site TypedContent

Helper that controls what happens after a forgot password request is submitted. As with registerHelper, this method can be overridden to customize the behavior when a user attempts to recover their password.

The default implementation is in terms of defaultRegisterHelper.

@since: 1.6.9

data EmailCreds site Source #

Data stored in a database for each e-mail address.

Constructors

EmailCreds
Fields emailCredsId :: AuthEmailId site emailCredsAuthId :: Maybe (AuthId site) emailCredsStatus :: VerStatus emailCredsVerkey :: Maybe VerKey emailCredsEmail :: Email

saltPass :: Text -> IO Text Source #

Salt a password with a randomly generated salt.

Routes

loginR :: AuthRoute Source #

registerR :: AuthRoute Source #

forgotPasswordR :: AuthRoute Source #

setpassR :: AuthRoute Source #

verifyR :: Text -> Text -> Bool -> AuthRoute Source #

Since: 1.4.5

isValidPass Source #

Arguments

:: Text	cleartext password
-> SaltedPass	salted password
-> Bool

Types

type Email = Text Source #

type VerKey = Text Source #

type VerUrl = Text Source #

type SaltedPass = Text Source #

type VerStatus = Bool Source #

type Identifier = Text Source #

An Identifier generalizes an email address to allow users to log in with some other form of credentials (e.g., username).

Note that any of these other identifiers must not be valid email addresses.

Since: 1.2.0

Misc

loginLinkKey :: Text Source #

Session variable set when user logged in via a login link. See needOldPassword.

Since: 1.2.1

setLoginLinkKey :: (MonadHandler m, YesodAuthEmail (HandlerSite m)) => AuthId (HandlerSite m) -> m () Source #

Set loginLinkKey to the current time.

setLoginLinkKey :: (MonadHandler m) => AuthId site -> m ()

Since: 1.2.1

Default handlers

defaultEmailLoginHandler :: YesodAuthEmail master => (Route Auth -> Route master) -> WidgetFor master () Source #

Default implementation of emailLoginHandler.

Since: 1.4.17

defaultRegisterHandler :: YesodAuthEmail master => AuthHandler master Html Source #

Default implementation of registerHandler.

Since: 1.2.6

defaultForgotPasswordHandler :: YesodAuthEmail master => AuthHandler master Html Source #

Default implementation of forgotPasswordHandler.

Since: 1.2.6

defaultSetPasswordHandler :: YesodAuthEmail master => Bool -> AuthHandler master TypedContent Source #

Default implementation of setPasswordHandler.

Since: 1.2.6

Default helpers

defaultRegisterHelper Source #

Arguments

:: YesodAuthEmail master
=> Bool	Allow lookup via username in addition to email
-> Bool	Set to `True` for forgot password flow, `False` for new account registration
-> Route Auth
-> AuthHandler master TypedContent