Snap.Snaplet.Auth

snap-0.9.2.2: Top-level package for the Snap Web Framework

Safe Haskell | None

Snap.Snaplet.Auth

Contents

- Higher Level Handler Functions
- Lower Level Functions
- Types
- Other Utilities
- Handlers
- Splice helpers

Description

This module contains all the central authentication functionality.

It exports a number of high-level functions to be used directly in your application handlers.

We also export a number of mid-level functions that should be helpful when you are integrating with another way of confirming the authentication of login requests.

Synopsis

- createUser :: Text -> ByteString -> Handler b (AuthManager b) AuthUser
- usernameExists :: Text -> Handler b (AuthManager b) Bool
- saveUser :: AuthUser -> Handler b (AuthManager b) AuthUser
- destroyUser :: AuthUser -> Handler b (AuthManager b) ()
- loginByUsername :: ByteString -> Password -> Bool -> Handler b (AuthManager b) (Either AuthFailure AuthUser)
- loginByRememberToken :: Handler b (AuthManager b) (Maybe AuthUser)
- forceLogin :: AuthUser -> Handler b (AuthManager b) (Either AuthFailure AuthUser)
- logout :: Handler b (AuthManager b) ()
- currentUser :: Handler b (AuthManager b) (Maybe AuthUser)
- isLoggedIn :: Handler b (AuthManager b) Bool
- markAuthSuccess :: AuthUser -> Handler b (AuthManager b) AuthUser
- markAuthFail :: AuthUser -> Handler b (AuthManager b) AuthUser
- checkPasswordAndLogin :: AuthUser -> Password -> Handler b (AuthManager b) (Either AuthFailure AuthUser)
- data AuthManager b = forall r . IAuthBackend r => AuthManager {
  - backend :: r
  - session :: Lens b (Snaplet SessionManager)
  - activeUser :: Maybe AuthUser
  - minPasswdLen :: Int
  - rememberCookieName :: ByteString
  - rememberPeriod :: Maybe Int
  - siteKey :: Key
  - lockout :: Maybe (Int, NominalDiffTime)
  - randomNumberGenerator :: RNG
  }
- class IAuthBackend r where
  - save :: r -> AuthUser -> IO AuthUser
  - lookupByUserId :: r -> UserId -> IO (Maybe AuthUser)
  - lookupByLogin :: r -> Text -> IO (Maybe AuthUser)
  - lookupByRememberToken :: r -> Text -> IO (Maybe AuthUser)
  - destroy :: r -> AuthUser -> IO ()
- data AuthSettings = AuthSettings {
  - asMinPasswdLen :: Int
  - asRememberCookieName :: ByteString
  - asRememberPeriod :: Maybe Int
  - asLockout :: Maybe (Int, NominalDiffTime)
  - asSiteKey :: FilePath
  }
- defAuthSettings :: AuthSettings
- data AuthUser = AuthUser {
  - userId :: Maybe UserId
  - userLogin :: Text
  - userPassword :: Maybe Password
  - userActivatedAt :: Maybe UTCTime
  - userSuspendedAt :: Maybe UTCTime
  - userRememberToken :: Maybe Text
  - userLoginCount :: Int
  - userFailedLoginCount :: Int
  - userLockedOutUntil :: Maybe UTCTime
  - userCurrentLoginAt :: Maybe UTCTime
  - userLastLoginAt :: Maybe UTCTime
  - userCurrentLoginIp :: Maybe ByteString
  - userLastLoginIp :: Maybe ByteString
  - userCreatedAt :: Maybe UTCTime
  - userUpdatedAt :: Maybe UTCTime
  - userRoles :: [Role]
  - userMeta :: HashMap Text Value
  }
- defAuthUser :: AuthUser
- newtype UserId = UserId {
  - unUid :: Text
  }
- data Password
  - = ClearText ByteString
  - | Encrypted ByteString
- data AuthFailure
  - = UserNotFound
  - | IncorrectPassword
  - | PasswordMissing
  - | LockedOut UTCTime
  - | AuthError String
- data BackendError
  - = DuplicateLogin
  - | BackendError String
