WebGear.Core.Trait.Auth.Basic

HTTP basic authentication support.

Middlewares defined in this module add basic authentication support to handlers. In most cases, you just need to use BasicAuth trait and basicAuth middleware. The table below describes when to use other traits and middlewares.

Type	Auth Scheme	Trait	Middleware
Required	Basic	BasicAuth	basicAuth
Optional	Basic	BasicAuth' Optional	optionalBasicAuth
Required	Any scheme	BasicAuth' Required	basicAuth'
Optional	Any scheme	BasicAuth' Optional	optionalBasicAuth'

For example, given this handler:

myHandler :: (Handler h IO, HasTrait (BasicAuth IO () Credentials) req) => RequestHandler h req
myHandler = ....

and the following definitions:

authConfig :: BasicAuth IO () Credentials
authConfig = BasicAuth' { toBasicAttribute = pure . Right }

type ErrorTraits = [Status, RequiredHeader "Content-Type" Text, RequiredHeader "WWW-Authenticate" Text, Body Text]

errorHandler :: (Handler h IO, Sets h ErrorTraits Response)
             => h (Linked req Request, BasicAuthError e) Response
errorHandler = respondUnauthorized "Basic" "MyRealm"

we can add basic authentication to myHandler:

myHandlerWithAuth :: (Handler h IO, Get h (BasicAuth IO () Credentials) Request, Sets h ErrorTraits Response)
                  => RequestHandler h req
myHandlerWithAuth = basicAuth authConfig errorHandler myHandler

The middlewares defined below take a BasicAuth' parameter which is a newtype wrapper over a function of type Credentials -> m (Either e a). This is used to convert the user supplied credentials to a value of type a or fail with an error of type e. The next handler is invoked after this conversion and can access a as a trait attribute.

Middlewares marked as Required take an additional error handling arrow as a parameter. This arrow is used when an error is encountered in authentication. This arrow receives the original request and a BasicAuthError as inputs and must produce a response as the output.

Middlewares marked as Optional do not have this additional error handling arrow. Instead, the trait attribute is of type Either (BasicAuthError e) a. The next handler will get the errors in this trait attribute and must handle it.

Documentation

newtype BasicAuth' (x :: Existence) (scheme :: Symbol) m e a

Trait for HTTP basic authentication: https://tools.ietf.org/html/rfc7617

Constructors

BasicAuth'

Fields

• toBasicAttribute :: Credentials -> m (Either e a)

  Convert the credentials to the trait attribute or an error

Instances

TraitAbsence (BasicAuth' 'Required scheme m e a) Request

Defined in WebGear.Core.Trait.Auth.Basic

Associated Types

type Absence (BasicAuth' 'Required scheme m e a) Request

TraitAbsence (BasicAuth' 'Optional scheme m e a) Request

Defined in WebGear.Core.Trait.Auth.Basic

Associated Types

type Absence (BasicAuth' 'Optional scheme m e a) Request

Trait (BasicAuth' 'Required scheme m e a) Request

Defined in WebGear.Core.Trait.Auth.Basic

Associated Types

type Attribute (BasicAuth' 'Required scheme m e a) Request

Trait (BasicAuth' 'Optional scheme m e a) Request

Defined in WebGear.Core.Trait.Auth.Basic

Associated Types

type Attribute (BasicAuth' 'Optional scheme m e a) Request

type Absence (BasicAuth' 'Required scheme m e a) Request

Defined in WebGear.Core.Trait.Auth.Basic

type Absence (BasicAuth' 'Required scheme m e a) Request = BasicAuthError e

type Absence (BasicAuth' 'Optional scheme m e a) Request

Defined in WebGear.Core.Trait.Auth.Basic

type Absence (BasicAuth' 'Optional scheme m e a) Request = Void

type Attribute (BasicAuth' 'Required scheme m e a) Request

Defined in WebGear.Core.Trait.Auth.Basic

type Attribute (BasicAuth' 'Required scheme m e a) Request = a

type Attribute (BasicAuth' 'Optional scheme m e a) Request

Defined in WebGear.Core.Trait.Auth.Basic

type Attribute (BasicAuth' 'Optional scheme m e a) Request = Either (BasicAuthError e) a

