Flask-htpasswd
--------------
.. image:: https://img.shields.io/travis/carsongee/flask-htpasswd.svg
    :target: https://travis-ci.org/carsongee/flask-htpasswd
.. image:: https://img.shields.io/coveralls/carsongee/flask-htpasswd.svg
    :target: https://coveralls.io/r/carsongee/flask-htpasswd
.. image:: https://img.shields.io/github/issues/carsongee/flask-htpasswd.svg
    :target: https://github.com/carsongee/flask-htpasswd/issues
.. image:: https://img.shields.io/pypi/dm/flask-htpasswd.svg
    :target: https://pypi.python.org/pypi/flask-htpasswd/0.1.0
.. image:: https://img.shields.io/pypi/v/flask-htpasswd.svg
    :target: https://pypi.python.org/pypi/flask-htpasswd/0.1.0
.. image:: https://img.shields.io/badge/license-BSD-blue.svg
    :target: https://github.com/carsongee/flask-htpasswd/blob/master/LICENSE


Flask extension for providing basic digest and token authentication
via apache htpasswd files.  So largely it fits between `Flask-Security
<https://pythonhosted.org/Flask-Security/>`_ which has additional
dependencies and `Flask-BasicAuth
<http://flask-basicauth.readthedocs.org/en/latest/>`_ which only
allows you to have one user (and also puts the plain text password
into the configuration).

Sample usage is to first create an htpasswd file with the `apache tool <http://httpd.apache.org/docs/2.2/programs/htpasswd.html>`_:

.. code-block:: bash

  htpasswd -c /path/to/.htpasswd my_username

Additional users can be added, or have their passwords changed, by running:

.. code-block:: bash

  htpasswd /path/to/.htpasswd new_user
  htpasswd /path/to/.htpasswd user_I_want_to_change_passwords_for

Then you just need to setup and configure your flask application, with
something like:

.. code-block:: python

  import flask
  from flask.ext.htpasswd import HtPasswdAuth

  app = flask.Flask(__name__)
  app.config['FLASK_HTPASSWD_PATH'] = '/path/to/.htpasswd'
  app.config['FLASK_SECRET'] = 'Hey Hey Kids, secure me!'

  htpasswd = HtPasswdAuth(app)
  

  @app.route('/')
  @htpasswd.required
  def index(user):
      return 'Hello {user}'.format(user=user)

  app.run(debug=True)

And that view should now prompt for a username and password (and
accept tokens).

If you would like to protect all of your views, that is easy too, just
add a little config. By setting ``app.config['FLASK_AUTH_ALL']=True``
before initializing the extension, an ``@app.before_request`` is added
that will require auth for all pages.

One last small feature, is that you can also set the authentication
realm.  The default is 'Login Required', but it can be set with
``app.config['FLASK_AUTH_REALM']`` before initialization.


Using Tokens
============

Tokens are based on the username and password, and thus invalid
whenever the user's password is changed.  To get a user password, you
can serve it out to the user with something like

.. code-block:: python

  import flask
  from flask.ext.htpasswd import HtPasswdAuth

  app = flask.Flask(__name__)
  app.config['FLASK_HTPASSWD_PATH'] = '/path/to/.htpasswd'
  app.config['FLASK_SECRET'] = 'Hey Hey Kids, secure me!'
  htpasswd = HtPasswdAuth(app)
  

  @app.route('/')
  @htpasswd.required
  def index(user):
      return flask.jsonify({'token': htpasswd.generate_token(user)})

  app.run(debug=True)

It can then be used by the user by adding it to the header of their requests, something like:

.. code-block:: python

  import requests

  requests.get('http://localhost:5000/', headers={'Authorization': 'token <token>'})


Release Notes
=============

0.2.0
`````

- Python 3 compatability

Acknowledgements
================

This is largely based on a combination of:

- http://flask-basicauth.readthedocs.org/en/latest/
- http://flask.pocoo.org/snippets/8/
- http://blog.miguelgrinberg.com/post/restful-authentication-with-flask


Links
`````

* `documentation
  <https://github.com/carsongee/flask-htpasswd/blob/master/README.rst>`_
* `development version
  <https://github.com/carsongee/flask-htpasswd/archive/master.tar.gz#egg=flask-htpasswd-dev>`_