- data Role = Role ByteString
- authSettingsFromConfig :: Initializer b v AuthSettings
- withBackend :: (forall r. IAuthBackend r => r -> Handler b (AuthManager v) a) -> Handler b (AuthManager v) a
- encryptPassword :: Password -> IO Password
- checkPassword :: Password -> Password -> Bool
- authenticatePassword :: AuthUser -> Password -> Maybe AuthFailure
- setPassword :: AuthUser -> ByteString -> IO AuthUser
- encrypt :: ByteString -> IO ByteString
- verify :: ByteString -> ByteString -> Bool
- registerUser :: ByteString -> ByteString -> Handler b (AuthManager b) AuthUser
- loginUser :: ByteString -> ByteString -> Maybe ByteString -> (AuthFailure -> Handler b (AuthManager b) ()) -> Handler b (AuthManager b) () -> Handler b (AuthManager b) ()
- logoutUser :: Handler b (AuthManager b) () -> Handler b (AuthManager b) ()
- requireUser :: Lens b (Snaplet (AuthManager b)) -> Handler b v a -> Handler b v a -> Handler b v a
- addAuthSplices :: HasHeist b => Lens b (Snaplet (AuthManager b)) -> Initializer b v ()
- ifLoggedIn :: Lens b (Snaplet (AuthManager b)) -> SnapletSplice b v
- ifLoggedOut :: Lens b (Snaplet (AuthManager b)) -> SnapletSplice b v
- loggedInUser :: Lens b (Snaplet (AuthManager b)) -> SnapletSplice b v

# Higher Level Handler Functions

createUser

Arguments

:: Text | Username
-> ByteString | Password
-> Handler b (AuthManager b) AuthUser |

Create a new user from just a username and password

May throw a DuplicateLogin if given username is not unique.

usernameExists

Arguments

:: Text | The username to be checked
-> Handler b (AuthManager b) Bool |

Check whether a user with the given username exists.

saveUser :: AuthUser -> Handler b (AuthManager b) AuthUser

Create or update a given user

May throw a `BackendError` if something goes wrong.

destroyUser :: AuthUser -> Handler b (AuthManager b) ()

Destroy the given user

May throw a `BackendError` if something goes wrong.

loginByUsername

Arguments

:: ByteString | Username/login for user
-> Password | Should be ClearText
-> Bool | Set remember token?
-> Handler b (AuthManager b) (Either AuthFailure AuthUser) |

Lookup a user by her username, check given password and perform login

loginByRememberToken :: Handler b (AuthManager b) (Maybe AuthUser)

Remember user from the remember token if possible and perform login

forceLogin

Arguments

:: AuthUser | An existing user, somehow looked up from db
-> Handler b (AuthManager b) (Either AuthFailure AuthUser) |

Login and persist the given `AuthUser` in the active session

Meant to be used if you have other means of being sure that the person is who she says she is.

logout :: Handler b (AuthManager b) ()

Logout the active user

currentUser :: Handler b (AuthManager b) (Maybe AuthUser)

Return the current user; trying to remember from cookie if possible.

isLoggedIn :: Handler b (AuthManager b) Bool

Convenience wrapper around `rememberUser` that returns a bool result

# Lower Level Functions

markAuthSuccess :: AuthUser -> Handler b (AuthManager b) AuthUser

Mutate an `AuthUser`, marking successful authentication

This will save the user to the backend.

markAuthFail :: AuthUser -> Handler b (AuthManager b) AuthUser

Mutate an `AuthUser`, marking failed authentication

This will save the user to the backend.

checkPasswordAndLogin

Arguments

:: AuthUser | An existing user, somehow looked up from db
-> Password | A ClearText password
-> Handler b (AuthManager b) (Either AuthFailure AuthUser) |

Authenticate and log the user into the current session if successful.

This is a mid-level function exposed to allow roll-your-own ways of looking up a user from the database.

This function will:

1. Check the password
2. Login the user into the current session
3. Mark success/failure of the authentication trial on the user record

# Types

data AuthManager b

Abstract data type holding all necessary information for auth operation

Constructors

forall r . IAuthBackend r => AuthManager |
Fields backend :: r Storage back-end session :: Lens b (Snaplet SessionManager) A lens pointer to a SessionManager activeUser :: Maybe AuthUser A per-request logged-in user cache minPasswdLen :: Int Password length range rememberCookieName :: ByteString Cookie name for the remember token rememberPeriod :: Maybe Int Remember period in seconds. Defaults to 2 weeks. siteKey :: Key A unique encryption key used to encrypt remember cookie lockout :: Maybe (Int, NominalDiffTime) Lockout after x tries, re-allow entry after y seconds randomNumberGenerator :: RNG Random number generator

