bzrlib.transport.http._urllib2_wrappers.AbstractAuthHandler : API documentation

A custom abstract authentication handler for all http authentications.

Provides the meat to handle authentication errors and preventively set authentication headers after the first successful authentication.

This can be used for http and proxy, as well as for basic, negotiate and digest authentications.

This provides an unified interface for all authentication handlers (urllib2 provides far too many with different policies).

The interaction between this handler and the urllib2 framework is not obvious, it works as follow:

opener.open(request) is called:

that may trigger http_request which will add an authentication header (self.build_header) if enough info is available.
the request is sent to the server,
if an authentication error is received self.auth_required is called, we acquire the authentication info in the error headers and call self.auth_match to check that we are able to try the authentication and complete the authentication parameters,
we call parent.open(request), that may trigger http_request and will add a header (self.build_header), but here we have all the required info (keep in mind that the request and authentication used in the recursive calls are really (and must be) the same objects).
if the call returns a response, the authentication have been successful and the request authentication parameters have been updated.

Method	__init__	Undocumented
Method	update_auth	Update a value in auth marking the auth as modified if needed
Method	auth_required	Retry the request if the auth scheme is ours.
Method	add_auth_header	Add the authentication header to the request
Method	auth_match	Check that we are able to handle that authentication scheme.
Method	build_auth_header	Build the value of the header used to authenticate.
Method	auth_successful	The authentification was successful for the request.
Method	get_user_password	Ask user for a password if none is already available.
Method	http_request	Insert an authentication header if information is available
Method	_parse_auth_header	Parse the authentication header.
Method	_build_password_prompt	Build a prompt taking the protocol used into account.
Method	_build_username_prompt	Build a prompt taking the protocol used into account.

def auth_match(self, header, auth):

overridden in bzrlib.transport.http._urllib2_wrappers.BasicAuthHandler, bzrlib.transport.http._urllib2_wrappers.DigestAuthHandler, bzrlib.transport.http._urllib2_wrappers.NegotiateAuthHandler

Check that we are able to handle that authentication scheme.

The request authentication parameters may need to be updated with info from the server. Some of these parameters, when combined, are considered to be the authentication key, if one of them change the authentication result may change. 'user' and 'password' are exampls, but some auth schemes may have others (digest's nonce is an example, digest's nonce_count is a counter-example). Such parameters must be updated by using the update_auth() method.

Parameters	header	The authentication header sent by the server.
	auth	The auth parameters already known. They may be updated.
Returns	True if we can try to handle the authentication.

def build_auth_header(self, auth, request):

overridden in bzrlib.transport.http._urllib2_wrappers.BasicAuthHandler, bzrlib.transport.http._urllib2_wrappers.DigestAuthHandler, bzrlib.transport.http._urllib2_wrappers.NegotiateAuthHandler

Build the value of the header used to authenticate.

Parameters	auth	The auth parameters needed to build the header.
	request	The request needing authentication.
Returns	None or header.

def auth_successful(self, request, response):

The authentification was successful for the request.

Additional infos may be available in the response.

Parameters	request	The succesfully authenticated request.
	response	The server response (may contain auth info).

def _build_password_prompt(self, auth):

Build a prompt taking the protocol used into account.

The AuthHandler is used by http and https, we want that information in the prompt, so we build the prompt from the authentication dict which contains all the needed parts.

Also, http and proxy AuthHandlers present different prompts to the user. The daughter classes should implements a public build_password_prompt using this method.

def _build_username_prompt(self, auth):

Build a prompt taking the protocol used into account.

The AuthHandler is used by http and https, we want that information in the prompt, so we build the prompt from the authentication dict which contains all the needed parts.

Also, http and proxy AuthHandlers present different prompts to the user. The daughter classes should implements a public build_username_prompt using this method.

Parameters	server_header	The value of the header sent by the server describing the authenticaion request.
Returns	A tuple (scheme, remainder) scheme being the first word in the given header (lower cased), remainder may be None.

b.t.h._.AbstractAuthHandler(urllib2.BaseHandler) : class documentation