Authl instance acts as the initial coordinator between the
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.
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.
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 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).
Provides a list of all of the registered handlers.
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.
- 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
Disposition represents the result of a phase of an authentication
transaction, and tells the top-level application what to do next.
Base class for all response dispositions.
Error(message, redir: str)¶
Indicates that authorization failed.
- message (str) – The error message to display
- redir (str) – The original redirection target of the auth attempt, if available
NeedsPost(url: str, message, data: dict)¶
Indicates that the callback needs to be re-triggered as a POST request.
- 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
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
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
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.
- 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
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,
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.
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.
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.
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.
- 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
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