A yesod-auth AuthPlugin designed to look users up in a Persistent database where the hash of their password is stored.

This module was removed from yesod-auth-1.3.0.0 and is now maintained separately. Versions of this module prior to yesod-auth-1.3 used a relatively weak hashing algorithm (a single round of SHA1) which does not provide adequate protection against an attacker who discovers the hashed passwords. See: https://github.com/yesodweb/yesod/issues/668.

It has now been rewritten to use Crypto.PasswordStore, but this has been done in a way which preserves compatibility both with the API and with databases which have been set up using older versions of this module. There are two levels of database compatibility:

• The verification code recognises both the old and new hash formats, so passwords can be verified against database entries which still contain old-style hashes.
• The function upgradePasswordHash can be used to migrate existing user records to use the new format hash. Unlike freshly created password hashes, entries converted this way must still have the old salt field, since the old hash function remains part of the algorithm needed for verification. (The new hash is layered on top of the old one.)

On the other hand, new passwords set up by setPassword or setPasswordStrength no longer use a separate salt field, so new users of this module need only provide a single password field in the user data, and can ignore the salt.

In a system which has been migrated from the old format, passwords which are reset will use the new format and will have an empty salt field. Once all the entries are of this form, it is safe to change the model to remove the salt, and change the HashDBUser instance accordingly.

To use this in a Yesod application, the foundation data type must be an instance of YesodPersist, and the username and hashed passwords should be added to the database. The following steps give an outline of what is required.

You need a database table to store user records: in a scaffolded site it might look like:

User
    name Text             -- user name used to uniquely identify users
    password Text Maybe   -- password hash for HashDB
    UniqueUser name

Create an instance of HashDBUser for this data type. For historical reasons Yesod.Auth.HashDB exports some names which are quite likely to clash with your own, so it is a good idea to import just the ones you need:

import Yesod.Auth.HashDB (HashDBUser(..))
....
instance HashDBUser User where
    userPasswordHash = userPassword
    setPasswordHash h u = u { userPassword = Just h }

In the YesodAuth instance declaration for your app, include authHashDB like so:

import Yesod.Auth.HashDB (authHashDB)
....
instance YesodAuth App where
    ....
    authPlugins _ = [ authHashDB (Just . UniqueUser), .... ]
    getAuthId creds = ... -- Perhaps modify scaffolding: see below

The argument to authHashDB is a function which takes a Text and produces a Maybe containing a Unique value to look up in the User table. The example (Just . UniqueUser) shown here works for the model outlined above.

In the scaffolding, the definition of getAuthId contains code to add a user who is not already in the database. Depending on how users are administered, this may not make sense when using HashDB, so consider whether it should be removed.

For a real application, the developer should provide some sort of of administrative interface for setting passwords; it needs to call setPassword and save the result in the database. However, if you need to initialise the database by hand, you can generate the correct password hash as follows:

ghci -XOverloadedStrings
> import Crypto.PasswordStore
> makePassword "MyPassword" 17

where "17" is the default strength parameter (defaultStrength) used in this module.

Custom Login Form

Instead of using the built-in HTML form, a custom one can be supplied by using authHashDBWithForm instead of authHashDB.

The custom form needs to be given as a function returning a Widget, since it has to build in the supplied "action" URL, and it must provide two text fields called "username" and "password". For example, the following modification of the outline code given above would replace the default form with a very minimal one which has no labels and a simple layout.

instance YesodAuth App where
    ....
    authPlugins _ = [ authHashDBWithForm myform (Just . UniqueUser), .... ]

myform :: Route App -> Widget
myform action = $(whamletFile "templates/loginform.hamlet")

where templates/loginform.hamlet contains

<form method="post" action="@{action}">
    <input name="username">
    <input type="password" name="password">
    <input type="submit" value="Login">