Soup.Auth¶

Subclasses:: Soup.AuthBasic, Soup.AuthDigest, Soup.AuthNTLM, Soup.AuthNegotiate

Methods¶

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

class	`new` (type, msg, auth_header)
	`authenticate` (username, password)
	`can_authenticate` ()
	`cancel` ()
	`get_authority` ()
	`get_authorization` (msg)
	`get_info` ()
	`get_protection_space` (source_uri)
	`get_realm` ()
	`get_scheme_name` ()
	`is_authenticated` ()
	`is_cancelled` ()
	`is_for_proxy` ()
	`is_ready` (msg)
	`update` (msg, auth_header)

Virtual Methods¶

Inherited:: GObject.Object (7)

	`do_authenticate` (username, password)
	`do_can_authenticate` ()
	`do_get_authorization` (msg)
	`do_get_protection_space` (source_uri)
	`do_is_authenticated` ()
	`do_is_ready` (msg)
	`do_update` (msg, auth_header)

Properties¶

Name	Type	Flags	Short Description
`authority`	`str`	r/w	Authentication authority
`is-authenticated`	`bool`	r	Whether or not the auth is authenticated
`is-cancelled`	`bool`	r	Whether or not the auth is cancelled
`is-for-proxy`	`bool`	r/w	Whether or not the auth is for a proxy server
`realm`	`str`	r/w	Authentication realm
`scheme-name`	`str`	r	Authentication scheme name

Signals¶

Inherited:: GObject.Object (1)

Fields¶

Inherited:: GObject.Object (1)

Name	Type	Access	Description
parent_instance	`GObject.Object`	r

Class Details¶

class Soup.Auth(**kwargs)¶

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

The abstract base class for handling authentication.

Specific HTTP Authentication mechanisms are implemented by its subclasses, but applications never need to be aware of the specific subclasses being used.

Soup.Auth objects store the authentication data associated with a given bit of web space. They are created automatically by [class`Session`].

classmethod new(type, msg, auth_header)¶

Parameters:

type (GObject.GType) – the type of auth to create (a subtype of Soup.Auth)
msg (Soup.Message) – the Soup.Message the auth is being created for
auth_header (str) – the WWW-Authenticate/Proxy-Authenticate header

Returns:

the new Soup.Auth, or None if it could not be created

Return type:

Soup.Auth or None

Creates a new Soup.Auth of type type with the information from msg and auth_header.

This is called by [class`Session`]; you will normally not create auths yourself.

authenticate(username, password)¶

Parameters:

username (str) – the username provided by the user or client
password (str) – the password provided by the user or client

Call this on an auth to authenticate it.

Normally this will cause the auth’s message to be requeued with the new authentication info.

can_authenticate()¶

Returns:: True if self is able to accept credentials.
Return type:: bool

Tests if self is able to authenticate by providing credentials to the [method`Auth`.authenticate].

cancel()¶

Call this on an auth to cancel it.

You need to cancel an auth to complete an asynchronous authenticate operation when no credentials are provided ([method`Auth`.authenticate] is not called). The Soup.Auth will be cancelled on dispose if it hans’t been authenticated.

get_authority()¶

Returns:: the authority
Return type:: str

Returns the authority (host:port) that self is associated with.

get_authorization(msg)¶

Parameters:: msg (Soup.Message) – the Soup.Message to be authorized
Returns:: the “Authorization” header, which must be freed.
Return type:: str

Generates an appropriate “Authorization” header for msg.

(The session will only call this if [method`Auth`.is_authenticated] returned True.)

get_info()¶

Returns:: the identifier
Return type:: str

Gets an opaque identifier for self.

The identifier can be used as a hash key or the like. Soup.Auth objects from the same server with the same identifier refer to the same authentication domain (eg, the URLs associated with them take the same usernames and passwords).

get_protection_space(source_uri)¶

Parameters:: source_uri (GLib.Uri) – the URI of the request that self was generated in response to.
Returns:: the list of paths, which can be freed with [method`Auth`.free_protection_space].
Return type:: [str]

Returns a list of paths on the server which self extends over.

