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')
@app.route('/')
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:]))
@app.route('/logout')
def logout():
flask.session.clear()
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 = None, token_storage: authl.tokens.TokenStore = None, session_namespace='_authl')¶ Easy Authl wrapper for use with a Flask application.
Parameters: - 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 forredir
: 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 nameurl
: 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 objectlogin_url
: the URL to use for the login formtester_url
: the URL to use for the test callbackredir
: The redirection destination that the login URL will- redirect them to
id_url
: Any pre-filled value for the ID urlerror
: 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 aflask.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. Defaults to
tokens.Serializer
using the Flaskapp.secret_key
; this is suitable for load-balancing scenarios as long as all service nodes use the same secret_key.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.
Parameters: - 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
- destination (str) – The redirection destination, as a full path
(e.g.
-
stylesheet
¶ The stylesheet to use for the Flask templates
-
url_scheme
¶ Provide the _scheme parameter to be sent along to flask.url_for
-
authl.flask.
client_id
()¶ 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.
Parameters: - 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
Returns: The configured
authl.Authl
instance. Note that if you want theAuthlFlask
instance you should instantiate that directly.