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)
	`try_generic_auth_callback` (msg, username)

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
`add-path`	`str`	w	Add a path covered by this auth domain
`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
`remove-path`	`str`	w	Remove a path covered by this auth domain

Signals¶

Inherited:	GObject.Object (1)

Fields¶

Inherited:	GObject.Object (1)

Name	Type	Access	Description
parent	`GObject.Object`	r

Class Details¶

class Soup.AuthDomain(**kwargs)¶

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

accepts(msg)¶

Parameters:	msg (`Soup.Message`) – a `Soup.Message`
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 Soup.AuthDomain.covers(), this does not check whether or not self cares if msg is authorized.

This is used by Soup.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, such that requests under path on self’s server will require authentication (unless overridden by Soup.AuthDomain.remove_path() or Soup.AuthDomain.set_filter()).

You can also add paths by setting the Soup.AUTH_DOMAIN_ADD_PATH property, which can also be used to add one or more paths at construct time.

challenge(msg)¶

Parameters:	msg (`Soup.Message`) – a `Soup.Message`

Adds a “WWW-Authenticate” or “Proxy-Authenticate” header to msg, requesting that the client authenticate, and sets msg’s status accordingly.

This is used by Soup.Server internally and is probably of no use to anyone else.

check_password(msg, username, password)¶

Parameters:	msg (`Soup.Message`) – a `Soup.Message` 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 Soup.AuthDomainGenericAuthCallback.

covers(msg)¶

Parameters:	msg (`Soup.Message`) – a `Soup.Message`
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 Soup.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, such that requests under path on self’s server will NOT require authentication.

This is not simply an undo-er for Soup.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 Soup.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.

You can also remove paths by setting the Soup.AUTH_DOMAIN_REMOVE_PATH property, which can also be used to remove one or more paths at construct time.

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.AUTH_DOMAIN_FILTER and Soup.AUTH_DOMAIN_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, Soup.AuthDomainDigestAuthCallback), the generic auth callback will be invoked. See Soup.AuthDomainGenericAuthCallback for information on what the callback should do.

try_generic_auth_callback(msg, username)¶

Parameters:	msg (`Soup.Message`) – username (`str`) –
Return type:	`bool`

do_accepts(msg, header) virtual¶

Parameters:	msg (`Soup.Message`) – header (`str`) –
Return type:	`str`

do_challenge(msg) virtual¶

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

Adds a “WWW-Authenticate” or “Proxy-Authenticate” header to msg, requesting that the client authenticate, and sets msg’s status accordingly.

This is used by Soup.Server internally and is probably of no use to anyone else.

do_check_password(msg, username, password) virtual¶

Parameters:	msg (`Soup.Message`) – a `Soup.Message` 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 Soup.AuthDomainGenericAuthCallback.

Property Details¶

Soup.AuthDomain.props.add_path¶

Name:	`add-path`
Type:	`str`
Default Value:	`None`
Flags:	`WRITABLE`

Add a path covered by this auth domain

Soup.AuthDomain.props.filter¶

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

The Soup.AuthDomainFilter for the domain

Soup.AuthDomain.props.filter_data¶

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

Data to pass to filter

Soup.AuthDomain.props.generic_auth_callback¶

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

The Soup.AuthDomainGenericAuthCallback for the domain

Soup.AuthDomain.props.generic_auth_data¶

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

Data to pass to auth callback

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

Soup.AuthDomain.props.remove_path¶

Name:	`remove-path`
Type:	`str`
Default Value:	`None`
Flags:	`WRITABLE`

Remove a path covered by this auth domain