type BasicAuth = BasicAuth' Required "Basic"

Trait for HTTP basic authentication with the Basic scheme.

newtype Realm

The protection space for authentication

Constructors

Realm ByteString

Instances

Eq Realm

Defined in WebGear.Core.Trait.Auth.Common

Methods

(==) :: Realm -> Realm -> Bool

(/=) :: Realm -> Realm -> Bool

Ord Realm

Defined in WebGear.Core.Trait.Auth.Common

Methods

compare :: Realm -> Realm -> Ordering

(<) :: Realm -> Realm -> Bool

(<=) :: Realm -> Realm -> Bool

(>) :: Realm -> Realm -> Bool

(>=) :: Realm -> Realm -> Bool

max :: Realm -> Realm -> Realm

min :: Realm -> Realm -> Realm

Read Realm

Defined in WebGear.Core.Trait.Auth.Common

Methods

readsPrec :: Int -> ReadS Realm

readList :: ReadS [Realm]

readPrec :: ReadPrec Realm

readListPrec :: ReadPrec [Realm]

Show Realm

Defined in WebGear.Core.Trait.Auth.Common

Methods

showsPrec :: Int -> Realm -> ShowS

show :: Realm -> String

showList :: [Realm] -> ShowS

IsString Realm

Defined in WebGear.Core.Trait.Auth.Common

Methods

fromString :: String -> Realm

newtype Username

Username for basic authentication. Valid usernames cannot contain ':' characters.

Constructors

Username ByteString

Instances

Eq Username

Defined in WebGear.Core.Trait.Auth.Basic

Methods

(==) :: Username -> Username -> Bool

(/=) :: Username -> Username -> Bool

Ord Username

Defined in WebGear.Core.Trait.Auth.Basic

Methods

compare :: Username -> Username -> Ordering

(<) :: Username -> Username -> Bool

(<=) :: Username -> Username -> Bool

(>) :: Username -> Username -> Bool

(>=) :: Username -> Username -> Bool

max :: Username -> Username -> Username

min :: Username -> Username -> Username

Read Username

Defined in WebGear.Core.Trait.Auth.Basic

Methods

readsPrec :: Int -> ReadS Username

readList :: ReadS [Username]

readPrec :: ReadPrec Username

readListPrec :: ReadPrec [Username]

Show Username

Defined in WebGear.Core.Trait.Auth.Basic

Methods

showsPrec :: Int -> Username -> ShowS

show :: Username -> String

showList :: [Username] -> ShowS

IsString Username

Defined in WebGear.Core.Trait.Auth.Basic

Methods

fromString :: String -> Username

newtype Password

Password for basic authentication.

Constructors

Password ByteString

Instances

Eq Password

Defined in WebGear.Core.Trait.Auth.Basic

Methods

(==) :: Password -> Password -> Bool

(/=) :: Password -> Password -> Bool

Ord Password

Defined in WebGear.Core.Trait.Auth.Basic

Methods

compare :: Password -> Password -> Ordering

(<) :: Password -> Password -> Bool

(<=) :: Password -> Password -> Bool

(>) :: Password -> Password -> Bool

(>=) :: Password -> Password -> Bool

max :: Password -> Password -> Password

min :: Password -> Password -> Password

Read Password

Defined in WebGear.Core.Trait.Auth.Basic

Methods

readsPrec :: Int -> ReadS Password

readList :: ReadS [Password]

readPrec :: ReadPrec Password

readListPrec :: ReadPrec [Password]

Show Password

Defined in WebGear.Core.Trait.Auth.Basic

Methods

showsPrec :: Int -> Password -> ShowS

show :: Password -> String

showList :: [Password] -> ShowS

IsString Password

Defined in WebGear.Core.Trait.Auth.Basic

Methods

fromString :: String -> Password

data Credentials

Basic authentication credentials retrieved from an HTTP request

Constructors

Credentials

Fields

• credentialsUsername :: !Username
• credentialsPassword :: !Password

Instances

Eq Credentials

Defined in WebGear.Core.Trait.Auth.Basic

Methods

(==) :: Credentials -> Credentials -> Bool

