Yesod.Auth

Subsite

data Auth

Instances

RenderRoute Auth

Defined in Yesod.Auth.Routes

Associated Types

data Route Auth :: Type

Methods

renderRoute :: Route Auth -> ([Text], [(Text, Text)])

ParseRoute Auth

Defined in Yesod.Auth.Routes

Methods

parseRoute :: ([Text], [(Text, Text)]) -> Maybe (Route Auth)

RouteAttrs Auth

Defined in Yesod.Auth.Routes

Methods

routeAttrs :: Route Auth -> Set Text

YesodAuth master => YesodSubDispatch Auth master

Defined in Yesod.Auth

Methods

yesodSubDispatch :: YesodSubRunnerEnv Auth master -> Application

Eq (Route Auth)

Defined in Yesod.Auth.Routes

Methods

(==) :: Route Auth -> Route Auth -> Bool

(/=) :: Route Auth -> Route Auth -> Bool

Read (Route Auth)

Defined in Yesod.Auth.Routes

Methods

readsPrec :: Int -> ReadS (Route Auth)

readList :: ReadS [Route Auth]

readPrec :: ReadPrec (Route Auth)

readListPrec :: ReadPrec [Route Auth]

Show (Route Auth)

Defined in Yesod.Auth.Routes

Methods

showsPrec :: Int -> Route Auth -> ShowS

show :: Route Auth -> String

showList :: [Route Auth] -> ShowS

data Route Auth

Defined in Yesod.Auth.Routes

data Route Auth

• = CheckR
• | LoginR
• | LogoutR
• | PluginR Text Texts

type AuthRoute = Route Auth

data family Route a :: Type

The type-safe URLs associated with a site argument.

Instances

RedirectUrl master (Route master)

Defined in Yesod.Core.Handler

Methods

toTextUrl :: (MonadHandler m, HandlerSite m ~ master) => Route master -> m Text

(key ~ Text, val ~ Text) => RedirectUrl master (Route master, [(key, val)])

Defined in Yesod.Core.Handler

Methods

toTextUrl :: (MonadHandler m, HandlerSite m ~ master) => (Route master, [(key, val)]) -> m Text

(key ~ Text, val ~ Text) => RedirectUrl master (Route master, Map key val)

Defined in Yesod.Core.Handler

Methods

toTextUrl :: (MonadHandler m, HandlerSite m ~ master) => (Route master, Map key val) -> m Text

Eq (Route LiteApp)

Defined in Yesod.Core.Internal.LiteApp

Methods

(==) :: Route LiteApp -> Route LiteApp -> Bool

(/=) :: Route LiteApp -> Route LiteApp -> Bool

Eq (Route WaiSubsite)

Defined in Yesod.Core.Types

Methods

(==) :: Route WaiSubsite -> Route WaiSubsite -> Bool

(/=) :: Route WaiSubsite -> Route WaiSubsite -> Bool

Eq (Route WaiSubsiteWithAuth)

Defined in Yesod.Core.Types

Methods

(==) :: Route WaiSubsiteWithAuth -> Route WaiSubsiteWithAuth -> Bool

(/=) :: Route WaiSubsiteWithAuth -> Route WaiSubsiteWithAuth -> Bool

Eq (Route Auth)

Defined in Yesod.Auth.Routes

Methods

(==) :: Route Auth -> Route Auth -> Bool

(/=) :: Route Auth -> Route Auth -> Bool

Ord (Route LiteApp)

Defined in Yesod.Core.Internal.LiteApp

Methods

compare :: Route LiteApp -> Route LiteApp -> Ordering

(<) :: Route LiteApp -> Route LiteApp -> Bool

(<=) :: Route LiteApp -> Route LiteApp -> Bool

(>) :: Route LiteApp -> Route LiteApp -> Bool

(>=) :: Route LiteApp -> Route LiteApp -> Bool

max :: Route LiteApp -> Route LiteApp -> Route LiteApp

