API Documentation

Authl instance

An Authl instance acts as the initial coordinator between the configured handler.Handler instances; given an identity address (such as an email address, WebFinger address, or Internet URL) it looks up the appropriate handler to use to initiate the login transaction, and it will also look up the handler for a transaction in progress.

class authl.Authl(cfg_handlers: Optional[List[authl.handlers.Handler]] = None)

The authentication wrapper instance.

Parameters:cfg_handlers – The list of configured handlers, in decreasing priority order.

Initialize an Authl library instance.

add_handler(handler: authl.handlers.Handler)

Adds another handler to the configured handler list at the lowest priority.

check_profiles(profiles) → Tuple[Optional[authl.handlers.Handler], str, str]

Given a list of profile URLs, check them for a handle-able identity

get_handler_by_id(handler_id)

Get the handler with the given ID, for a transaction in progress.

get_handler_for_url(url: str) → Tuple[Optional[authl.handlers.Handler], str, str]

Get the appropriate handler for the specified identity address. If more than one handler knows how to handle an address, it will use the one with the highest priority.

Parameters:url (str) – The identity address; typically a URL but can also be a WebFinger or email address.
Returns:a tuple of (handler, hander_id, profile_url).
handlers

Provides a list of all of the registered handlers.

authl.from_config(config: Dict[str, Any], state_storage: Optional[dict] = None, token_storage: Optional[authl.tokens.TokenStore] = None) → authl.Authl

Generate an Authl handler set from provided configuration directives.

Parameters:
  • config (dict) – a configuration dictionary. See the individual handlers’ from_config functions to see possible configuration values.
  • state_storage (dict) – a dict-like object that will store session state for methods that need it. Defaults to an instance-local ExpiringDict; this will not work well in load-balanced scenarios. This can be safely stored in a user session, if available.
  • token_storage (tokens.TokenStore) – a TokenStore for storing session state for methods that need it. Defaults to an instance-local DictStore backed by an ExpiringDict; this will not work well in load-balanced scenarios.

Handlers will be enabled based on truthy values of the following keys:

For additional configuration settings, see each handler’s respective from_config().

Dispositions

A Disposition represents the result of a phase of an authentication transaction, and tells the top-level application what to do next.

class authl.disposition.Disposition

Base class for all response dispositions.

class authl.disposition.Error(message, redir: str)

Indicates that authorization failed.

Parameters:
  • message (str) – The error message to display
  • redir (str) – The original redirection target of the auth attempt, if available
class authl.disposition.NeedsPost(url: str, message, data: dict)

Indicates that the callback needs to be re-triggered as a POST request.

Parameters:
  • url (str) – The URL that needs to be POSTed to
  • message (str) – A user-friendly message to display
  • data (dict) – POST data to be sent in the request, as key-value pairs
class authl.disposition.Notify(cdata)

Indicates that a notification should be sent to the user to take an external action, such as checking email or waiting for a text message or the like.

The actual notification client data is to be configured in the underlying handler by the application, and will typically be a string.

Parameters:cdata – Notification client data
class authl.disposition.Redirect(url: str)

Indicates that the authenticating user should be redirected to another URL for the next step.

Parameters:url (str) – The URL to redirect the user to
class authl.disposition.Verified(identity: str, redir: str, profile: Optional[dict] = None)

Indicates that the user is now verified; it is now up to the application to add that authorization to the user session and redirect the client to the actual view.

Parameters:
  • identity (str) – The verified identity URL
  • redir (str) – Where to redirect the user to
  • profile (dict) –

    The user’s profile information. Standardized keys:

    • avatar: A URL to the user’s avatar image
    • bio: Brief biographical information
    • homepage: The user’s personal homepage
    • location: The user’s stated location
    • name: The user’s display/familiar name
    • pronouns: The user’s declared pronouns
    • profile_url: A human-readable URL to link to the user’s service-specific profile (which may or may not be the same as their identity URL).
    • endpoints: A dictionary of key-value pairs referring to the user’s various integration services

Token storage

The provided implementations are intended merely as a starting point that works for the most common cases with minimal external dependencies. In general, if you’re only running a service on a single endpoint, use DictStore, and if you want to be able to load-balance, use Serializer. However, it is quite reasonable to provide your own implementation of TokenStore which is backed by a shared data store such as Redis or a database.

class authl.tokens.TokenStore

Storage for tokens; given some data to store, returns an opaque identifier that can be used to reconstitute said token.

put(value: Any) → str

Generates a token with the specified stored values.

Parameters:value – The token value to store
Returns:The stored token’s ID
get(key: str, to_type=<class 'tuple'>) → Any

Retrieves the token’s value; raises KeyError if the token does not exist or is invalid.

remove(key: str)

Removes the key from the backing store, if appropriate. Is a no-op if the key doesn’t exist (or if there’s no backing store).

pop(key: str, to_type=<class 'tuple'>) → Any

Retrieves the token’s values, and deletes the token from the backing store. Even if the value retrieval fails, it will be removed.

class authl.tokens.DictStore(store: Optional[dict] = None, keygen: Callable[[...], str] = <function DictStore.<lambda>>)

A token store that stores the values in a dict-like container.

This is suitable for the general case of having a single persistent service running on a single endpoint.

Parameters:
  • store – dict-like class that maps the generated key to the stored value. Defaults to an expiringdict with a size limit of 1024 and a maximum lifetime of 1 hour. This can be tuned to your needs. In particular, the lifetime never needs to be any higher than your longest allowed transaction lifetime, and the size limit generally needs to be no more than the number of concurrent logins at any given time.
  • keygen (func) – A function to generate a non-colliding string key for the stored token. This defaults to py:func:uuid.uuid4.

Initialize the store

class authl.tokens.Serializer(secret_key)

A token store that stores the token values within the token name, using a tamper-resistant signed serializer. Use this to avoid having a backing store entirely, although the tokens can get quite large.

This is suitable for situations where you are load-balancing across multiple nodes, or need tokens to persist across frequent service restarts, and don’t want to be dependent on a database. Note that all running instances will need to share the same secret_key.

Also note that tokens stored in this way cannot be revoked individually.

Additionally, this token storage mechanism may limit the security of some of the identity providers.

Initializes the token store

Parameters:secret_key (str) – The signing key for the serializer