Safe Haskell	Safe-Inferred
Language	Haskell2010

WebGear.Core.Trait.Auth.Basic

Description

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) ts) => RequestHandler h ts
myHandler = ....

and the following definitions:

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

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

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

we can add basic authentication to myHandler:

myHandlerWithAuth :: (Handler h IO, Get h (BasicAuth IO () Credentials), Sets h ErrorTraits)
                  => RequestHandler h ts
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.

Synopsis

newtype BasicAuth' (x :: Existence) (scheme :: Symbol) m e a = BasicAuth' {
- toBasicAttribute :: Credentials -> m (Either e a)
}
type BasicAuth = BasicAuth' Required "Basic"
newtype Realm = Realm ByteString
newtype Username = Username ByteString
newtype Password = Password ByteString
data Credentials = Credentials {
- credentialsUsername :: !Username
- credentialsPassword :: !Password
}
data BasicAuthError e
basicAuth :: forall m e t h ts. (ArrowChoice h, Get h (BasicAuth' Required "Basic" m e t), HasTrait (AuthorizationHeader "Basic") ts) => BasicAuth m e t -> h (Request `With` ts, BasicAuthError e) Response -> Middleware h ts (BasicAuth m e t : ts)
basicAuth' :: forall scheme m e t h ts. (ArrowChoice h, Get h (BasicAuth' Required scheme m e t), HasTrait (AuthorizationHeader scheme) ts) => BasicAuth' Required scheme m e t -> h (Request `With` ts, BasicAuthError e) Response -> Middleware h ts (BasicAuth' Required scheme m e t : ts)
optionalBasicAuth :: forall m e t h ts. (ArrowChoice h, Get h (BasicAuth' Optional "Basic" m e t), HasTrait (AuthorizationHeader "Basic") ts) => BasicAuth' Optional "Basic" m e t -> Middleware h ts (BasicAuth' Optional "Basic" m e t : ts)
optionalBasicAuth' :: forall scheme m e t h ts. (ArrowChoice h, Get h (BasicAuth' Optional scheme m e t), HasTrait (AuthorizationHeader scheme) ts) => BasicAuth' Optional scheme m e t -> Middleware h ts (BasicAuth' Optional scheme m e t : ts)

Documentation

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

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

Instances details

