Safe Haskell | None |
---|---|
Language | Haskell98 |
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" }
- 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
.
- authEmail :: YesodAuthEmail m => AuthPlugin m
- class (YesodAuth site, PathPiece (AuthEmailId site), RenderMessage site AuthMessage) => YesodAuthEmail site where
- type AuthEmailId site
- 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 -> 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) -> WidgetT master IO ()
- defaultRegisterHandler :: YesodAuthEmail master => HandlerT Auth (HandlerT master IO) Html
- defaultForgotPasswordHandler :: YesodAuthEmail master => HandlerT Auth (HandlerT master IO) Html
- defaultSetPasswordHandler :: YesodAuthEmail master => Bool -> HandlerT Auth (HandlerT master IO) TypedContent
Plugin
authEmail :: YesodAuthEmail m => AuthPlugin m Source #
class (YesodAuth site, PathPiece (AuthEmailId site), RenderMessage site AuthMessage) => YesodAuthEmail site where Source #
addUnverified, sendVerifyEmail, getVerifyKey, setVerifyKey, verifyAccount, getPassword, setPassword, getEmailCreds, getEmail, afterPasswordRoute
type AuthEmailId site Source #
addUnverified :: Email -> VerKey -> HandlerT site IO (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
sendVerifyEmail :: Email -> VerKey -> VerUrl -> HandlerT site IO () Source #
Send an email to the given address to verify ownership.
Since: 1.1.0
getVerifyKey :: AuthEmailId site -> HandlerT site IO (Maybe VerKey) Source #
Get the verification key for the given email ID.
Since: 1.1.0
setVerifyKey :: AuthEmailId site -> VerKey -> HandlerT site IO () Source #
Set the verification key for the given email ID.
Since: 1.1.0
verifyAccount :: AuthEmailId site -> HandlerT site IO (Maybe (AuthId site)) Source #
Verify the email address on the given account.
Warning! If you have persisted the
somewhere, this method should delete that key, or make it unusable
in some fashion. Otherwise, the same key can be used multiple times!AuthEmailId
site
See https://github.com/yesodweb/yesod/issues/1222.
Since: 1.1.0
getPassword :: AuthId site -> HandlerT site IO (Maybe SaltedPass) Source #
Get the salted password for the given account.
Since: 1.1.0
setPassword :: AuthId site -> SaltedPass -> HandlerT site IO () Source #
Set the salted password for the given account.
Since: 1.1.0
getEmailCreds :: Identifier -> HandlerT site IO (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 -> HandlerT site IO (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
needOldPassword :: AuthId site -> HandlerT site IO 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 -> HandlerT site IO (Either Text ()) Source #
Check that the given plain-text password meets minimum security standards.
Default: password is at least three characters.
confirmationEmailSentResponse :: Text -> HandlerT site IO TypedContent Source #
Response after sending a confirmation email.
Since: 1.2.2
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) -> WidgetT site IO () 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 :: HandlerT Auth (HandlerT site IO) 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 :: HandlerT Auth (HandlerT site IO) 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 :: Bool -> HandlerT Auth (HandlerT site IO) TypedContent Source #
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
data EmailCreds site Source #
Data stored in a database for each e-mail address.
EmailCreds | |
|
Routes
:: Text | cleartext password |
-> SaltedPass | salted password |
-> Bool |
Types
type SaltedPass = Text 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) -> WidgetT master IO () Source #
Default implementation of emailLoginHandler
.
Since: 1.4.17
defaultRegisterHandler :: YesodAuthEmail master => HandlerT Auth (HandlerT master IO) Html Source #
Default implementation of registerHandler
.
Since: 1.2.6
defaultForgotPasswordHandler :: YesodAuthEmail master => HandlerT Auth (HandlerT master IO) Html Source #
Default implementation of forgotPasswordHandler
.
Since: 1.2.6
defaultSetPasswordHandler :: YesodAuthEmail master => Bool -> HandlerT Auth (HandlerT master IO) TypedContent Source #
Default implementation of setPasswordHandler
.
Since: 1.2.6