AuthDomain

class AuthDomain(**properties: Any)

Superclasses: Object

Subclasses: AuthDomainBasic, AuthDomainDigest

Server-side authentication.

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

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

Methods

class AuthDomain

accepts(msg: ServerMessage) → str | None

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

Mirroring covers, this does not check whether or not domain cares if msg is authorized.

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

Parameters:

msg – a ServerMessage

add_path(path: str) → None

Adds path to domain.

Requests under path on domain’s server will require authentication (unless overridden by remove_path or set_filter).

Parameters:

path – the path to add to domain

challenge(msg: ServerMessage) → None

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

Parameters:

msg – a ServerMessage

check_password(msg: ServerMessage, username: str, password: str) → bool

Checks if msg authenticates to domain via username and password.

This would normally be called from a AuthDomainGenericAuthCallback.

Parameters:

• msg – a ServerMessage

• username – a username

• password – a password

covers(msg: ServerMessage) → bool

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

Parameters:

msg – a ServerMessage

get_realm() → str

Gets the realm name associated with domain.

remove_path(path: str) → None

Removes path from domain.

Requests under path on domain’s server will NOT require authentication.

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

Parameters:

path – the path to remove from domain

set_filter(filter: Callable[[...], bool], *filter_data: Any) → None

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 filter_data properties, which can also be used to set the filter at construct time.

Parameters:

• filter – the auth filter for domain

• filter_data – data to pass to filter

set_generic_auth_callback(auth_callback: Callable[[...], bool], *auth_data: Any) → None

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

Parameters:

• auth_callback – the auth callback

• auth_data – data to pass to auth_callback

Properties

class AuthDomain

props.filter: Callable[[...], bool]

The AuthDomainFilter for the domain.

props.filter_data: None

Data to pass to the AuthDomainFilter.

props.generic_auth_callback: Callable[[...], bool]

The AuthDomainGenericAuthCallback.

props.generic_auth_data: None

The data to pass to the AuthDomainGenericAuthCallback.

props.proxy: bool

Whether or not this is a proxy auth domain.

props.realm: str

The realm of this auth domain.

Virtual Methods

class AuthDomain

do_accepts(msg: ServerMessage, header: str) → str

Parameters:

• msg

• header

do_challenge(msg: ServerMessage) → 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 Server internally and is probably of no use to anyone else.

Parameters:

msg – a ServerMessage

do_check_password(msg: ServerMessage, username: str, password: str) → bool

Checks if msg authenticates to domain via username and password.

This would normally be called from a AuthDomainGenericAuthCallback.

Parameters:

• msg – a ServerMessage

• username – a username

• password – a password

Fields

class AuthDomain

parent_instance