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.
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
andBASIC_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 viainit_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
andBASIC_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.