min :: Route LiteApp -> Route LiteApp -> Route LiteApp

Ord (Route WaiSubsite)

Defined in Yesod.Core.Types

Methods

compare :: Route WaiSubsite -> Route WaiSubsite -> Ordering

(<) :: Route WaiSubsite -> Route WaiSubsite -> Bool

(<=) :: Route WaiSubsite -> Route WaiSubsite -> Bool

(>) :: Route WaiSubsite -> Route WaiSubsite -> Bool

(>=) :: Route WaiSubsite -> Route WaiSubsite -> Bool

max :: Route WaiSubsite -> Route WaiSubsite -> Route WaiSubsite

min :: Route WaiSubsite -> Route WaiSubsite -> Route WaiSubsite

Ord (Route WaiSubsiteWithAuth)

Defined in Yesod.Core.Types

Methods

compare :: Route WaiSubsiteWithAuth -> Route WaiSubsiteWithAuth -> Ordering

(<) :: Route WaiSubsiteWithAuth -> Route WaiSubsiteWithAuth -> Bool

(<=) :: Route WaiSubsiteWithAuth -> Route WaiSubsiteWithAuth -> Bool

(>) :: Route WaiSubsiteWithAuth -> Route WaiSubsiteWithAuth -> Bool

(>=) :: Route WaiSubsiteWithAuth -> Route WaiSubsiteWithAuth -> Bool

max :: Route WaiSubsiteWithAuth -> Route WaiSubsiteWithAuth -> Route WaiSubsiteWithAuth

min :: Route WaiSubsiteWithAuth -> Route WaiSubsiteWithAuth -> Route WaiSubsiteWithAuth

Read (Route LiteApp)

Defined in Yesod.Core.Internal.LiteApp

Methods

readsPrec :: Int -> ReadS (Route LiteApp)

readList :: ReadS [Route LiteApp]

readPrec :: ReadPrec (Route LiteApp)

readListPrec :: ReadPrec [Route LiteApp]

Read (Route WaiSubsite)

Defined in Yesod.Core.Types

Methods

readsPrec :: Int -> ReadS (Route WaiSubsite)

readList :: ReadS [Route WaiSubsite]

readPrec :: ReadPrec (Route WaiSubsite)

readListPrec :: ReadPrec [Route WaiSubsite]

Read (Route WaiSubsiteWithAuth)

Defined in Yesod.Core.Types

Methods

readsPrec :: Int -> ReadS (Route WaiSubsiteWithAuth)

readList :: ReadS [Route WaiSubsiteWithAuth]

readPrec :: ReadPrec (Route WaiSubsiteWithAuth)

readListPrec :: ReadPrec [Route WaiSubsiteWithAuth]

Read (Route Auth)

Defined in Yesod.Auth.Routes

Methods

readsPrec :: Int -> ReadS (Route Auth)

readList :: ReadS [Route Auth]

readPrec :: ReadPrec (Route Auth)

readListPrec :: ReadPrec [Route Auth]

Show (Route LiteApp)

Defined in Yesod.Core.Internal.LiteApp

Methods

showsPrec :: Int -> Route LiteApp -> ShowS

show :: Route LiteApp -> String

showList :: [Route LiteApp] -> ShowS

Show (Route WaiSubsite)

Defined in Yesod.Core.Types

Methods

showsPrec :: Int -> Route WaiSubsite -> ShowS

show :: Route WaiSubsite -> String

showList :: [Route WaiSubsite] -> ShowS

Show (Route WaiSubsiteWithAuth)

Defined in Yesod.Core.Types

Methods

showsPrec :: Int -> Route WaiSubsiteWithAuth -> ShowS

show :: Route WaiSubsiteWithAuth -> String

showList :: [Route WaiSubsiteWithAuth] -> ShowS

Show (Route Auth)

Defined in Yesod.Auth.Routes

Methods

