.\" Man page generated from reStructuredText.
.
.TH "FLASK-HTTPAUTH" "1" "July 26, 2014" "" "Flask-HTTPAuth"
.SH NAME
flask-httpauth \- Flask-HTTPAuth Documentation
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.sp
\fBFlask\-HTTPAuth\fP is a simple extension that provides Basic and Digest HTTP authentication for Flask routes.
.SH BASIC AUTHENTICATION EXAMPLE
.sp
The following example application uses HTTP Basic authentication to protect route \fB\(aq/\(aq\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
from flask import Flask
from flask.ext.httpauth import HTTPBasicAuth

app = Flask(__name__)
auth = HTTPBasicAuth()

users = {
    "john": "hello",
    "susan": "bye"
}

@auth.get_password
def get_pw(username):
    if username in users:
        return users.get(username)
    return None

@app.route(\(aq/\(aq)
@auth.login_required
def index():
    return "Hello, %s!" % auth.username()

if __name__ == \(aq__main__\(aq:
    app.run()
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The \fBget_password\fP callback needs to return the password associated with the username given as argument. Flask\-HTTPAuth will allow access only if \fBget_password(username) == password\fP\&.
.sp
If the passwords are stored hashed in the user database then an additional callback is needed:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
@auth.hash_password
def hash_pw(password):
    return md5(password).hexdigest()
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
When the \fBhash_password\fP callback is provided access will be granted when \fBget_password(username) == hash_password(password)\fP\&.
.sp
If the hashing algorithm requires the username to be known then the callback can take two arguments instead of one:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
@auth.hash_password
def hash_pw(username, password):
    get_salt(username)
    return hash(password, salt)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
For the most degree of flexibility the \fIget_password\fP and \fIhash_password\fP callbacks can be replaced with \fIverify_password\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
@auth.verify_password
def verify_pw(username, password):
    return call_custom_verify_function(username, password)
.ft P
.fi
.UNINDENT
.UNINDENT
.SH DIGEST AUTHENTICATION EXAMPLE
.sp
The following example is similar to the previous one, but HTTP Digest authentication is used:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
from flask import Flask
from flask.ext.httpauth import HTTPDigestAuth

app = Flask(__name__)
app.config[\(aqSECRET_KEY\(aq] = \(aqsecret key here\(aq
auth = HTTPDigestAuth()

users = {
    "john": "hello",
    "susan": "bye"
}

@auth.get_password
def get_pw(username):
    if username in users:
        return users.get(username)
    return None

@app.route(\(aq/\(aq)
@auth.login_required
def index():
    return "Hello, %s!" % auth.username()

if __name__ == \(aq__main__\(aq:
    app.run()
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Note that because digest authentication stores data in Flask\(aqs \fBsession\fP object the configuration must have a \fBSECRET_KEY\fP set.
.SH API DOCUMENTATION
.INDENT 0.0
.TP
.B class flask_httpauth.HTTPBasicAuth
This class that handles HTTP Basic authentication for Flask routes.
.INDENT 7.0
.TP
.B get_password(password_callback)
This callback function will be called by the framework to obtain the password for a given user. Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
@auth.get_password
def get_password(username):
    return db.get_user_password(username)
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B hash_password(hash_password_callback)
If defined, this callback function will be called by the framework to apply a custom hashing algorithm to the password provided by the client. If this callback isn\(aqt provided the password will be checked unchanged. The callback can take one or two arguments. The one argument version receives the password to hash, while the two argument version receives the username and the password in that order. Example single argument callback:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
@auth.hash_password
def hash_password(password):
    return md5(password).hexdigest()
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Example two argument callback:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
@auth.hash_password
def hash_pw(username, password):
    get_salt(username)
    return hash(password, salt)
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B verify_password(verify_password_callback)
If defined, this callback function will be called by the framework to verify that the username and password combination provided by the client are valid. The callback function takes two arguments, the username and the password and must return \fBTrue\fP or \fBFalse\fP\&. Example usage:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
@auth.verify_password
def verify_password(username, password):
    user = User.query.filter_by(username).first()
    if not user:
        return False
    return passlib.hash.sha256_crypt.verify(password, user.password_hash)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Note that when a \fIverify_password\fP callback is provided the \fIget_password\fP and \fIhash_password\fP callbacks are not used.
.UNINDENT
.INDENT 7.0
.TP
.B error_handler(error_callback)
If defined, this callback function will be called by the framework when it is necessary to send an authentication error back to the client. The return value from this function can be the body of the response as a string or it can also be a response object created with \fImake_response\fP\&. If this callback isn\(aqt provided a default error response is generated. Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
@auth.error_handler
def auth_error():
    return "<h1>Access Denied</h1>"
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B login_required(view_function_callback)
This callback function will be called when authentication is succesful. This will typically be a Flask view function. Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
@app.route(\(aq/private\(aq)
@auth.login_required
def private_page():
    return "Only for authorized people!"
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B username()
A view function that is protected with this class can access the logged username through this method. Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
@app.route(\(aq/\(aq)
@auth.login_required
def index():
    return "Hello, %s!" % auth.username()
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B class flask.ext.httpauth.HTTPDigestAuth
This class that handles HTTP Digest authentication for Flask routes. The \fBSECRET_KEY\fP configuration must be set in the Flask application to enable the session to work. Flask by default stores user sessions in the client as secure cookies, so the client must be able to handle cookies. To support clients that are not web browsers or that cannot handle cookies a \fI\%session interface\fP that writes sessions in the server must be used.
.INDENT 7.0
.TP
.B get_password(password_callback)
See basic authentication for documentation and examples.
.UNINDENT
.INDENT 7.0
.TP
.B error_handler(error_callback)
See basic authentication for documentation and examples.
.UNINDENT
.INDENT 7.0
.TP
.B login_required(view_function_callback)
See basic authentication for documentation and examples.
.UNINDENT
.INDENT 7.0
.TP
.B username()
See basic authentication for documentation and examples.
.UNINDENT
.UNINDENT
.SH AUTHOR
Miguel Grinberg
.SH COPYRIGHT
2013, Miguel Grinberg
.\" Generated by docutils manpage writer.
.