Authcode

Tutorial

This guide covers what you need to know to start using Authcode.

Installation

pip install authcode

Quick Start

Using Authcode is your app is just three step process:

1. Create a Auth object

auth = authcode.Auth(SECRET_KEY, db=db)
User = auth.User

There are several parameters that you can use to configure it, but at least you must provide a secret key and a connection objet to SQLAlchemy.

The object db is what you get from SQLAlchemy_Wrapper [1] or Flask_SQLAlchemy.

Auth.User is the user model automatically generated by Authcode. You will need this reference for creating users or relate it to your other models.

Tip

Don’t have a db because you are using SQLAlchemy directly? [1] Read the section advanced.naked_sqlalchemy to find out how to proceed.

2. Setup for your framework

The next step is to setup the newly created Auth object for the web framework you’re using. For instance, with Flask you do:

authcode.setup_for_flask(auth, app)

This setup function configure Authcode with the peculiarities of the framework you´re using, such as how to render the templates, mount views and things like that.

For now, these are the framework included with the library:

  • Flask (See api.setup_for_flask)
  • Bottle (See api.setup_for_bottle)

3. Protect your views

Finally, you use auth.protected to decorate the views you want that are only accessible to users.

@app.route('/')
@auth.protected()
def index():
    ...

Note

Note that the decorator is being called (have a pair of parentheses at the end of the line). These are necessary, don´t forget to write them.

Warning

Warning!
If you define the URLs of your views by decorating them —like you do in Flask— be careful to put the decorator authentication after the route, otherwise your views will be unprotected. Do it this way:
  @app.route('/admin/')
  @auth.protected()
  def myview():
      ...

See also

This decorator has other options, such as specifying roles that the user must have to enter a page. Red more about it in this guide authorization.

Authcode automatically generates views for login, logout and restoring your password, so when you try to visit the this page, it will redirect you to the included default login page.

_images/login.png

Default login page.

Note than that page also has a link to another one to rest your password; The method is the standard: you write your username and Authcode sends you an email with a special link to choose a new password.

For this to work, it needs a way to send the email, that’s a feature that your application must provide[2]_. For example, it might look like this:

def send_auth_email(user, subject, msg):
    try:
        mailer.send(
            subject=subject,
            from_email=config.MAILER_FROM,
            to=user.email,
            html=msg
        )
    except Exception as e:
        print(e)

Authcode.setup_for_flask(auth, app, send_email=send_auth_email)

The function that you pass to send_email takes as arguments the user who wants to recover his password, the subject and body of the message (by default in HTML). Of course you must have an email associated with the user, so either you use your email as username (login) or add an email field using a mixin as described in the next section (authentication).

See the code of this example in https://github.com/jpscaletti/Authcode/tree/master/examples/minimal.

[1](1, 2) SQLAlchemy-Wrapper will save you a lot of the work needed to initialize SQLAlchemy, regardless of whether you use Authcode or not.
[2]or you can also disable it completely in the settings.