Happstack.Auth

Happstack.Auth offers an easy way to implement user authentication for Happstack web applications. It uses Happstack.State as database back-end and SHA512 for password encryption. Session safety is ensured by a HTTP header fingerprint (client ip & user-agent) and a configurable session timeout.

To use this module, add the AuthState to your state dependencies, for example:

 import Happstack.Auth

 instance Component MyState where
     type Dependencies MyState = AuthState :+: End
     initialValue = ...

One of the first things in your response monad should be updateTimeout to make sure session timeouts are updated correctly.

High level functions

User registration

register

Arguments

:: (MonadIO m, FilterMonad Response m, ServerMonad m)

=> Minutes

Session timeout

-> Username

-> Password

-> m a

User exists response

-> m a

Success response

-> m a

Register a new user

changePassword

Arguments

:: MonadIO m

=> Username

-> Password

Old password

-> Password

New password

-> m Bool

setPassword :: MonadIO m => Username -> Password -> m Bool

Session management

updateTimeout :: (MonadIO m, FilterMonad Response m, MonadPlus m, ServerMonad m) => Minutes -> m ()

Update the session timeout of logged in users. Add this to the top of your application route, for example:

 appRoute :: ServerPart Response
 appRoute = updateTimeout 5 >> msum
     [ {- your routing here -}
     ]

performLogin

Arguments

:: (MonadIO m, FilterMonad Response m, ServerMonad m)

=> Minutes

Session timeout

-> User

-> m a

Run with modified headers, including the new session cookie

-> m a

performLogout :: (MonadIO m, FilterMonad Response m) => SessionKey -> m ()

loginHandler

Arguments

:: (MonadIO m, FilterMonad Response m, MonadPlus m, ServerMonad m)

=> Minutes

Session timeout

-> Maybe String

POST field to look for username (default: "username")

-> Maybe String

POST field to look for password (default: "password")

-> m a

Success response

-> (Maybe Username -> Maybe Password -> m a)

Fail response. Arguments: Post data

-> m a

Handles data from a login form to log the user in.

logoutHandler

Arguments

:: (ServerMonad m, MonadPlus m, MonadIO m, FilterMonad Response m)

=> m a

Response after logout

-> m a

withSession

Arguments

:: MonadIO m

=> (SessionData -> ServerPartT m a)

Logged in response

-> ServerPartT m a

Not logged in response

-> ServerPartT m a

Run a ServerPartT with the SessionData of the currently logged in user (if available)

loginGate

Arguments

:: MonadIO m

=> ServerPartT m a

Logged in

-> ServerPartT m a

Not registered

-> ServerPartT m a

Require a login

getSessionData :: (MonadIO m, MonadPlus m, ServerMonad m) => m (Maybe SessionData)

Get the SessionData of the currently logged in user

getSessionKey :: (MonadIO m, MonadPlus m, ServerMonad m) => m (Maybe SessionKey)

Get the identifier for the current session

clearSessionCookie :: FilterMonad Response m => m ()

Basic functions

Users

addUser :: MonadIO m => Username -> Password -> m (Maybe User)

getUser :: MonadIO m => Username -> m (Maybe User)

getUserById :: MonadIO m => UserId -> m (Maybe User)

delUser :: MonadIO m => Username -> m ()

updateUser :: MonadIO m => User -> m ()

Update (replace) a user

authUser :: MonadIO m => Username -> Password -> m (Maybe User)

isUser :: MonadIO m => Username -> m Bool

listUsers :: MonadIO m => m [Username]

numUsers :: MonadIO m => m Int

askUsers :: MonadIO m => m UserDB

Warning: This UserDB uses the internal types from Happstack.Auth.Data.Internal

Sessions

newSession :: MonadIO m => SessionData -> m SessionKey

getSession :: MonadIO m => SessionKey -> m (Maybe SessionData)

setSession :: MonadIO m => SessionKey -> SessionData -> m ()

delSession :: MonadIO m => SessionKey -> m ()

clearAllSessions :: MonadIO m => m ()

numSessions :: MonadIO m => m Int

getSessions :: MonadIO m => m (Sessions SessionData)

Warning: This Sessions uses the internal types from Happstack.Auth.Data.Internal

clearExpiredSessions :: MonadIO m => m ()

Data types

These data types collide with the data definitions used internaly in Happstack.Auth.Data.Internal. However, if you need both modules you might want to import the Data module qualified:

 import Happstack.Auth
 import qualified Happstack.Auth.Data.Internal as AuthD

data User

Instances

Convertible User User

Convertible User User

userName :: User -> Username

userId :: User -> UserId

type Username = String

type Password = String

data UserId

Abstract user identification

Instances

Eq UserId

Data UserId

Num UserId

Ord UserId

Read UserId

Show UserId

Typeable UserId

Version UserId

Serialize UserId

data SessionData

Constructors

SessionData

Fields

sessionUserId :: UserId

sessionUsername :: Username

sessionTimeout :: ClockTime

sessionFingerprint :: (Either String ByteString, Maybe ByteString)

either IP or "x-forwarded-for" header & user-agent

Instances

Convertible SessionData SessionData

Convertible SessionData SessionData

data SessionKey

Abstract session identification

Instances

Eq SessionKey

Data SessionKey

Num SessionKey

Ord SessionKey

Read SessionKey

Show SessionKey

Typeable SessionKey

Version SessionKey

Serialize SessionKey

Random SessionKey

(Serialize NewSession, Serialize SessionKey) => UpdateEvent NewSession SessionKey

type Minutes = Int

data AuthState

Add this to your Dependency-List of your application state

Instances

Data AuthState

Show AuthState

Typeable AuthState

Version AuthState

Serialize AuthState

Methods AuthState

Component AuthState

authProxy :: Proxy AuthState