type Absence (BasicAuth' 'Optional scheme m e a) Source #
Instance details Defined in WebGear.Core.Trait.Auth.Basic type Absence (BasicAuth' 'Optional scheme m e a) = Void
type Absence (BasicAuth' 'Required scheme m e a) Source #
Instance details Defined in WebGear.Core.Trait.Auth.Basic type Absence (BasicAuth' 'Required scheme m e a) = BasicAuthError e
type Attribute (BasicAuth' 'Optional scheme m e a) Request Source #
Instance details Defined in WebGear.Core.Trait.Auth.Basic type Attribute (BasicAuth' 'Optional scheme m e a) Request = Either (BasicAuthError e) a
type Attribute (BasicAuth' 'Required scheme m e a) Request Source #
Instance details Defined in WebGear.Core.Trait.Auth.Basic type Attribute (BasicAuth' 'Required scheme m e a) Request = a
type Prerequisite (BasicAuth' x scheme m e a) ts Source #
Instance details Defined in WebGear.Core.Trait.Auth.Basic type Prerequisite (BasicAuth' x scheme m e a) ts = HasTrait (AuthorizationHeader scheme) ts

type BasicAuth = BasicAuth' Required "Basic" Source #

Trait for HTTP basic authentication with the Basic scheme.

newtype Realm Source #

The protection space for authentication

Constructors

Realm ByteString

Instances

Instances details

IsString Realm Source #
Instance details Defined in WebGear.Core.Trait.Auth.Common Methods fromString :: String -> Realm #
Read Realm Source #
Instance details Defined in WebGear.Core.Trait.Auth.Common Methods readsPrec :: Int -> ReadS Realm # readList :: ReadS [Realm] # readPrec :: ReadPrec Realm # readListPrec :: ReadPrec [Realm] #
Show Realm Source #
Instance details Defined in WebGear.Core.Trait.Auth.Common Methods showsPrec :: Int -> Realm -> ShowS # show :: Realm -> String # showList :: [Realm] -> ShowS #
Eq Realm Source #
Instance details Defined in WebGear.Core.Trait.Auth.Common Methods (==) :: Realm -> Realm -> Bool # (/=) :: Realm -> Realm -> Bool #
Ord Realm Source #
Instance details 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 #

newtype Username Source #

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

Constructors

Username ByteString

Instances

Instances details

IsString Username Source #
Instance details Defined in WebGear.Core.Trait.Auth.Basic Methods fromString :: String -> Username #
Read Username Source #
Instance details Defined in WebGear.Core.Trait.Auth.Basic Methods readsPrec :: Int -> ReadS Username # readList :: ReadS [Username] # readPrec :: ReadPrec Username # readListPrec :: ReadPrec [Username] #
Show Username Source #
Instance details Defined in WebGear.Core.Trait.Auth.Basic Methods showsPrec :: Int -> Username -> ShowS # show :: Username -> String # showList :: [Username] -> ShowS #
Eq Username Source #
Instance details Defined in WebGear.Core.Trait.Auth.Basic Methods (==) :: Username -> Username -> Bool # (/=) :: Username -> Username -> Bool #
Ord Username Source #
Instance details 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 #

newtype Password Source #

Password for basic authentication.

Constructors

Password ByteString

Instances

Instances details

IsString Password Source #
Instance details Defined in WebGear.Core.Trait.Auth.Basic Methods fromString :: String -> Password #
Read Password Source #
Instance details Defined in WebGear.Core.Trait.Auth.Basic Methods readsPrec :: Int -> ReadS Password # readList :: ReadS [Password] # readPrec :: ReadPrec Password # readListPrec :: ReadPrec [Password] #
Show Password Source #
Instance details Defined in WebGear.Core.Trait.Auth.Basic Methods showsPrec :: Int -> Password -> ShowS # show :: Password -> String # showList :: [Password] -> ShowS #
Eq Password Source #
Instance details Defined in WebGear.Core.Trait.Auth.Basic Methods (==) :: Password -> Password -> Bool # (/=) :: Password -> Password -> Bool #
Ord Password Source #
Instance details 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 #

data Credentials Source #

Basic authentication credentials retrieved from an HTTP request

Constructors

Credentials
Fields credentialsUsername :: !Username credentialsPassword :: !Password

Instances

Instances details

Read Credentials Source #
Instance details Defined in WebGear.Core.Trait.Auth.Basic Methods readsPrec :: Int -> ReadS Credentials # readList :: ReadS [Credentials] # readPrec :: ReadPrec Credentials # readListPrec :: ReadPrec [Credentials] #
Show Credentials Source #
Instance details Defined in WebGear.Core.Trait.Auth.Basic Methods showsPrec :: Int -> Credentials -> ShowS # show :: Credentials -> String # showList :: [Credentials] -> ShowS #
Eq Credentials Source #
Instance details Defined in WebGear.Core.Trait.Auth.Basic Methods (==) :: Credentials -> Credentials -> Bool # (/=) :: Credentials -> Credentials -> Bool #
Ord Credentials Source #
Instance details 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 #

data BasicAuthError e Source #

Error retrieving basic authentication credentials

Constructors

BasicAuthHeaderMissing
BasicAuthSchemeMismatch
BasicAuthCredsBadFormat
BasicAuthAttributeError e

Instances

Instances details

Read e => Read (BasicAuthError e) Source #
Instance details 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) Source #
Instance details Defined in WebGear.Core.Trait.Auth.Basic Methods showsPrec :: Int -> BasicAuthError e -> ShowS # show :: BasicAuthError e -> String # showList :: [BasicAuthError e] -> ShowS #
Eq e => Eq (BasicAuthError e) Source #
Instance details Defined in WebGear.Core.Trait.Auth.Basic Methods (==) :: BasicAuthError e -> BasicAuthError e -> Bool # (/=) :: BasicAuthError e -> BasicAuthError e -> Bool #

basicAuth Source #

Arguments

:: forall m e t h ts. (ArrowChoice h, Get h (BasicAuth' Required "Basic" m e t), HasTrait (AuthorizationHeader "Basic") ts)
=> BasicAuth m e t	Authentication configuration
-> h (Request `With` ts, BasicAuthError e) Response	Error handler
-> Middleware h ts (BasicAuth m e t : ts)

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' Source #

Arguments

:: forall scheme m e t h ts. (ArrowChoice h, Get h (BasicAuth' Required scheme m e t), HasTrait (AuthorizationHeader scheme) ts)
=> BasicAuth' Required scheme m e t	Authentication configuration
-> h (Request `With` ts, BasicAuthError e) Response	Error handler
-> Middleware h ts (BasicAuth' Required scheme m e t : ts)

Similar to basicAuth but supports a custom authentication scheme.

Example usage:

basicAuth' @"scheme" cfg errorHandler nextHandler

optionalBasicAuth Source #

Arguments

:: forall m e t h ts. (ArrowChoice h, Get h (BasicAuth' Optional "Basic" m e t), HasTrait (AuthorizationHeader "Basic") ts)
=> BasicAuth' Optional "Basic" m e t	Authentication configuration
-> Middleware h ts (BasicAuth' Optional "Basic" m e t : ts)

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' Source #

Arguments

:: forall scheme m e t h ts. (ArrowChoice h, Get h (BasicAuth' Optional scheme m e t), HasTrait (AuthorizationHeader scheme) ts)
=> BasicAuth' Optional scheme m e t	Authentication configuration
-> Middleware h ts (BasicAuth' Optional scheme m e t : ts)

Similar to optionalBasicAuth but supports a custom authentication scheme.

Example usage:

optionalBasicAuth' @"scheme" cfg nextHandler