showsPrec :: Int -> Route Auth -> ShowS

show :: Route Auth -> String

showList :: [Route Auth] -> ShowS

data Route LiteApp

Defined in Yesod.Core.Internal.LiteApp

data Route LiteApp = LiteAppRoute [Text]

data Route WaiSubsite

Defined in Yesod.Core.Types

data Route WaiSubsite = WaiSubsiteRoute [Text] [(Text, Text)]

data Route WaiSubsiteWithAuth

Defined in Yesod.Core.Types

data Route WaiSubsiteWithAuth = WaiSubsiteWithAuthRoute [Text] [(Text, Text)]

data Route Auth

Defined in Yesod.Auth.Routes

data Route Auth

• = CheckR
• | LoginR
• | LogoutR
• | PluginR Text Texts

data AuthPlugin master

Constructors

AuthPlugin

Fields

• apName :: Text
• apDispatch :: Method -> [Piece] -> AuthHandler master TypedContent
• apLogin :: (Route Auth -> Route master) -> WidgetFor master ()

getAuth :: a -> Auth

class (Yesod master, PathPiece (AuthId master), RenderMessage master FormMessage) => YesodAuth master where

Minimal complete definition

loginDest, logoutDest, (authenticate | getAuthId), authPlugins

Associated Types

type AuthId master

Methods

authLayout :: (MonadHandler m, HandlerSite m ~ master) => WidgetFor master () -> m Html

specify the layout. Uses defaultLayout by default

loginDest :: master -> Route master

Default destination on successful login, if no other destination exists.

logoutDest :: master -> Route master

Default destination on successful logout, if no other destination exists.

authenticate :: (MonadHandler m, HandlerSite m ~ master) => Creds master -> m (AuthenticationResult master)

Perform authentication based on the given credentials.

Default implementation is in terms of getAuthId

@since: 1.4.4

getAuthId :: (MonadHandler m, HandlerSite m ~ master) => Creds master -> m (Maybe (AuthId master))

Deprecated: Define authenticate instead; getAuthId will be removed in the next major version

Determine the ID associated with the set of credentials.

Default implementation is in terms of authenticate

authPlugins :: master -> [AuthPlugin master]

Which authentication backends to use.

loginHandler :: AuthHandler master Html

What to show on the login page.

By default this calls defaultLoginHandler, which concatenates plugin widgets and wraps the result in authLayout. Override if you need fancy widget containers, additional functionality, or an entirely custom page. For example, in some applications you may want to prevent the login page being displayed for a user who is already logged in, even if the URL is visited explicitly; this can be done by overriding loginHandler in your instance declaration with something like:

instance YesodAuth App where
    ...
    loginHandler = do
        ma <- lift maybeAuthId
        when (isJust ma) $
            lift $ redirect HomeR   -- or any other Handler code you want
        defaultLoginHandler

renderAuthMessage

Arguments

:: master

-> [Text]

languages

-> AuthMessage

-> Text

Used for i18n of messages provided by this package.

redirectToReferer :: master -> Bool

After login and logout, redirect to the referring page, instead of loginDest and logoutDest. Default is False.

redirectToCurrent :: master -> Bool

When being redirected to the login page should the current page be set to redirect back to. Default is True.

Since: 1.4.21

authHttpManager :: (MonadHandler m, HandlerSite m ~ master) => m Manager

Return an HTTP connection manager that is stored in the foundation type. This allows backends to reuse persistent connections. If none of the backends you're using use HTTP connections, you can safely return error "authHttpManager" here.

onLogin :: (MonadHandler m, master ~ HandlerSite m) => m ()

Called on a successful login. By default, calls addMessageI "success" NowLoggedIn.

onLogout :: (MonadHandler m, master ~ HandlerSite m) => m ()

Called on logout. By default, does nothing

maybeAuthId :: (MonadHandler m, master ~ HandlerSite m) => m (Maybe (AuthId master))

