Safe Haskell | Safe-Inferred |
---|---|
Language | Haskell2010 |
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, RequiredRequestHeader "Content-Type" Text, RequiredRequestHeader "WWW-Authenticate" Text, Body Text] errorHandler :: (Handler
h IO, Sets h ErrorTraits Response) => 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
) Request, Sets h ErrorTraits Response) =>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
. This is used to convert the user supplied credentials to a
value of type Credentials
-> m (Either
e a)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
(
. The next handler will get the errors in this
trait attribute and must handle it.BasicAuthError
e) a
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 {}
- data BasicAuthError e
- basicAuth :: forall m e t h ts. (ArrowChoice h, Get h (BasicAuth' Required "Basic" m e t) Request, 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) Request, 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) Request, 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) Request, 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
BasicAuth' | |
|
Instances
Trait (BasicAuth' 'Optional scheme m e a) Request Source # | |
Defined in WebGear.Core.Trait.Auth.Basic | |
Trait (BasicAuth' 'Required scheme m e a) Request Source # | |
Defined in WebGear.Core.Trait.Auth.Basic | |
TraitAbsence (BasicAuth' 'Optional scheme m e a) Request Source # | |
Defined in WebGear.Core.Trait.Auth.Basic | |
TraitAbsence (BasicAuth' 'Required scheme m e a) Request Source # | |
Defined in WebGear.Core.Trait.Auth.Basic | |
type Absence (BasicAuth' 'Optional scheme m e a) Request Source # | |
Defined in WebGear.Core.Trait.Auth.Basic | |
type Absence (BasicAuth' 'Required scheme m e a) Request Source # | |
Defined in WebGear.Core.Trait.Auth.Basic | |
type Attribute (BasicAuth' 'Optional scheme m e a) Request Source # | |
Defined in WebGear.Core.Trait.Auth.Basic | |
type Attribute (BasicAuth' 'Required scheme m e a) Request Source # | |
Defined in WebGear.Core.Trait.Auth.Basic | |
type Prerequisite (BasicAuth' x scheme m e a) ts Request Source # | |
Defined in WebGear.Core.Trait.Auth.Basic |
type BasicAuth = BasicAuth' Required "Basic" Source #
Trait for HTTP basic authentication with the Basic scheme.
The protection space for authentication
Username for basic authentication. Valid usernames cannot contain ':' characters.
Password for basic authentication.
data Credentials Source #
Basic authentication credentials retrieved from an HTTP request
Instances
Read Credentials Source # | |
Defined in WebGear.Core.Trait.Auth.Basic readsPrec :: Int -> ReadS Credentials # readList :: ReadS [Credentials] # readPrec :: ReadPrec Credentials # readListPrec :: ReadPrec [Credentials] # | |
Show Credentials Source # | |
Defined in WebGear.Core.Trait.Auth.Basic showsPrec :: Int -> Credentials -> ShowS # show :: Credentials -> String # showList :: [Credentials] -> ShowS # | |
Eq Credentials Source # | |
Defined in WebGear.Core.Trait.Auth.Basic (==) :: Credentials -> Credentials -> Bool # (/=) :: Credentials -> Credentials -> Bool # | |
Ord Credentials Source # | |
Defined in WebGear.Core.Trait.Auth.Basic 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
Instances
Read e => Read (BasicAuthError e) Source # | |
Defined in WebGear.Core.Trait.Auth.Basic readsPrec :: Int -> ReadS (BasicAuthError e) # readList :: ReadS [BasicAuthError e] # readPrec :: ReadPrec (BasicAuthError e) # readListPrec :: ReadPrec [BasicAuthError e] # | |
Show e => Show (BasicAuthError e) Source # | |
Defined in WebGear.Core.Trait.Auth.Basic showsPrec :: Int -> BasicAuthError e -> ShowS # show :: BasicAuthError e -> String # showList :: [BasicAuthError e] -> ShowS # | |
Eq e => Eq (BasicAuthError e) Source # | |
Defined in WebGear.Core.Trait.Auth.Basic (==) :: BasicAuthError e -> BasicAuthError e -> Bool # (/=) :: BasicAuthError e -> BasicAuthError e -> Bool # |
:: forall m e t h ts. (ArrowChoice h, Get h (BasicAuth' Required "Basic" m e t) Request, 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.
:: forall scheme m e t h ts. (ArrowChoice h, Get h (BasicAuth' Required scheme m e t) Request, 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
:: forall m e t h ts. (ArrowChoice h, Get h (BasicAuth' Optional "Basic" m e t) Request, 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
so that the handler can process the
authentication error appropriately.Either
(BasicAuthError
e) t
:: forall scheme m e t h ts. (ArrowChoice h, Get h (BasicAuth' Optional scheme m e t) Request, 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