Instances

IAuthBackend (AuthManager b) |

class IAuthBackend r where

All storage backends need to implement this typeclass

Backend operations may throw `BackendError`s

Methods

save :: r -> AuthUser -> IO AuthUser

Create or update the given `AuthUser` record. If the `userId` in the `AuthUser` already exists in the database, then that user's information should be updated. If it does not exist, then a new user should be created.

lookupByUserId :: r -> UserId -> IO (Maybe AuthUser)

lookupByLogin :: r -> Text -> IO (Maybe AuthUser)

lookupByRememberToken :: r -> Text -> IO (Maybe AuthUser)

destroy :: r -> AuthUser -> IO ()

Instances

IAuthBackend JsonFileAuthManager |
IAuthBackend (AuthManager b) |

data AuthSettings

Authetication settings defined at initialization time

Constructors

AuthSettings |
Fields asMinPasswdLen :: Int Currently not used/checked asRememberCookieName :: ByteString Name of the desired remember cookie asRememberPeriod :: Maybe Int How long to remember when the option is used in rest of the API. `Nothing` means remember until end of session. asLockout :: Maybe (Int, NominalDiffTime) Lockout strategy: ([MaxAttempts], [LockoutDuration]) asSiteKey :: FilePath Location of app's encryption key

defAuthSettings :: AuthSettings

Default settings for Auth.

     asMinPasswdLen = 8
     asRememberCookieName = "_remember"
     asRememberPeriod = Just (2*7*24*60*60) = 2 weeks
     asLockout = Nothing
     asSiteKey = "site_key.txt"

data AuthUser

Type representing the concept of a User in your application.

Constructors

AuthUser |
Fields userId :: Maybe UserId userLogin :: Text userPassword :: Maybe Password userActivatedAt :: Maybe UTCTime userSuspendedAt :: Maybe UTCTime userRememberToken :: Maybe Text userLoginCount :: Int userFailedLoginCount :: Int userLockedOutUntil :: Maybe UTCTime userCurrentLoginAt :: Maybe UTCTime userLastLoginAt :: Maybe UTCTime userCurrentLoginIp :: Maybe ByteString userLastLoginIp :: Maybe ByteString userCreatedAt :: Maybe UTCTime userUpdatedAt :: Maybe UTCTime userRoles :: [Role] userMeta :: HashMap Text Value

Instances

Eq AuthUser |
Show AuthUser |
ToJSON AuthUser |
ToJSON UserIdCache |
FromJSON AuthUser |
FromJSON UserIdCache |

defAuthUser :: AuthUser

Default AuthUser that has all empty values.

newtype UserId

Internal representation of a `User`. By convention, we demand that the application is able to directly fetch a `User` using this identifier.

Think of this type as a secure, authenticated user. You should normally never see this type unless a user has been authenticated.

Constructors

UserId |
Fields unUid :: Text

Instances

Eq UserId |
Ord UserId |
Read UserId |
Show UserId |
ToJSON UserId |
ToJSON UserIdCache |
FromJSON UserId |
FromJSON UserIdCache |
Hashable UserId |

data Password

Password is clear when supplied by the user and encrypted later when returned from the db.

Constructors

ClearText ByteString |
Encrypted ByteString |

Instances

Eq Password |
Ord Password |
Read Password |
Show Password |
ToJSON Password |
FromJSON Password |

data AuthFailure

Authentication failures indicate what went wrong during authentication. They may provide useful information to the developer, although it is generally not advisable to show the user the exact details about why login failed.

Constructors

UserNotFound |
IncorrectPassword |
PasswordMissing |
LockedOut UTCTime | Locked out until given time
AuthError String |

Instances

Eq AuthFailure |
Ord AuthFailure |
Read AuthFailure |
Show AuthFailure |
Typeable AuthFailure |
Exception AuthFailure |
Error AuthFailure |

data BackendError

Constructors

DuplicateLogin |
BackendError String |

Instances

Eq BackendError |
Read BackendError |
Show BackendError |
Typeable BackendError |
Exception BackendError |