Retrieves user credentials, if user is authenticated.

By default, this calls defaultMaybeAuthId to get the user ID from the session. This can be overridden to allow authentication via other means, such as checking for a special token in a request header. This is especially useful for creating an API to be accessed via some means other than a browser.

Since: 1.2.0

maybeAuthId :: (MonadHandler m, master ~ HandlerSite m, YesodAuthPersist master, Typeable (AuthEntity master)) => m (Maybe (AuthId master))

Retrieves user credentials, if user is authenticated.

By default, this calls defaultMaybeAuthId to get the user ID from the session. This can be overridden to allow authentication via other means, such as checking for a special token in a request header. This is especially useful for creating an API to be accessed via some means other than a browser.

Since: 1.2.0

onErrorHtml :: (MonadHandler m, HandlerSite m ~ master) => Route master -> Text -> m Html

Called on login error for HTTP requests. By default, calls addMessage with "error" as status and redirects to dest.

runHttpRequest :: (MonadHandler m, HandlerSite m ~ master, MonadUnliftIO m) => Request -> (Response BodyReader -> m a) -> m a

runHttpRequest gives you a chance to handle an HttpException and retry The default behavior is to simply execute the request which will throw an exception on failure

The HTTP Request is given in case it is useful to change behavior based on inspecting the request. This is an experimental API that is not broadly used throughout the yesod-auth code base

class (YesodAuth master, YesodPersist master) => YesodAuthPersist master where

Class which states that the given site is an instance of YesodAuth and that its AuthId is a lookup key for the full user information in a YesodPersist database.

The default implementation of getAuthEntity assumes that the AuthId for the YesodAuth superclass is in fact a persistent Key for the given value. This is the common case in Yesod, and means that you can easily look up the full information on a given user.

Since: 1.4.0

Minimal complete definition

Nothing

Associated Types

type AuthEntity master :: *

If the AuthId for a given site is a persistent ID, this will give the value for that entity. E.g.:

type AuthId MySite = UserId
AuthEntity MySite ~ User

Since: 1.2.0

Methods

getAuthEntity :: (MonadHandler m, HandlerSite m ~ master) => AuthId master -> m (Maybe (AuthEntity master))

getAuthEntity :: (YesodPersistBackend master ~ backend, PersistRecordBackend (AuthEntity master) backend, Key (AuthEntity master) ~ AuthId master, PersistStore backend, MonadHandler m, HandlerSite m ~ master) => AuthId master -> m (Maybe (AuthEntity master))

Plugin interface

data Creds master

User credentials

Constructors

Creds

Fields

• credsPlugin :: Text

  How the user was authenticated

• credsIdent :: Text

  Identifier. Exact meaning depends on plugin.

• credsExtra :: [(Text, Text)]

Instances

Show (Creds master)

Defined in Yesod.Auth

Methods

showsPrec :: Int -> Creds master -> ShowS

show :: Creds master -> String

showList :: [Creds master] -> ShowS

setCreds

Arguments

:: (MonadHandler m, YesodAuth (HandlerSite m))

=> Bool

if HTTP redirects should be done

-> Creds (HandlerSite m)

new credentials

-> m ()

Sets user credentials for the session after checking them with authentication backends.

setCredsRedirect

Arguments

:: (MonadHandler m, YesodAuth (HandlerSite m))

=> Creds (HandlerSite m)

new credentials

-> m TypedContent

clearCreds

Arguments

:: (MonadHandler m, YesodAuth (HandlerSite m))

=> Bool

if HTTP, redirect to logoutDest

-> m ()

Clears current user credentials for the session.

Since: 1.1.7

loginErrorMessage :: (MonadHandler m, YesodAuth (HandlerSite m)) => Route (HandlerSite m) -> Text -> m TypedContent

For HTML, set the message and redirect to the route. For JSON, send the message and a 401 status

loginErrorMessageI :: Route Auth -> AuthMessage -> AuthHandler master TypedContent

