Flask wrapper

AuthlFlask is an easy-to-use wrapper for use with Flask . By default it gives you a login form (with optional URL tester) and a login endpoint that stores the verified identity in flask.session['me']. All this behavior is configurable.

The basic usage is very simple:

import flask
import authl.flask

app = flask.Flask(__name__)
app.secret_key = "extremely secret"

authl.flask.setup(app, {
    # Simple IndieAuth setup
    'INDIEAUTH_CLIENT_ID': authl.flask.client_id,

    # Minimal Fediverse setup
    'FEDIVERSE_NAME': 'My website',

    # Send email using localhost
    'EMAIL_FROM': 'me@example.com',
    'SMTP_HOST': 'localhost',
    'SMTP_PORT': 25
}, tester_path='/test')

    if 'me' in flask.session:
        return 'Hello {me}. Want to <a href="{logout}">log out</a>?'.format(
            me=flask.session['me'], logout=flask.url_for(
                'logout', redir=flask.request.path[1:])

    return 'You are not logged in. Want to <a href="{login}">log in</a>?'.format(
        login=flask.url_for('authl.login', redir=flask.request.path[1:]))

def logout():
    return flask.redirect('/')

This gives you a very simple login form configured to work with IndieAuth, Fediverse, and email at the default location of /login, and a logout mechanism at /logout. The endpoint at /test can be used to test an identity URL for login support.

class authl.flask.AuthlFlask(app: flask.app.Flask, config: Dict[str, Any], login_name: str = 'authl.login', login_path: str = '/login', callback_name: str = 'authl.callback', callback_path: str = '/cb', tester_name: str = 'authl.test', tester_path: str = None, login_render_func: Callable = None, notify_render_func: Callable = None, session_auth_name: Optional[str] = 'me', force_https: bool = False, stylesheet: Union[str, Callable] = None, on_verified: Callable = None, make_permanent: bool = True, state_storage: Dict[KT, VT] = None, token_storage: authl.tokens.TokenStore = None, session_namespace='_authl')

Easy Authl wrapper for use with a Flask application.

  • app (flask.Flask) – the application to attach to
  • config (dict) – Configuration directives for Authl’s handlers. See from_config for more information.
  • login_name (str) – The endpoint name for the login handler, for flask.url_for()
  • login_path (str) –

    The mount point of the login endpoint

    The login endpoint takes the following arguments (as specified via flask.url_for()):

    • me: The URL to initiate authentication for
    • redir: Where to redirect the user to after successful login
  • callback_name (str) – The endpoint name for the callback handler, for flask.url_for()
  • callback_path (str) – The mount point of the callback handler endpoint
  • tester_name (str) – The endpoint name for the URL tester, for flask.url_for()
  • tester_path (str) –

    The mount point of the URL tester endpoint

    The URL tester endpoint takes a query parameter of url which is the URL to check. It returns a JSON object that describes the detected handler (if any), with the following attributes:

    • name: the service name
    • url: a canonicized version of the URL

    The URL tester endpoint will only be mounted if tester_path is specified. This will also enable a small asynchronous preview in the default login form.

  • login_render_func (function) –

    The function to call to render the login page; if not specified a default will be provided.

    This function takes the following arguments; note that more may be added so it should also take a **kwargs for future compatibility:

    • auth: the authl.Authl object
    • login_url: the URL to use for the login form
    • tester_url: the URL to use for the test callback
    • redir: The redirection destination that the login URL will
      redirect them to
    • id_url: Any pre-filled value for the ID url
    • error: Any error message that occurred

    If login_render_func returns a falsy value, the default login form will be used instead. This is useful for providing a conditional override, or as a rudimentary hook for analytics on the login flow or the like.

  • notify_render_func (function) –

    The function to call to render the user notification page; if not specified a default will be provided.

    This function takes the following arguments:

    • cdata: the client data for the handler
  • session_auth_name (str) – The session parameter to use for the authenticated user. Set to None if you want to use your own session management.
  • force_https (bool) – Whether to force authentication to switch to a https:// connection
  • stylesheet (str) – the URL to use for the default page stylesheet; if not
  • on_verified (function) –

    A function to call on successful login (called after setting the session value)

    This function receives the disposition.Verified object, and may return a Flask response of its own, which should ideally be a flask.redirect(). This can be used to capture more information about the user (such as filling out a user profile) or to redirect certain users to an administrative screen of some sort.

  • make_permanent (bool) – Whether a session should persist past the browser window closing
  • token_storage (tokens.TokenStore) –

    Storage for token data for methods which use it. Uses the same default as authl.from_config().

    Note that if the default is used, the app.secret_key MUST be set before this class is initialized.

  • state_storage – The mechanism to use for transactional state storage for login methods that need it. Defaults to using the Flask user session.
  • session_namespace – A namespace for Authl to keep a small amount of user session data in. Should never need to be changed.
render_login_form(destination: str, error: Optional[str] = None)

Renders the login form. This might be called by the Flask app if, for example, a page requires login to be seen.

  • destination (str) – The redirection destination, as a full path (e.g. '/path/to/view')
  • error (str) – Any error message to display on the login form

The stylesheet to use for the Flask templates


Provide the _scheme parameter to be sent along to flask.url_for


A shim to generate a client ID based on the current site URL, for use with IndieAuth.

authl.flask.load_template(filename: str) → str

Load the built-in Flask template.

Parameters:filename (str) – The filename of the built-in template

Raises FileNotFoundError on no such template

Returns:the contents of the template.
authl.flask.setup(app: flask.app.Flask, config: Dict[str, Any], **kwargs) → authl.Authl

Simple setup function.

  • app (flask.flask) – The Flask app to configure with Authl.
  • config (dict) – Configuration values for the Authl instance; see authl.from_config()
  • kwargs – Additional arguments to pass along to the AuthlFlask constructor

The configured authl.Authl instance. Note that if you want the AuthlFlask instance you should instantiate that directly.