Soup.AuthDomain¶

Subclasses:: Soup.AuthDomainBasic, Soup.AuthDomainDigest

Methods¶

Inherited:: GObject.Object (37)
Structs:: GObject.ObjectClass (5)

	`accepts` (msg)
	`add_path` (path)
	`challenge` (msg)
	`check_password` (msg, username, password)
	`covers` (msg)
	`get_realm` ()
	`remove_path` (path)
	`set_filter` (filter, *filter_data)
	`set_generic_auth_callback` (auth_callback, *auth_data)

Virtual Methods¶

Inherited:: GObject.Object (7)

	`do_accepts` (msg, header)
	`do_challenge` (msg)
	`do_check_password` (msg, username, password)

Properties¶

Name	Type	Flags	Short Description
`filter`	`int`	r/w	A filter for deciding whether or not to require authentication
`filter-data`	`int`	r/w	Data to pass to filter
`generic-auth-callback`	`int`	r/w	An authentication callback that can be used with any `Soup.AuthDomain` subclass
`generic-auth-data`	`int`	r/w	Data to pass to auth callback
`proxy`	`bool`	r/w/co	Whether or not this is a proxy auth domain
`realm`	`str`	r/w/co	The realm of this auth domain

Signals¶

Inherited:: GObject.Object (1)

Fields¶

Inherited:: GObject.Object (1)

Name	Type	Access	Description
parent_instance	`GObject.Object`	r

Class Details¶

class Soup.AuthDomain(**kwargs)¶

Bases:: GObject.Object
Abstract:: Yes
Structure:: Soup.AuthDomainClass

Server-side authentication.

A Soup.AuthDomain manages authentication for all or part of a [class`Server`]. To make a server require authentication, first create an appropriate subclass of Soup.AuthDomain, and then add it to the server with [method`Server`.add_auth_domain].

In order for an auth domain to have any effect, you must add one or more paths to it (via [method`AuthDomain`.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 ([method`AuthDomain`.set_filter] to bypass authentication for those requests that don’t need it.

accepts(msg)¶

Parameters:: msg (Soup.ServerMessage) – a Soup.ServerMessage
Returns:: the username that msg has authenticated as, if in fact it has authenticated. None otherwise.
Return type:: str or None

Checks if msg contains appropriate authorization for self to accept it.

Mirroring [method`AuthDomain`.covers], this does not check whether or not self *cares* if msg is authorized.

This is used by [class`Server`] internally and is probably of no use to anyone else.

add_path(path)¶

Parameters:: path (str) – the path to add to self

Adds path to self.

Requests under path on self's server will require authentication (unless overridden by [method`AuthDomain`.remove_path] or [method`AuthDomain`.set_filter]).

challenge(msg)¶

Parameters:: msg (Soup.ServerMessage) – a Soup.ServerMessage

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 [class`Server`] internally and is probably of no use to anyone else.

check_password(msg, username, password)¶

Parameters:

msg (Soup.ServerMessage) – a Soup.ServerMessage
username (str) – a username
password (str) – a password

Returns:

whether or not the message is authenticated

Return type:

bool

Checks if msg authenticates to self via username and password.

This would normally be called from a [callback`AuthDomainGenericAuthCallback`].

covers(msg)¶

Parameters:: msg (Soup.ServerMessage) – a Soup.ServerMessage
Returns:: True if self requires msg to be authenticated
Return type:: bool

Checks if self 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 [class`Server`] internally and is probably of no use to anyone else.

get_realm()¶

Returns:: self's realm
Return type:: str

Gets the realm name associated with self.

remove_path(path)¶

Parameters:: path (str) – the path to remove from self

Removes path from self.

Requests under path on self's server will NOT require authentication.

This is not simply an undo-er for [method`AuthDomain`.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 [method`AuthDomain`.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.

set_filter(filter, *filter_data)¶

Parameters:

filter (Soup.AuthDomainFilter) – the auth filter for self
filter_data (object or None) – data to pass to filter

Adds filter as an authentication filter to self.

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 Soup.AuthDomain :filter and [property`AuthDomain`:py:data::filter-data<Soup.AuthDomain.props.filter_data> properties], which can also be used to set the filter at construct time.

set_generic_auth_callback(auth_callback, *auth_data)¶

Parameters:

auth_callback (Soup.AuthDomainGenericAuthCallback) – the auth callback
auth_data (object or None) – data to pass to auth_callback

Sets auth_callback as an authentication-handling callback for self.

Whenever a request comes in to self which cannot be authenticated via a domain-specific auth callback (eg, [callback`AuthDomainDigestAuthCallback`]), the generic auth callback will be invoked. See [callback`AuthDomainGenericAuthCallback`] for information on what the callback should do.

do_accepts(msg, header) virtual¶

Parameters:

msg (Soup.ServerMessage) –
header (str) –

Return type:

str

do_challenge(msg) virtual¶

Parameters:: msg (Soup.ServerMessage) – a Soup.ServerMessage
Return type:: str

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 [class`Server`] internally and is probably of no use to anyone else.

do_check_password(msg, username, password) virtual¶

Parameters:

msg (Soup.ServerMessage) – a Soup.ServerMessage
username (str) – a username
password (str) – a password

Returns:

whether or not the message is authenticated

Return type:

bool

Checks if msg authenticates to domain via username and password.

This would normally be called from a [callback`AuthDomainGenericAuthCallback`].

Property Details¶

Soup.AuthDomain.props.filter¶

Name:: filter
Type:: int
Default Value:: None
Flags:: READABLE, WRITABLE

The [callback`AuthDomainFilter`] for the domain.

Soup.AuthDomain.props.filter_data¶

Name:: filter-data
Type:: int
Default Value:: None
Flags:: READABLE, WRITABLE

Data to pass to the [callback`AuthDomainFilter`].

Soup.AuthDomain.props.generic_auth_callback¶

Name:: generic-auth-callback
Type:: int
Default Value:: None
Flags:: READABLE, WRITABLE

The [callback`AuthDomainGenericAuthCallback`].

Soup.AuthDomain.props.generic_auth_data¶

Name:: generic-auth-data
Type:: int
Default Value:: None
Flags:: READABLE, WRITABLE

The data to pass to the [callback`AuthDomainGenericAuthCallback`].

Soup.AuthDomain.props.proxy¶

Name:: proxy
Type:: bool
Default Value:: False
Flags:: READABLE, WRITABLE, CONSTRUCT_ONLY

Whether or not this is a proxy auth domain.

Soup.AuthDomain.props.realm¶

Name:: realm
Type:: str
Default Value:: None
Flags:: READABLE, WRITABLE, CONSTRUCT_ONLY

The realm of this auth domain.