Getter

A “Getter” is an instance used by a backend to extract the authentication information from a falcon Request.

Getter

class falcon_auth2.Getter

Represents a class that extracts authentication information from a request.

Note

Subclasses that wish to only support the load_async() method are also required to override the load() method since it is defined as abstract. In these cases the sync version may just raise an exception.

async_calls_sync_load = None

Indicates if this Getter has an async load implementation that is not just a fallback to sync load() method, like the default load_async() method.

This property is automatically set by the Getter when a subclass is defined (using __init_subclass__) if not specified directly by a subclass (by setting it to a valued different than None).

abstract load(req: falcon.request.Request, *, challenges: Optional[Iterable[str]] = None) → str

Loads the specified attribute from the provided request.

If a getter cannot be used with the current request, a BackendNotApplicable is raised. The challenges, when provided, will be added to WWW-Authenticate header in case of error.

Parameters

req (Request) – The current request. This may be a wsgi or an asgi falcon request.

Keyword Arguments

challenges (Optional[Iterable[str]], optional) – One or more authentication challenges to use as the value of the WWW-Authenticate header in case of errors.

Returns

str – The loaded data, in case of success.

async load_async(req: falcon.request.Request, *, challenges: Optional[Iterable[str]] = None) → str

Async version of load(). The default implementation simply calls load(), but subclasses may override this implementation to provide an async version.

HeaderGetter

class falcon_auth2.HeaderGetter(header_key: str)

Returns the specified header from a request.

Parameters

header_key (str) – the name of the header to load.

load(req: falcon.request.Request, *, challenges: Optional[Iterable[str]] = None) → str

Loads the header from the provided request

AuthHeaderGetter

class falcon_auth2.AuthHeaderGetter(auth_header_type: str, *, header_key: str = 'Authorization')

Returns the auth header from a request, checking that it in the form <auth_header_type> value.

Parameters

auth_header_type (str) – The type of the auth header. Common values are "Basic", "Bearer".

Keyword Arguments

header_key (str, optional) – The name of the header to load. Defaults to "Authorization".

load(req: falcon.request.Request, *, challenges: Optional[Iterable[str]] = None) → str

Loads the auth header from the provided request

ParamGetter

class falcon_auth2.ParamGetter(param_name: str)

Returns the specified parameter from the request.

If the parameter appears multiple times an error will be raised.

Note

When the falcon Request option RequestOptions.auto_parse_form_urlencoded is set to True, this getter can also retrieve parameter in the body of a form-urlencoded request.

Parameters

param_name (str) – the name of the param to load.

load(req: falcon.request.Request, *, challenges: Optional[Iterable[str]] = None) → str

Loads the parameter from the provided request

CookieGetter

class falcon_auth2.CookieGetter(cookie_name: str)

Returns the specified cookie from the request.

If the cookie appears multiple times an error will be raised.

Parameters

cookie_name (str) – the name of the cookie to load.

load(req: falcon.request.Request, *, challenges: Optional[Iterable[str]] = None) → str

Loads the cookie from the provided request

MultiGetter

class falcon_auth2.MultiGetter(getters: Iterable[falcon_auth2.getter.Getter])

Combines multiple getters. This is useful if a value can be passed in multiple ways to the server, like using an header or a query parameter.

Will use the first value successfully returned, ignoring all BackendNotApplicable exceptions raised by the previously tried getters. If no getter can return a valid value an exception will only be raised.

Parameters

getters (Iterable[Getter]) – The getters to use. They will be tried in order and the first value successfully returned is used.

load(req: falcon.request.Request, *, challenges: Optional[Iterable[str]] = None) → str

Loads the value from the provided request using the provided getters

async load_async(req: falcon.request.Request, *, challenges: Optional[Iterable[str]] = None) → str

Async version of load().

Makes sure load is called inside a greenlet spawn context