data Role

This will be replaced by a role-based permission system.

Constructors

Role ByteString |

Instances

Eq Role |
Ord Role |
Read Role |
Show Role |
ToJSON Role |
FromJSON Role |

# Other Utilities

authSettingsFromConfig :: Initializer b v AuthSettings

Function to get auth settings from a config file. This function can be used by the authors of auth snaplet backends in the initializer to let the user configure the auth snaplet from a config file. All options are optional and default to what's in defAuthSettings if not supplied. Here's what the default options would look like in the config file:

     minPasswordLen = 8
     rememberCookie = "_remember"
     rememberPeriod = 1209600 # 2 weeks
     lockout = [5, 86400] # 5 attempts locks you out for 86400 seconds
     siteKey = "site_key.txt"

withBackend

Arguments

:: (forall r. IAuthBackend r => r -> Handler b (AuthManager v) a) | The function to run with the handler.
-> Handler b (AuthManager v) a |

Run a function on the backend, and return the result.

This uses an existential type so that the backend type doesn't `escape` AuthManager. The reason that the type is Handler b (AuthManager v) a and not a is because anything that uses the backend will return an IO something, which you can liftIO, or a Handler b (AuthManager v) a if it uses other handler things.

encryptPassword :: Password -> IO Password

Turn a `ClearText` password into an `Encrypted` password, ready to be stuffed into a database.

checkPassword :: Password -> Password -> Bool

authenticatePassword

Arguments

:: AuthUser | Looked up from the back-end
-> Password | Check against this password
-> Maybe AuthFailure |

Check password for a given user.

Returns Nothing if check is successful and an IncorrectPassword error otherwise

setPassword :: AuthUser -> ByteString -> IO AuthUser

Set a new password for the given user. Given password should be clear-text; it will be encrypted into a `Encrypted`.

encrypt :: ByteString -> IO ByteString

The underlying encryption function, in case you need it for external processing.

verify

Arguments

:: ByteString | Cleartext
-> ByteString | Encrypted reference
-> Bool |

The underlying verify function, in case you need it for external processing.

# Handlers

registerUser

Arguments

:: ByteString | Login field
-> ByteString | Password field
-> Handler b (AuthManager b) AuthUser |

Register a new user by specifying login and password `Param` fields

loginUser

Arguments

:: ByteString | Username field
-> ByteString | Password field
-> Maybe ByteString | Remember field; Nothing if you want no remember function.
-> (AuthFailure -> Handler b (AuthManager b) ()) | Upon failure
-> Handler b (AuthManager b) () | Upon success
-> Handler b (AuthManager b) () |

A `MonadSnap` handler that processes a login form.

The request paremeters are passed to `performLogin`

logoutUser

Arguments

:: Handler b (AuthManager b) () | What to do after logging out
-> Handler b (AuthManager b) () |

Simple handler to log the user out. Deletes user from session.

requireUser

Arguments

:: Lens b (Snaplet (AuthManager b)) | Lens reference to an AuthManager
-> Handler b v a | Do this if no authenticated user is present.
-> Handler b v a | Do this if an authenticated user is present.
-> Handler b v a |

Require that an authenticated `AuthUser` is present in the current session.

This function has no DB cost - only checks to see if a user_id is present in the current session.

# Splice helpers

addAuthSplices

Arguments

:: HasHeist b |
=> Lens b (Snaplet (AuthManager b)) | A lens reference to `AuthManager`
-> Initializer b v () |

Add all standard auth splices to a Heist-enabled application.

This adds the following splices: <ifLoggedIn> <ifLoggedOut> <loggedInUser>

ifLoggedIn :: Lens b (Snaplet (AuthManager b)) -> SnapletSplice b v

A splice that can be used to check for existence of a user. If a user is present, this will run the contents of the node.

     <ifLoggedIn> Show this when there is a logged in user </ifLoggedIn>

ifLoggedOut :: Lens b (Snaplet (AuthManager b)) -> SnapletSplice b v

A splice that can be used to check for absence of a user. If a user is not present, this will run the contents of the node.

     <ifLoggedOut> Show this when there is a logged in user </ifLoggedOut>

loggedInUser :: Lens b (Snaplet (AuthManager b)) -> SnapletSplice b v

A splice that will simply print the current user's login, if there is one.