(/=) :: Credentials -> Credentials -> Bool

Ord Credentials

Defined in WebGear.Core.Trait.Auth.Basic

Methods

compare :: Credentials -> Credentials -> Ordering

(<) :: Credentials -> Credentials -> Bool

(<=) :: Credentials -> Credentials -> Bool

(>) :: Credentials -> Credentials -> Bool

(>=) :: Credentials -> Credentials -> Bool

max :: Credentials -> Credentials -> Credentials

min :: Credentials -> Credentials -> Credentials

Read Credentials

Defined in WebGear.Core.Trait.Auth.Basic

Methods

readsPrec :: Int -> ReadS Credentials

readList :: ReadS [Credentials]

readPrec :: ReadPrec Credentials

readListPrec :: ReadPrec [Credentials]

Show Credentials

Defined in WebGear.Core.Trait.Auth.Basic

Methods

showsPrec :: Int -> Credentials -> ShowS

show :: Credentials -> String

showList :: [Credentials] -> ShowS

data BasicAuthError e

Error retrieving basic authentication credentials

Constructors

BasicAuthHeaderMissing

BasicAuthSchemeMismatch

BasicAuthCredsBadFormat

BasicAuthAttributeError e

Instances

Eq e => Eq (BasicAuthError e)

Defined in WebGear.Core.Trait.Auth.Basic

Methods

(==) :: BasicAuthError e -> BasicAuthError e -> Bool

(/=) :: BasicAuthError e -> BasicAuthError e -> Bool

Read e => Read (BasicAuthError e)

Defined in WebGear.Core.Trait.Auth.Basic

Methods

readsPrec :: Int -> ReadS (BasicAuthError e)

readList :: ReadS [BasicAuthError e]

readPrec :: ReadPrec (BasicAuthError e)

readListPrec :: ReadPrec [BasicAuthError e]

Show e => Show (BasicAuthError e)

Defined in WebGear.Core.Trait.Auth.Basic

Methods

showsPrec :: Int -> BasicAuthError e -> ShowS

show :: BasicAuthError e -> String

showList :: [BasicAuthError e] -> ShowS

basicAuth

Arguments

:: forall m e t h req. (Get h (BasicAuth' Required "Basic" m e t) Request, ArrowChoice h)

=> BasicAuth m e t

Authentication configuration

-> h (Linked req Request, BasicAuthError e) Response

Error handler

-> Middleware h req (BasicAuth m e t ': req)

Middleware to add basic authentication protection for a handler.

Example usage:

basicAuth cfg errorHandler nextHandler

The errorHandler is invoked if the credentials are invalid or missing. The nextHandler is invoked if the credentials were retrieved successfully.

basicAuth'

Arguments

:: forall scheme m e t h req. (Get h (BasicAuth' Required scheme m e t) Request, ArrowChoice h)

=> BasicAuth' Required scheme m e t

Authentication configuration

-> h (Linked req Request, BasicAuthError e) Response

Error handler

-> Middleware h req (BasicAuth' Required scheme m e t ': req)

Similar to basicAuth but supports a custom authentication scheme.

Example usage:

basicAuth' @"scheme" cfg errorHandler nextHandler

optionalBasicAuth

Arguments

:: forall m e t h req. (Get h (BasicAuth' Optional "Basic" m e t) Request, ArrowChoice h)

=> BasicAuth' Optional "Basic" m e t

Authentication configuration

-> Middleware h req (BasicAuth' Optional "Basic" m e t ': req)

Middleware to add optional basic authentication protection for a handler.

Example usage:

optionalBasicAuth cfg nextHandler

This middleware will not fail if credentials are invalid or missing. Instead the trait attribute is of type Either (BasicAuthError e) t so that the handler can process the authentication error appropriately.

optionalBasicAuth'

Arguments

:: forall scheme m e t h req. (Get h (BasicAuth' Optional scheme m e t) Request, ArrowChoice h)

=> BasicAuth' Optional scheme m e t

Authentication configuration

-> Middleware h req (BasicAuth' Optional scheme m e t ': req)

Similar to optionalBasicAuth but supports a custom authentication scheme.

Example usage:

optionalBasicAuth' @"scheme" cfg nextHandler