Authentication and Authorization

Authentication and authorization are two very related, and yet separate, concepts. While the former deals with identifying a user, the latter determines what a user is allowed to do. Unfortunately, since both terms are often abbreviated as “auth,” the concepts are often conflated.

Yesod provides built-in support for a number of third-party authentication systems, such as OpenID, BrowserID and OAuth. These are systems where your application trusts some external system for validating a user’s credentials. Additionally, there is support for more commonly used username/password and email/password systems. The former route ensures simplicity for users (no new passwords to remember) and implementors (no need to deal with an entire security architecture), while the latter gives the developer more control.

On the authorization side, we are able to take advantage of REST and type-safe URLs to create simple, declarative systems. Additionally, since all authorization code is written in Haskell, you have the full flexibility of the language at your disposal.

This chapter will cover how to set up an “auth” solution in Yesod and discuss some trade-offs in the different authentication options.

Overview

The yesod-auth package provides a unified interface for a number of different authentication plugins. The only real requirement for these backends is that they identify a user based on some unique string. In OpenID, for instance, this would be the actual OpenID value. In BrowserID, it’s the email address. For HashDB (which uses a database of hashed passwords), it’s the username.

Each authentication plugin provides its own system for logging in, whether it be via passing tokens with an external site or an email/password form. After a successful login, the plugin sets a value in the user’s session to indicate his/her AuthId. This AuthId is usually a Persistent ID from a table used for keeping track of users.

There are a few functions available for querying a user’s AuthId, most commonly maybeAuthId, requireAuthId, maybeAuth and requireAuth. The “require” versions will redirect to a login page if the user is not logged in, while the second set of functions (the ones not ending in Id) give both the table ID and entity value.

Since all of the storage of AuthId is built on top of sessions, all of the rules from there apply. In particular, the data is stored in an encrypted, HMACed client cookie, which automatically times out after a certain configurable period of inactivity. Additionally, since there is no server-side component to sessions, logging out simply deletes the data from the session cookie; if a user reuses an older cookie value, the session will still be valid.

You can replace the default client-side sessions with server side sessions, to provide a forced logout capability, if this is desired. Also, if you wish to secure your sessions from man in the middle (MITM) attacks, you should serve your site over SSL and harden your sessions via sslOnlySessions and sslOnlyMiddleware, as described in the sessions chapter.

On the flip side, authorization is handled by a few methods inside the Yesod typeclass. For every request, these methods are run to determine if access should be allowed, denied, or if the user needs to be authenticated. By default, these methods allow access for every request. Alternatively, you can implement authorization in a more ad-hoc way by adding calls to requireAuth and the like within individual handler functions, though this undermines many of the benefits of a declarative authorization system.

Authenticate Me

