Copyright | Will Thompson and Iñaki García Etxebarria |
---|---|
License | LGPL-2.1 |
Maintainer | Iñaki García Etxebarria |
Safe Haskell | Safe-Inferred |
Language | Haskell2010 |
Server-side authentication.
A AuthDomain
manages authentication for all or part of a
[classserver
]. To make a server require authentication, first create
an appropriate subclass of AuthDomain
, and then add it to the
server with [methodserver
.add_auth_domain].
In order for an auth domain to have any effect, you must add one or more
paths to it (via [methodauthDomain
.add_path]). To require authentication for
all ordinary requests, add the path "/"
. (Note that this does not include
the special "*"
URI (eg, "OPTIONS *"), which must be added as a separate
path if you want to cover it.)
If you need greater control over which requests should and shouldn't be
authenticated, add paths covering everything you *might* want authenticated,
and then use a filter ([methodauthDomain
.set_filter] to bypass
authentication for those requests that don't need it.
Synopsis
- newtype AuthDomain = AuthDomain (ManagedPtr AuthDomain)
- class (GObject o, IsDescendantOf AuthDomain o) => IsAuthDomain o
- toAuthDomain :: (MonadIO m, IsAuthDomain o) => o -> m AuthDomain
- authDomainAccepts :: (HasCallStack, MonadIO m, IsAuthDomain a, IsServerMessage b) => a -> b -> m (Maybe Text)
- authDomainAddPath :: (HasCallStack, MonadIO m, IsAuthDomain a) => a -> Text -> m ()
- authDomainChallenge :: (HasCallStack, MonadIO m, IsAuthDomain a, IsServerMessage b) => a -> b -> m ()
- authDomainCheckPassword :: (HasCallStack, MonadIO m, IsAuthDomain a, IsServerMessage b) => a -> b -> Text -> Text -> m Bool
- authDomainCovers :: (HasCallStack, MonadIO m, IsAuthDomain a, IsServerMessage b) => a -> b -> m Bool
- authDomainGetRealm :: (HasCallStack, MonadIO m, IsAuthDomain a) => a -> m Text
- authDomainRemovePath :: (HasCallStack, MonadIO m, IsAuthDomain a) => a -> Text -> m ()
- authDomainSetFilter :: (HasCallStack, MonadIO m, IsAuthDomain a) => a -> AuthDomainFilter -> m ()
- authDomainSetGenericAuthCallback :: (HasCallStack, MonadIO m, IsAuthDomain a) => a -> AuthDomainGenericAuthCallback -> m ()
- clearAuthDomainFilter :: (MonadIO m, IsAuthDomain o) => o -> m ()
- constructAuthDomainFilter :: (IsAuthDomain o, MonadIO m) => FunPtr C_AuthDomainFilter -> m (GValueConstruct o)
- getAuthDomainFilter :: (MonadIO m, IsAuthDomain o) => o -> m (Maybe AuthDomainFilter_WithClosures)
- setAuthDomainFilter :: (MonadIO m, IsAuthDomain o) => o -> FunPtr C_AuthDomainFilter -> m ()
- constructAuthDomainFilterData :: (IsAuthDomain o, MonadIO m) => Ptr () -> m (GValueConstruct o)
- getAuthDomainFilterData :: (MonadIO m, IsAuthDomain o) => o -> m (Ptr ())
- setAuthDomainFilterData :: (MonadIO m, IsAuthDomain o) => o -> Ptr () -> m ()
- clearAuthDomainGenericAuthCallback :: (MonadIO m, IsAuthDomain o) => o -> m ()
- constructAuthDomainGenericAuthCallback :: (IsAuthDomain o, MonadIO m) => FunPtr C_AuthDomainGenericAuthCallback -> m (GValueConstruct o)
- getAuthDomainGenericAuthCallback :: (MonadIO m, IsAuthDomain o) => o -> m (Maybe AuthDomainGenericAuthCallback_WithClosures)
- setAuthDomainGenericAuthCallback :: (MonadIO m, IsAuthDomain o) => o -> FunPtr C_AuthDomainGenericAuthCallback -> m ()
- constructAuthDomainGenericAuthData :: (IsAuthDomain o, MonadIO m) => Ptr () -> m (GValueConstruct o)
- getAuthDomainGenericAuthData :: (MonadIO m, IsAuthDomain o) => o -> m (Ptr ())
- setAuthDomainGenericAuthData :: (MonadIO m, IsAuthDomain o) => o -> Ptr () -> m ()
- constructAuthDomainProxy :: (IsAuthDomain o, MonadIO m) => Bool -> m (GValueConstruct o)
- getAuthDomainProxy :: (MonadIO m, IsAuthDomain o) => o -> m Bool
- constructAuthDomainRealm :: (IsAuthDomain o, MonadIO m) => Text -> m (GValueConstruct o)
- getAuthDomainRealm :: (MonadIO m, IsAuthDomain o) => o -> m Text
Exported types
newtype AuthDomain Source #
Memory-managed wrapper type.
AuthDomain (ManagedPtr AuthDomain) |
Instances
Eq AuthDomain Source # | |
Defined in GI.Soup.Objects.AuthDomain (==) :: AuthDomain -> AuthDomain -> Bool # (/=) :: AuthDomain -> AuthDomain -> Bool # | |
GObject AuthDomain Source # | |
Defined in GI.Soup.Objects.AuthDomain | |
ManagedPtrNewtype AuthDomain Source # | |
Defined in GI.Soup.Objects.AuthDomain toManagedPtr :: AuthDomain -> ManagedPtr AuthDomain | |
TypedObject AuthDomain Source # | |
Defined in GI.Soup.Objects.AuthDomain | |
HasParentTypes AuthDomain Source # | |
Defined in GI.Soup.Objects.AuthDomain | |
IsGValue (Maybe AuthDomain) Source # | Convert |
Defined in GI.Soup.Objects.AuthDomain gvalueGType_ :: IO GType gvalueSet_ :: Ptr GValue -> Maybe AuthDomain -> IO () gvalueGet_ :: Ptr GValue -> IO (Maybe AuthDomain) | |
type ParentTypes AuthDomain Source # | |
Defined in GI.Soup.Objects.AuthDomain type ParentTypes AuthDomain = '[Object] |
class (GObject o, IsDescendantOf AuthDomain o) => IsAuthDomain o Source #
Type class for types which can be safely cast to AuthDomain
, for instance with toAuthDomain
.
Instances
(GObject o, IsDescendantOf AuthDomain o) => IsAuthDomain o Source # | |
Defined in GI.Soup.Objects.AuthDomain |
toAuthDomain :: (MonadIO m, IsAuthDomain o) => o -> m AuthDomain Source #
Cast to AuthDomain
, for types for which this is known to be safe. For general casts, use castTo
.
Methods
Click to display all available methods, including inherited ones
Methods
accepts, addPath, bindProperty, bindPropertyFull, challenge, checkPassword, covers, forceFloating, freezeNotify, getv, isFloating, notify, notifyByPspec, ref, refSink, removePath, runDispose, stealData, stealQdata, thawNotify, unref, watchClosure.
Getters
getData, getProperty, getQdata, getRealm.
Setters
setData, setDataFull, setFilter, setGenericAuthCallback, setProperty.
accepts
:: (HasCallStack, MonadIO m, IsAuthDomain a, IsServerMessage b) | |
=> a |
|
-> b |
|
-> m (Maybe Text) | Returns: the username that |
Checks if msg
contains appropriate authorization for domain
to
accept it.
Mirroring [methodauthDomain
.covers], this does not check whether or not
domain
*cares* if msg
is authorized.
This is used by [classserver
] internally and is probably of no use to
anyone else.
addPath
:: (HasCallStack, MonadIO m, IsAuthDomain a) | |
=> a |
|
-> Text |
|
-> m () |
Adds path
to domain
.
Requests under path
on domain
's server will require authentication (unless
overridden by [methodauthDomain
.remove_path] or
[methodauthDomain
.set_filter]).
challenge
:: (HasCallStack, MonadIO m, IsAuthDomain a, IsServerMessage b) | |
=> a |
|
-> b |
|
-> m () |
Adds a "WWW-Authenticate" or "Proxy-Authenticate" header to msg
.
It requests that the client authenticate, and sets msg
's status accordingly.
This is used by [classserver
] internally and is probably of no use to
anyone else.
checkPassword
authDomainCheckPassword Source #
:: (HasCallStack, MonadIO m, IsAuthDomain a, IsServerMessage b) | |
=> a |
|
-> b |
|
-> Text |
|
-> Text |
|
-> m Bool | Returns: whether or not the message is authenticated |
Checks if msg
authenticates to domain
via username
and
password
.
This would normally be called from a
[callbackauthDomainGenericAuthCallback
].
covers
:: (HasCallStack, MonadIO m, IsAuthDomain a, IsServerMessage b) | |
=> a |
|
-> b |
|
-> m Bool | Returns: |
Checks if domain
requires msg
to be authenticated (according to
its paths and filter function).
This does not actually look at whether msg
*is* authenticated, merely
whether or not it needs to be.
This is used by [classserver
] internally and is probably of no use to
anyone else.
getRealm
:: (HasCallStack, MonadIO m, IsAuthDomain a) | |
=> a |
|
-> m Text | Returns: |
Gets the realm name associated with domain
.
removePath
:: (HasCallStack, MonadIO m, IsAuthDomain a) | |
=> a |
|
-> Text |
|
-> m () |
Removes path
from domain
.
Requests under path
on domain
's server will NOT require
authentication.
This is not simply an undo-er for [methodauthDomain
.add_path]; it
can be used to "carve out" a subtree that does not require
authentication inside a hierarchy that does. Note also that unlike
with [methodauthDomain
.add_path], this cannot be overridden by
adding a filter, as filters can only bypass authentication that
would otherwise be required, not require it where it would
otherwise be unnecessary.
setFilter
:: (HasCallStack, MonadIO m, IsAuthDomain a) | |
=> a |
|
-> AuthDomainFilter |
|
-> m () |
Adds filter
as an authentication filter to domain
.
The filter gets a chance to bypass authentication for certain requests that would otherwise require it. Eg, it might check the message's path in some way that is too complicated to do via the other methods, or it might check the message's method, and allow GETs but not PUTs.
The filter function returns True
if the request should still
require authentication, or False
if authentication is unnecessary
for this request.
To help prevent security holes, your filter should return True
by
default, and only return False
under specifically-tested
circumstances, rather than the other way around. Eg, in the example
above, where you want to authenticate PUTs but not GETs, you should
check if the method is GET and return False
in that case, and then
return True
for all other methods (rather than returning True
for
PUT and False
for all other methods). This way if it turned out
(now or later) that some paths supported additional methods besides
GET and PUT, those methods would default to being NOT allowed for
unauthenticated users.
You can also set the filter by setting the SoupAuthDomain:filter
and [propertyauthDomain
:filter-data properties], which can also be
used to set the filter at construct time.
setGenericAuthCallback
authDomainSetGenericAuthCallback Source #
:: (HasCallStack, MonadIO m, IsAuthDomain a) | |
=> a |
|
-> AuthDomainGenericAuthCallback |
|
-> m () |
Sets authCallback
as an authentication-handling callback for domain
.
Whenever a request comes in to domain
which cannot be authenticated via a
domain-specific auth callback (eg, [callbackauthDomainDigestAuthCallback
]),
the generic auth callback will be invoked. See
[callbackauthDomainGenericAuthCallback
] for information on what the callback
should do.
Properties
filter
The [callbackauthDomainFilter
] for the domain.
clearAuthDomainFilter :: (MonadIO m, IsAuthDomain o) => o -> m () Source #
Set the value of the “filter
” property to Nothing
.
When overloading is enabled, this is equivalent to
clear
#filter
constructAuthDomainFilter :: (IsAuthDomain o, MonadIO m) => FunPtr C_AuthDomainFilter -> m (GValueConstruct o) Source #
Construct a GValueConstruct
with valid value for the “filter
” property. This is rarely needed directly, but it is used by new
.
getAuthDomainFilter :: (MonadIO m, IsAuthDomain o) => o -> m (Maybe AuthDomainFilter_WithClosures) Source #
Get the value of the “filter
” property.
When overloading is enabled, this is equivalent to
get
authDomain #filter
setAuthDomainFilter :: (MonadIO m, IsAuthDomain o) => o -> FunPtr C_AuthDomainFilter -> m () Source #
Set the value of the “filter
” property.
When overloading is enabled, this is equivalent to
set
authDomain [ #filter:=
value ]
filterData
Data to pass to the [callbackauthDomainFilter
].
constructAuthDomainFilterData :: (IsAuthDomain o, MonadIO m) => Ptr () -> m (GValueConstruct o) Source #
Construct a GValueConstruct
with valid value for the “filter-data
” property. This is rarely needed directly, but it is used by new
.
getAuthDomainFilterData :: (MonadIO m, IsAuthDomain o) => o -> m (Ptr ()) Source #
Get the value of the “filter-data
” property.
When overloading is enabled, this is equivalent to
get
authDomain #filterData
setAuthDomainFilterData :: (MonadIO m, IsAuthDomain o) => o -> Ptr () -> m () Source #
Set the value of the “filter-data
” property.
When overloading is enabled, this is equivalent to
set
authDomain [ #filterData:=
value ]
genericAuthCallback
The [callbackauthDomainGenericAuthCallback
].
clearAuthDomainGenericAuthCallback :: (MonadIO m, IsAuthDomain o) => o -> m () Source #
Set the value of the “generic-auth-callback
” property to Nothing
.
When overloading is enabled, this is equivalent to
clear
#genericAuthCallback
constructAuthDomainGenericAuthCallback :: (IsAuthDomain o, MonadIO m) => FunPtr C_AuthDomainGenericAuthCallback -> m (GValueConstruct o) Source #
Construct a GValueConstruct
with valid value for the “generic-auth-callback
” property. This is rarely needed directly, but it is used by new
.
getAuthDomainGenericAuthCallback :: (MonadIO m, IsAuthDomain o) => o -> m (Maybe AuthDomainGenericAuthCallback_WithClosures) Source #
Get the value of the “generic-auth-callback
” property.
When overloading is enabled, this is equivalent to
get
authDomain #genericAuthCallback
setAuthDomainGenericAuthCallback :: (MonadIO m, IsAuthDomain o) => o -> FunPtr C_AuthDomainGenericAuthCallback -> m () Source #
Set the value of the “generic-auth-callback
” property.
When overloading is enabled, this is equivalent to
set
authDomain [ #genericAuthCallback:=
value ]
genericAuthData
The data to pass to the [callbackauthDomainGenericAuthCallback
].
constructAuthDomainGenericAuthData :: (IsAuthDomain o, MonadIO m) => Ptr () -> m (GValueConstruct o) Source #
Construct a GValueConstruct
with valid value for the “generic-auth-data
” property. This is rarely needed directly, but it is used by new
.
getAuthDomainGenericAuthData :: (MonadIO m, IsAuthDomain o) => o -> m (Ptr ()) Source #
Get the value of the “generic-auth-data
” property.
When overloading is enabled, this is equivalent to
get
authDomain #genericAuthData
setAuthDomainGenericAuthData :: (MonadIO m, IsAuthDomain o) => o -> Ptr () -> m () Source #
Set the value of the “generic-auth-data
” property.
When overloading is enabled, this is equivalent to
set
authDomain [ #genericAuthData:=
value ]
proxy
Whether or not this is a proxy auth domain.
constructAuthDomainProxy :: (IsAuthDomain o, MonadIO m) => Bool -> m (GValueConstruct o) Source #
Construct a GValueConstruct
with valid value for the “proxy
” property. This is rarely needed directly, but it is used by new
.
getAuthDomainProxy :: (MonadIO m, IsAuthDomain o) => o -> m Bool Source #
Get the value of the “proxy
” property.
When overloading is enabled, this is equivalent to
get
authDomain #proxy
realm
The realm of this auth domain.
constructAuthDomainRealm :: (IsAuthDomain o, MonadIO m) => Text -> m (GValueConstruct o) Source #
Construct a GValueConstruct
with valid value for the “realm
” property. This is rarely needed directly, but it is used by new
.
getAuthDomainRealm :: (MonadIO m, IsAuthDomain o) => o -> m Text Source #
Get the value of the “realm
” property.
When overloading is enabled, this is equivalent to
get
authDomain #realm