User functions

data AuthenticationResult master

The result of an authentication based on credentials

Since: 1.4.4

Constructors

Authenticated (AuthId master)

Authenticated successfully

UserError AuthMessage

Invalid credentials provided by user

ServerError Text

Some other error

defaultMaybeAuthId :: (MonadHandler m, HandlerSite m ~ master, YesodAuthPersist master, Typeable (AuthEntity master)) => m (Maybe (AuthId master))

Retrieves user credentials from the session, if user is authenticated.

This function does not confirm that the credentials are valid, see maybeAuthIdRaw for more information. The first call in a request does a database request to make sure that the account is still in the database.

Since: 1.1.2

defaultLoginHandler :: AuthHandler master Html

Default handler to show the login page.

This is the default loginHandler. It concatenates plugin widgets and wraps the result in authLayout. See loginHandler for more details.

Since: 1.4.9

maybeAuthPair :: (YesodAuthPersist master, Typeable (AuthEntity master), MonadHandler m, HandlerSite m ~ master) => m (Maybe (AuthId master, AuthEntity master))

Similar to maybeAuth, but doesn’t assume that you are using a Persistent database.

Since: 1.4.0

maybeAuth :: (YesodAuthPersist master, val ~ AuthEntity master, Key val ~ AuthId master, PersistEntity val, Typeable val, MonadHandler m, HandlerSite m ~ master) => m (Maybe (Entity val))

Similar to maybeAuthId, but additionally look up the value associated with the user's database identifier to get the value in the database. This assumes that you are using a Persistent database.

Since: 1.1.0

requireAuthId :: (MonadHandler m, YesodAuth (HandlerSite m)) => m (AuthId (HandlerSite m))

Similar to maybeAuthId, but redirects to a login page if user is not authenticated or responds with error 401 if this is an API client (expecting JSON).

Since: 1.1.0

requireAuthPair :: (YesodAuthPersist master, Typeable (AuthEntity master), MonadHandler m, HandlerSite m ~ master) => m (AuthId master, AuthEntity master)

Similar to requireAuth, but not tied to Persistent's Entity type. Instead, the AuthId and AuthEntity are returned in a tuple.

Since: 1.4.0

requireAuth :: (YesodAuthPersist master, val ~ AuthEntity master, Key val ~ AuthId master, PersistEntity val, Typeable val, MonadHandler m, HandlerSite m ~ master) => m (Entity val)

Similar to maybeAuth, but redirects to a login page if user is not authenticated or responds with error 401 if this is an API client (expecting JSON).

Since: 1.1.0

Exception

data AuthException

Constructors

InvalidFacebookResponse

Instances

Show AuthException

Defined in Yesod.Auth

Methods

showsPrec :: Int -> AuthException -> ShowS

show :: AuthException -> String

showList :: [AuthException] -> ShowS

Exception AuthException

Defined in Yesod.Auth

Methods

toException :: AuthException -> SomeException

fromException :: SomeException -> Maybe AuthException

displayException :: AuthException -> String

Helper

type MonadAuthHandler master m = (MonadHandler m, YesodAuth master, master ~ HandlerSite m, Auth ~ SubHandlerSite m, MonadUnliftIO m)

type AuthHandler master a = forall m. MonadAuthHandler master m => m a

Internal

credsKey :: Text

Internal session key used to hold the authentication information.

Since: 1.2.3

provideJsonMessage :: Monad m => Text -> Writer (Endo [ProvidedRep m]) ()

messageJson401 :: MonadHandler m => Text -> m Html -> m TypedContent

asHtml :: Html -> Html

Orphan instances

YesodAuth master => RenderMessage master AuthMessage

Methods

renderMessage :: master -> [Lang] -> AuthMessage -> Text

YesodAuth master => YesodSubDispatch Auth master

Methods

yesodSubDispatch :: YesodSubRunnerEnv Auth master -> Application