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