djblets.webapi.auth.backends.base¶

The base class for an API authentication backend.

WebAPIAuthenticateResult¶

A type alias for authentication results.

This was the only return value supported prior to Djblets 3.2.

Contents are in the form of:

Tuple:

0 (bool) – Whether the authentication request was successful.
1 (str) – The error message to return if authentication failed.

This can be None if it succeeded, or if it failed and the default error from LOGIN_FAILED should be used.
2 (dict) – Any HTTP headers to return in the response.

This can be None if no headers need to be returned, or if it failed and default headers from LOGIN_FAILED should be used.

New in version 3.2.

alias of Tuple[bool, Optional[str], Optional[Dict[str, str]]]

WebAPICredentials¶

A type alias for credentials passed to or from auth handlers.

New in version 3.2.

alias of Dict[str, Any]

WebAPIGetCredentialsResult¶

A type alias for the result of a get_credentials response.

New in version 3.2.

alias of Optional[Union[Tuple[bool, Optional[str], Optional[Dict[str, str]]], Dict[str, Any]]]

class WebAPIAuthBackend[source]¶

Bases: object

Handles a form of authentication for the web API.

This can be overridden to provide custom forms of authentication, or to support multiple types of authentication.

More than one authentication backend can be used with the web API. In that case, the client can make the determination about which to use.

Auth backends generally need to only override the get_credentials() method, though more specialized ones may override other methods as well.

They must also provide www_auth_scheme which is a WWW-Authenticate scheme value.

www_auth_scheme: Optional[str] = None¶

The auth scheme used in the WWW-Authenticate header.

Type:: str

A regex of sensitive entries in the credentials dictionary.

By default, this excludes keys containing “api”, “token”, “key”, “secret”, “password”, or “signature” anywhere in the name, in any casing.

This can be extended for other sensitive information.

get_auth_headers(request: HttpRequest) → Dict[str, Any][source]¶

Return extra authentication headers for the response.

Parameters:: request (django.http.HttpRequest) – The HTTP request from the client.
Returns:: The authentication headers (defaults to empty).
Return type:: dict

authenticate(request: HttpRequest, **kwargs) → Optional[Tuple[bool, Optional[str], Optional[Dict[str, str]]]][source]¶

Authenticate a request against this auth backend.

This will fetch the credentials and attempt an authentication against those credentials.

This function must return None to indicate it should be skipped and another backend should be tried, or a tuple indicating the success/failure and additional details for the client.

Parameters:

request (django.http.HttpRequest) – The HTTP request from the client.

Returns:

See WebAPIAuthenticateResult for details on the format for the returned type value.

If the backend should be skipped, this will return None.

Return type:

tuple or None

get_credentials(request: HttpRequest) → Optional[Union[Tuple[bool, Optional[str], Optional[Dict[str, str]]], Dict[str, Any]]][source]¶

Return credentials provided in the request.

This returns a dictionary of all credentials necessary for this auth backend. By default, this expects username and password, though more specialized auth backends may provide other information. These credentials will be passed to login_with_credentials().

This function must be implemented by the subclass.

Parameters:: request (django.http.HttpRequest) – The HTTP request from the client.
Returns:: A dictionary of credential information.
Return type:: dict

login_with_credentials(request: HttpRequest, **credentials) → Tuple[bool, Optional[str], Optional[Dict[str, str]]][source]¶

This takes the provided credentials from the request (as returned by get_credentials()) and attempts a login against the main authentication backends used by Django.

Parameters:

request (django.http.HttpRequest) – The HTTP request from the client.
credentials (dict) – All credentials provided by get_credentials().

Returns:

See the return type in authenticate().

Return type:

tuple or None

validate_credentials(request: HttpRequest, **credentials) → Optional[Tuple[bool, Optional[str], Optional[Dict[str, str]]]][source]¶

Validate that credentials are valid.

This is called before we attempt to authenticate with the credentials, and can short-circuit the rest of the authentication process, returning a result tuple if desired. If None is returned, authentication proceeds as normal.

By default, this will attempt to bypass authentication if the current user is already logged in and matches the authenticated user (if and only if username appears in the credentials).

Subclasses can override this to provide more specific behavior for their sets of credentials, or to disable this entirely.

Parameters:

request (django.http.HttpRequest) – The HTTP request from the client.
credentials (dict) – All credentials provided by get_credentials().

Returns:

See the return type in authenticate().

Return type:

tuple or None

clean_credentials_for_display(credentials: Dict[str, Any]) → Dict[str, Any][source]¶

Clean up a credentials dictionary, removing sensitive information.

This will take a credentials dictionary and mask anything sensitive, preparing it for output to a log file.

Parameters:: credentials (dict) – A dictionary of credentials provided for authentication.
Returns:: A sanitized dictionary of credentials, for display purposes.
Return type:: dict

__annotations__ = {'www_auth_scheme': 'Optional[str]'}¶