| Safe Haskell | None |
|---|---|
| Language | Haskell2010 |
Yesod.Auth.NoPassword
Description
This auth plugin for Yesod enabled simple passwordless authentication.
The only detail required from a user is an email address, and accounts are either updated or created, depending on whether the account exists or not. To actually log in, users are sent an email containing a link that authenticates them and logs them in.
This plugin provides:
- Token generation
- Orchestration of the login process and email sending
- Receiving of the login form data via HTTP POST.
- Authentication of users once they return to the site from an email
This plugin does not provide:
- A login form
- Email rendering or sending
- An account model
- A viewable interface (i.e. via HTTP GET) for the login form
These are left for the user of the plugin to implement so that they can retain control over form functionality, account models, email design and email service provider.
Implementation checklist:
- Implement an instance of
NoPasswordAuthfor your Yesod application. - Implement a Yesod form that resolves to an
EmailForm. Add
authNoPasswordto your authentication plugins in your instance ofYesodAuth, passing the form you wish to use for authentication. This typeclass provides a number of methods for customisation of behaviour, but the minimal implementation is:
- authNoPassword :: NoPasswordAuth m => Form m EmailForm -> AuthPlugin m
- newtype EmailForm = EmailForm {}
- class YesodAuthPersist master => NoPasswordAuth master where
- type Email = Text
- type Token = Text
- type TokenId = Text
- type Hash = Text
- loginPostR :: AuthRoute
Plugin
authNoPassword :: NoPasswordAuth m => Form m EmailForm -> AuthPlugin m Source #
Function to create the Yesod Auth plugin. Must be used by a type with an
instance for NoPasswordAuth, and must be given a form to use.
Form Type
Data type required for the Yesod form.
Typeclass
class YesodAuthPersist master => NoPasswordAuth master where Source #
Minimal complete definition
loginRoute, emailSentRoute, sendLoginEmail, getUserByEmail, getEmailAndHashByTokenId, updateLoginHashForUser, newUserWithLoginHash
Methods
loginRoute :: master -> Route master Source #
Route to a page that dispays a login form. This is not provided by the plugin.
emailSentRoute :: master -> Route master Source #
Route to which the user should be sent after entering an email address. This is not provided by the plugin.
Note: the user will not be authenticated when they reach the page.
sendLoginEmail :: Email -> Text -> HandlerT master IO () Source #
Send a login email.
getUserByEmail :: Email -> HandlerT master IO (Maybe (AuthId master)) Source #
Get a user by their email address. Used to determine if the user exists or not.
getEmailAndHashByTokenId :: TokenId -> HandlerT master IO (Maybe (Email, Hash)) Source #
Get a Hash by a TokenId.
Invoked when the user returns to the site from an email. We don't know
who the user is at this point as they may open the link from the email
on another device or in another browser, so session data can't be used.
Equally we do not want to pass the user's ID or email address in a URL
if we don't have to, so instead we look up users by the TokenId that
we issued them earlier in the process.
updateLoginHashForUser :: AuthId master -> Maybe Hash -> TokenId -> HandlerT master IO () Source #
Update a user's login hash
This is also used to blank out the hash once the user has logged in, or
can be used to prevent the user from logging in, so must accept a value
of Nothing.
It is recommended that the TokenId storage be enforced as unique.
For this reason, the token is not passed as a maybe, as some storage
backends treat NULL values as the same.
newUserWithLoginHash :: Email -> Hash -> TokenId -> HandlerT master IO () Source #
Create a new user with an email address and hash.
tokenStrength :: HandlerT master IO Int Source #
Optional – return a custom token strength.
A token strength of x equates to 2^x hash rounds.
tokenParamName :: HandlerT master IO Text Source #
Optional – return a custom token param name.
Types
Utility
loginPostR :: AuthRoute Source #
Route to which the site should POST the email form form.