(All subdirectories of these paths are also assumed to be part of self's protection space, unless otherwise discovered not to be.)

get_realm()¶

Returns:: the realm name
Return type:: str

Returns self's realm.

This is an identifier that distinguishes separate authentication spaces on a given server, and may be some string that is meaningful to the user. (Although it is probably not localized.)

get_scheme_name()¶

Returns:: the scheme name
Return type:: str

Soup.Auth.get_scheme_name: (attributes org.gtk.Method.get_property=scheme-name) Returns self's scheme name. (Eg, “Basic”, “Digest”, or “NTLM”)

is_authenticated()¶

Returns:: True if self has been given a username and password
Return type:: bool

Tests if self has been given a username and password.

is_cancelled()¶

Returns:: True if self has been cancelled
Return type:: bool

Tests if self has been cancelled

is_for_proxy()¶

Returns:: True or False
Return type:: bool

Tests whether or not self is associated with a proxy server rather than an “origin” server.

is_ready(msg)¶

Parameters:: msg (Soup.Message) – a Soup.Message
Returns:: True if self is ready to make a request with.
Return type:: bool

Tests if self is ready to make a request for msg with.

For most auths, this is equivalent to [method`Auth`.is_authenticated], but for some auth types (eg, NTLM), the auth may be sendable (eg, as an authentication request) even before it is authenticated.

update(msg, auth_header)¶

Parameters:

msg (Soup.Message) – the Soup.Message self is being updated for
auth_header (str) – the WWW-Authenticate/Proxy-Authenticate header

Returns:

True if self is still a valid (but potentially unauthenticated) Soup.Auth. False if something about auth_params could not be parsed or incorporated into self at all.

Return type:

bool

Updates self with the information from msg and auth_header, possibly un-authenticating it.

As with [ctor`Auth`.new], this is normally only used by [class`Session`].

do_authenticate(username, password) virtual¶

Parameters:

username (str) – the username provided by the user or client
password (str) – the password provided by the user or client

Call this on an auth to authenticate it.

Normally this will cause the auth’s message to be requeued with the new authentication info.

do_can_authenticate() virtual¶

Returns:: True if auth is able to accept credentials.
Return type:: bool

Tests if auth is able to authenticate by providing credentials to the [method`Auth`.authenticate].

do_get_authorization(msg) virtual¶

Parameters:: msg (Soup.Message) – the Soup.Message to be authorized
Returns:: the “Authorization” header, which must be freed.
Return type:: str

Generates an appropriate “Authorization” header for msg.

(The session will only call this if [method`Auth`.is_authenticated] returned True.)

do_get_protection_space(source_uri) virtual¶

Parameters:: source_uri (GLib.Uri) – the URI of the request that auth was generated in response to.
Returns:: the list of paths, which can be freed with [method`Auth`.free_protection_space].
Return type:: [str]

Returns a list of paths on the server which auth extends over.

(All subdirectories of these paths are also assumed to be part of auth's protection space, unless otherwise discovered not to be.)

do_is_authenticated() virtual¶

Returns:: True if auth has been given a username and password
Return type:: bool

Tests if auth has been given a username and password.

do_is_ready(msg) virtual¶

Parameters:: msg (Soup.Message) – a Soup.Message
Returns:: True if auth is ready to make a request with.
Return type:: bool

Tests if auth is ready to make a request for msg with.

For most auths, this is equivalent to [method`Auth`.is_authenticated], but for some auth types (eg, NTLM), the auth may be sendable (eg, as an authentication request) even before it is authenticated.

do_update(msg, auth_header) virtual¶

Parameters:

msg (Soup.Message) – the Soup.Message auth is being updated for
auth_header ({object: object}) – the WWW-Authenticate/Proxy-Authenticate header

Returns:

True if auth is still a valid (but potentially unauthenticated) Soup.Auth. False if something about auth_params could not be parsed or incorporated into auth at all.

Return type:

bool

Updates auth with the information from msg and auth_header, possibly un-authenticating it.

As with [ctor`Auth`.new], this is normally only used by [class`Session`].

Property Details¶

Soup.Auth.props.authority¶

Name:: authority
Type:: str
Default Value:: None
Flags:: READABLE, WRITABLE

The authority (host:port) being authenticated to.

Soup.Auth.props.is_authenticated¶

Name:: is-authenticated
Type:: bool
Default Value:: False
Flags:: READABLE

Whether or not the auth has been authenticated.

Soup.Auth.props.is_cancelled¶

Name:: is-cancelled
Type:: bool
Default Value:: False
Flags:: READABLE

Whether or not the auth has been cancelled.

Soup.Auth.props.is_for_proxy¶

Name:: is-for-proxy
Type:: bool
Default Value:: False
Flags:: READABLE, WRITABLE

Whether or not the auth is for a proxy server.

Soup.Auth.props.realm¶

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

The authentication realm.

Soup.Auth.props.scheme_name¶

Name:: scheme-name
Type:: str
Default Value:: None
Flags:: READABLE

The authentication scheme name.