Flask-BasicAuth

Flask-BasicAuth is a Flask extension that provides an easy way to protect certain views or your whole application with HTTP basic access authentication.

Installation

The easiest way to install Flask-BasicAuth is with pip:

pip install Flask-BasicAuth

Usage

Usage of Flask-BasicAuth is simple:

from flask import Flask, render_template
from flask_basicauth import BasicAuth

app = Flask(__name__)

app.config['BASIC_AUTH_USERNAME'] = 'john'
app.config['BASIC_AUTH_PASSWORD'] = 'matrix'

basic_auth = BasicAuth(app)

@app.route('/secret')
@basic_auth.required
def secret_view():
    return render_template('secret.html')

If you would like to protect you entire site with basic access authentication, just set BASIC_AUTH_FORCE configuration variable to True:

app.config['BASIC_AUTH_FORCE'] = True

You might find this useful, for example, if you would like to protect your staging server from uninvited guests.

Warning

Please make sure that you use SSL/TLS (HTTPS) to encrypt the connection between the client and the server, when using basic access authentication. In basic access authentication username and password are sent in cleartext, and if SSL/TLS is not used, the credentials could be easily intercepted.

Configuration

The following configuration values exist for Flask-BasicAuth. Flask-BasicAuth loads these values from your main Flask config which can be populated in various ways.

A list of configuration keys currently understood by the extension:

BASIC_AUTH_FORCE

If set to True, makes the whole site require HTTP basic access authentication.

Defaults to False.

BASIC_AUTH_REALM

The authentication realm used for the challenge. This is typically a description of the system being accessed.

Defaults to ''.

BASIC_AUTH_USERNAME and BASIC_AUTH_PASSWORD

The correct username and password combination that grants access for the client to the protected resource.

You can override BasicAuth.check_credentials, if you need a different authentication logic for your application.

API reference

This part of the documentation covers all the public classes and functions in Flask-BasicAuth.

class flask.ext.basicauth.BasicAuth(app=None)

A Flask extension for adding HTTP basic access authentication to the application.

Parameters:app – a Flask instance. Defaults to None. If no application is provided on creation, then it can be provided later on via init_app().
authenticate()

Check the request for HTTP basic access authentication header and try to authenticate the user.

Returns:True if the user is authorized, or False otherwise.
challenge()

Challenge the client for username and password.

This method is called when the client did not provide username and password in the request, or the username and password combination was wrong.

Returns:a Response with 401 response code, including the required authentication scheme and authentication realm.
check_credentials(username, password)

Check if the given username and password are correct.

By default compares the given username and password to BASIC_AUTH_USERNAME and BASIC_AUTH_PASSWORD configuration variables.

Parameters:
  • username – a username provided by the client
  • password – a password provided by the client
Returns:

True if the username and password combination was correct, and False otherwise.
init_app(app)

Initialize this BasicAuth extension for the given application.

Parameters:app – a Flask instance
required(view_func)

A decorator that can be used to protect specific views with HTTP basic access authentication.

Changelog

Here you can see the full list of changes between each Flask-BasicAuth release.

0.2.0 (June 15, 2013)

  • Added Python 3 support.

0.1.1 (May 20, 2013)

  • Fixed an issue where attempting to authenticate with password containing one or more colons was failing with “too many values to unpack” error (Michael Wallace).

0.1.0 (April 30, 2012)

  • Initial public release

License

Copyright (c) 2013, Janne Vanhala

All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

  • Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
  • Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
  • The names of the contributors may not be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS “AS IS” AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.