Let’s jump right in with an example of authentication. For the Google OAuth authentication to work you should follow these steps:

  1. Read on Google Developers Help how to obtain OAuth 2.0 credentials such as a client ID and client secret that are known to both Google and your application.

  2. Set Authorized redirect URIs to http://localhost:3000/auth/page/googleemail2/complete.

  3. Enable Google+ API and Contacts API.

  4. Once you have the clientId and secretId, replace them in the code below.

  1. {-# LANGUAGE MultiParamTypeClasses #-}
  2. {-# LANGUAGE OverloadedStrings     #-}
  3. {-# LANGUAGE QuasiQuotes           #-}
  4. {-# LANGUAGE TemplateHaskell       #-}
  5. {-# LANGUAGE TypeFamilies          #-}
  6. import           Data.Default                (def)
  7. import           Data.Text                   (Text)
  8. import           Network.HTTP.Client.Conduit (Manager, newManager)
  9. import           Yesod
  10. import           Yesod.Auth
  11. import           Yesod.Auth.GoogleEmail2
  14. -- Replace with Google client ID.
  15. clientId :: Text
  16. clientId = ""
  18. -- Replace with Google secret ID.
  19. clientSecret :: Text
  20. clientSecret = ""
  22. data App = App
  23.     { httpManager :: Manager
  24.     }
  26. mkYesod "App" [parseRoutes|
  27. / HomeR GET
  28. /auth AuthR Auth getAuth
  29. |]
  31. instance Yesod App where
  32.     -- Note: In order to log in with BrowserID, you must correctly
  33.     -- set your hostname here.
  34.     approot = ApprootStatic "http://localhost:3000"
  36. instance YesodAuth App where
  37.     type AuthId App = Text
  38.     authenticate = return . Authenticated . credsIdent
  40.     loginDest _ = HomeR
  41.     logoutDest _ = HomeR
  43.     authPlugins _ = [ authGoogleEmail clientId clientSecret ]
  45.     -- The default maybeAuthId assumes a Persistent database. We're going for a
  46.     -- simpler AuthId, so we'll just do a direct lookup in the session.
  47.     maybeAuthId = lookupSession "_ID"
  49. instance RenderMessage App FormMessage where
  50.     renderMessage _ _ = defaultFormMessage
  52. getHomeR :: Handler Html
  53. getHomeR = do
  54.     maid <- maybeAuthId
  55.     defaultLayout
  56.         [whamlet|
  57.             <p>Your current auth ID: #{show maid}
  58.             $maybe _ <- maid
  59.                 <p>
  60.                     <a href=@{AuthR LogoutR}>Logout
  61.             $nothing
  62.                 <p>
  63.                     <a href=@{AuthR LoginR}>Go to the login page
  64.         |]
  66. main :: IO ()
  67. main = do
  68.     man <- newManager
  69.     warp 3000 $ App man

We’ll start with the route declarations. First, we declare our standard HomeR route, and then we set up the authentication subsite. Remember that a subsite needs four parameters: the path to the subsite, the route name, the subsite name, and a function to get the subsite value. In other words, based on the line:

  1. /auth AuthR Auth getAuth

We need to have getAuth :: MyAuthSite → Auth. While we haven’t written that function ourselves, yesod-auth provides it automatically. With other subsites (like static files), we provide configuration settings in the subsite value, and therefore need to specify the get function. In the auth subsite, we specify these settings in a separate typeclass, YesodAuth.

Why not use the subsite value? There are a number of settings we would like to give for an auth subsite, and doing so from a record type would be inconvenient. Also, since we want to have an AuthId associated type, a typeclass is more natural. And why not use a typeclass for all subsites? It comes with a downside: you can then only have a single instance per site, disallowing serving different sets of static files from different routes. Also, the subsite value works better when we want to load data at app initialization.

So what exactly goes in this YesodAuth instance? There are five required declarations:

  • AuthId is an associated type. This is the value yesod-auth will give you when you ask if a user is logged in (via maybeAuthId or requireAuthId). In our case, we’re simply using Text, to store the raw identifier- email address in our case, as we’ll soon see.

  • authenticate gets the actual AuthId from the Creds (credentials) data type. This type has three pieces of information: the authentication backend used (googleemail in our case), the actual identifier, and an associated list of arbitrary extra information. Each backend provides different extra information; see their docs for more information.

  • loginDest gives the route to redirect to after a successful login.

  • Likewise, logoutDest gives the route to redirect to after a logout.

  • authPlugins is a list of individual authentication backends to use. In our example, we’re using Google OAuth, which authenticates a user using their Google account.

In addition to these five methods, there are other methods available to control other behavior of the authentication system, such as what the login page looks like. For more information, please see the API documentation.

In our HomeR handler, we have some simple links to the login and logout pages, depending on whether or not the user is logged in. Notice how we construct these subsite links: first we give the subsite route name (AuthR), followed by the route within the subsite (LoginR and LogoutR).

Email

For many use cases, third-party authentication of email will be sufficient. Occasionally, you’ll want users to create passwords on your site. The scaffolded site does not include this setup, because:

  • In order to securely accept passwords, you need to be running over SSL. Many users are not serving their sites over SSL.

  • While the email backend properly salts and hashes passwords, a compromised database could still be problematic. Again, we make no assumptions that Yesod users are following secure deployment practices.

  • You need to have a working system for sending email. Many web servers these days are not equipped to deal with all of the spam protection measures used by mail servers.

The example below will use the system’s built-in sendmail executable. If you would like to avoid the hassle of dealing with an email server yourself, you can use Amazon SES. There is a package called mime-mail-ses which provides a drop-in replacement for the sendmail code used below. This is the approach I generally recommend, and what I use on most of my sites, including FP Haskell Center and Haskellers.com.

But assuming you are able to meet these demands, and you want to have a separate password login specifically for your site, Yesod offers a built-in backend. It requires quite a bit of code to set up, since it needs to store passwords securely in the database and send a number of different emails to users (verify account, password retrieval, etc.).

Let’s have a look at a site that provides email authentication, storing passwords in a Persistent SQLite database.

Even if you don’t have an email server, for debugging purposes the verification link is printed in the console.

  1. {-# LANGUAGE DeriveDataTypeable         #-}
  2. {-# LANGUAGE FlexibleContexts           #-}
  3. {-# LANGUAGE GADTs                      #-}
  4. {-# LANGUAGE GeneralizedNewtypeDeriving #-}
  5. {-# LANGUAGE MultiParamTypeClasses      #-}
  6. {-# LANGUAGE OverloadedStrings          #-}
  7. {-# LANGUAGE QuasiQuotes                #-}
  8. {-# LANGUAGE TemplateHaskell            #-}
  9. {-# LANGUAGE TypeFamilies               #-}
  10. import           Control.Monad            (join)
  11. import           Control.Monad.Logger     (runNoLoggingT)
  12. import           Data.Maybe               (isJust)
  13. import           Data.Text                (Text, unpack)
  14. import qualified Data.Text.Lazy.Encoding
  15. import           Data.Typeable            (Typeable)
  16. import           Database.Persist.Sqlite
  17. import           Database.Persist.TH
  18. import           Network.Mail.Mime
  19. import           Text.Blaze.Html.Renderer.Utf8 (renderHtml)
  20. import           Text.Hamlet                   (shamlet)
  21. import           Text.Shakespeare.Text         (stext)
  22. import           Yesod
  23. import           Yesod.Auth
  24. import           Yesod.Auth.Email
  26. share [mkPersist sqlSettings { mpsGeneric = False }, mkMigrate "migrateAll"] [persistLowerCase|
  27. User
  28.     email Text
  29.     password Text Maybe -- Password may not be set yet
  30.     verkey Text Maybe -- Used for resetting passwords
  31.     verified Bool
  32.     UniqueUser email
  33.     deriving Typeable
  34. |]
  36. data App = App SqlBackend
  38. mkYesod "App" [parseRoutes|
  39. / HomeR GET
  40. /auth AuthR Auth getAuth
  41. |]
  43. instance Yesod App where
  44.     -- Emails will include links, so be sure to include an approot so that
  45.     -- the links are valid!
  46.     approot = ApprootStatic "http://localhost:3000"
  47.     yesodMiddleware = defaultCsrfMiddleware . defaultYesodMiddleware
  49. instance RenderMessage App FormMessage where
  50.     renderMessage _ _ = defaultFormMessage
  52. -- Set up Persistent
  53. instance YesodPersist App where
  54.     type YesodPersistBackend App = SqlBackend
  55.     runDB f = do
  56.         App conn <- getYesod
  57.         runSqlConn f conn
  59. instance YesodAuth App where
  60.     type AuthId App = UserId
  62.     loginDest _ = HomeR
  63.     logoutDest _ = HomeR
  64.     authPlugins _ = [authEmail]
  66.     -- Need to find the UserId for the given email address.
  67.     authenticate creds = liftHandler $ runDB $ do
  68.         x <- insertBy $ User (credsIdent creds) Nothing Nothing False
  69.         return $ Authenticated $
  70.             case x of
  71.                 Left (Entity userid _) -> userid -- existing user
  72.                 Right userid -> userid -- newly added user
  74. instance YesodAuthPersist App
  76. -- Here's all of the email-specific code
  77. instance YesodAuthEmail App where
  78.     type AuthEmailId App = UserId
  80.     afterPasswordRoute _ = HomeR
  82.     addUnverified email verkey =
  83.         liftHandler $ runDB $ insert $ User email Nothing (Just verkey) False
  85.     sendVerifyEmail email _ verurl = do
  86.         -- Print out to the console the verification email, for easier
  87.         -- debugging.
  88.         liftIO $ putStrLn $ "Copy/ Paste this URL in your browser:" ++ unpack verurl
  90.         -- Send email.
  91.         liftIO $ renderSendMail (emptyMail $ Address Nothing "noreply")
  92.             { mailTo = [Address Nothing email]
  93.             , mailHeaders =
  94.                 [ ("Subject", "Verify your email address")
  95.                 ]
  96.             , mailParts = [[textPart, htmlPart]]
  97.             }
  98.       where
  99.         textPart = Part
  100.             { partType = "text/plain; charset=utf-8"
  101.             , partEncoding = None
  102.             , partDisposition = DefaultDisposition
  103.             , partContent = PartContent $ Data.Text.Lazy.Encoding.encodeUtf8
  104.                 [stext|
  105.                     Please confirm your email address by clicking on the link below.
  107.                     #{verurl}
  109.                     Thank you
  110.                 |]
  111.             , partHeaders = []
  112.             }
  113.         htmlPart = Part
  114.             { partType = "text/html; charset=utf-8"
  115.             , partEncoding = None
  116.             , partDisposition = DefaultDisposition
  117.             , partContent = PartContent $ renderHtml
  118.                 [shamlet|
  119.                     <p>Please confirm your email address by clicking on the link below.
  120.                     <p>
  121.                         <a href=#{verurl}>#{verurl}
  122.                     <p>Thank you
  123.                 |]
  124.             , partHeaders = []
  125.             }
  126.     getVerifyKey = liftHandler . runDB . fmap (join . fmap userVerkey) . get
  127.     setVerifyKey uid key = liftHandler $ runDB $ update uid [UserVerkey =. Just key]
  128.     verifyAccount uid = liftHandler $ runDB $ do
  129.         mu <- get uid
  130.         case mu of
  131.             Nothing -> return Nothing
  132.             Just u -> do
  133.                 update uid [UserVerified =. True, UserVerkey =. Nothing]
  134.                 return $ Just uid
  135.     getPassword = liftHandler . runDB . fmap (join . fmap userPassword) . get
  136.     setPassword uid pass = liftHandler . runDB $ update uid [UserPassword =. Just pass]
  137.     getEmailCreds email = liftHandler $ runDB $ do
  138.         mu <- getBy $ UniqueUser email
  139.         case mu of
  140.             Nothing -> return Nothing
  141.             Just (Entity uid u) -> return $ Just EmailCreds
  142.                 { emailCredsId = uid
  143.                 , emailCredsAuthId = Just uid
  144.                 , emailCredsStatus = isJust $ userPassword u
  145.                 , emailCredsVerkey = userVerkey u
  146.                 , emailCredsEmail = email
  147.                 }
  148.     getEmail = liftHandler . runDB . fmap (fmap userEmail) . get
  150. getHomeR :: Handler Html
  151. getHomeR = do
  152.     maid <- maybeAuthId
  153.     defaultLayout
  154.         [whamlet|
  155.             <p>Your current auth ID: #{show maid}
  156.             $maybe _ <- maid
  157.                 <p>
  158.                     <a href=@{AuthR LogoutR}>Logout
  159.             $nothing
  160.                 <p>
  161.                     <a href=@{AuthR LoginR}>Go to the login page
  162.         |]
  164. main :: IO ()
  165. main = runNoLoggingT $ withSqliteConn "email.db3" $ \conn -> liftIO $ do
  166.     runSqlConn (runMigration migrateAll) conn
  167.     warp 3000 $ App conn

Authorization

Once you can authenticate your users, you can use their credentials to authorize requests. Authorization in Yesod is simple and declarative: most of the time, you just need to add the authRoute and isAuthorized methods to your Yesod typeclass instance. Let’s see an example.

  1. {-# LANGUAGE MultiParamTypeClasses #-}
  2. {-# LANGUAGE OverloadedStrings     #-}
  3. {-# LANGUAGE QuasiQuotes           #-}
  4. {-# LANGUAGE TemplateHaskell       #-}
  5. {-# LANGUAGE TypeFamilies          #-}
  6. import           Data.Default         (def)
  7. import           Data.Text            (Text)
  8. import           Network.HTTP.Conduit (Manager, newManager, tlsManagerSettings)
  9. import           Yesod
  10. import           Yesod.Auth
  11. import           Yesod.Auth.Dummy -- just for testing, don't use in real life!!!
  13. data App = App
  14.     { httpManager :: Manager
  15.     }
  17. mkYesod "App" [parseRoutes|
  18. /      HomeR  GET POST
  19. /admin AdminR GET
  20. /auth  AuthR  Auth getAuth
  21. |]
  23. instance Yesod App where
  24.     authRoute _ = Just $ AuthR LoginR
  26.     -- route name, then a boolean indicating if it's a write request
  27.     isAuthorized HomeR True = isAdmin
  28.     isAuthorized AdminR _ = isAdmin
  30.     -- anyone can access other pages
  31.     isAuthorized _ _ = return Authorized
  33. isAdmin = do
  34.     mu <- maybeAuthId
  35.     return $ case mu of
  36.         Nothing -> AuthenticationRequired
  37.         Just "admin" -> Authorized
  38.         Just _ -> Unauthorized "You must be an admin"
  40. instance YesodAuth App where
  41.     type AuthId App = Text
  42.     authenticate = return . Authenticated . credsIdent
  44.     loginDest _ = HomeR
  45.     logoutDest _ = HomeR
  47.     authPlugins _ = [authDummy]
  49.     maybeAuthId = lookupSession "_ID"
  51. instance RenderMessage App FormMessage where
  52.     renderMessage _ _ = defaultFormMessage
  54. getHomeR :: Handler Html
  55. getHomeR = do
  56.     maid <- maybeAuthId
  57.     defaultLayout
  58.         [whamlet|
  59.             <p>Note: Log in as "admin" to be an administrator.
  60.             <p>Your current auth ID: #{show maid}
  61.             $maybe _ <- maid
  62.                 <p>
  63.                     <a href=@{AuthR LogoutR}>Logout
  64.             <p>
  65.                 <a href=@{AdminR}>Go to admin page
  66.             <form method=post>
  67.                 Make a change (admins only)
  68.                 \ #
  69.                 <input type=submit>
  70.         |]
  72. postHomeR :: Handler ()
  73. postHomeR = do
  74.     setMessage "You made some change to the page"
  75.     redirect HomeR
  77. getAdminR :: Handler Html
  78. getAdminR = defaultLayout
  79.     [whamlet|
  80.         <p>I guess you're an admin!
  81.         <p>
  82.             <a href=@{HomeR}>Return to homepage
  83.     |]
  85. main :: IO ()
  86. main = do
  87.     manager <- newManager tlsManagerSettings
  88.     warp 3000 $ App manager

authRoute should be your login page, almost always AuthR LoginR. isAuthorized is a function that takes two parameters: the requested route, and whether or not the request was a “write” request. You can actually change the meaning of what a write request is using the isWriteRequest method, but the out-of-the-box version follows RESTful principles: anything but a GET, HEAD, OPTIONS or TRACE request is a write request.

What’s convenient about the body of isAuthorized is that you can run any Handler code you want. This means you can:

  • Access the filesystem (normal IO)

  • Lookup values in the database

  • Pull any session or request values you want

Using these techniques, you can develop as sophisticated an authorization system as you like, or even tie into existing systems used by your organization.

Conclusion

This chapter covered the basics of setting up user authentication, as well as how the built-in authorization functions provide a simple, declarative approach for users. While these are complicated concepts, with many approaches, Yesod should provide you with the building blocks you need to create your own customized auth solution.