KegBouncer 2.2.4

Intro

Built on top of Keg and KegElements, KegBouncer offers several features for managing authorization and authentication. KegBouncer allows you to pick and choose which features you want it to handle in you application. It achieves this by providing each feature as a Mixin class which you can optionally mixin to your entities (probably a User entity).

The available mixins cover:

• Three-tierd permission system

• Password-based authentication and password history

• Login history

Refer to the sections below on how to use each of these.

Permissions

In order to use KegBouncer’s authorization features to protect Keg views, you will also need Flask-Login. However, KegBouncer’s models do not require that dependency.

keg_bouncer.mixins.PermissionMixin provides a three-tiered permissions model. It manages four kinds of entities:

• Users

• Permissions (for describing actions that can be guarded within the system)

• User groups (for grouping users in a way that best models business needs)

• Permission bundles (for grouping permissions in a way that best models the system)

We call this a “three-tiered” permissions model because a user can be granted permissions in three ways:

1. Directly

2. Through permission bundles

3. Through user groups

This terminology is designed to distinguish this permissions model from other ones, like RBAC, which permit higherarchies of any depth. Technically, this three-tier model is a special case of RBAC.

Note about the term “role”: While this model is technically a special case of the widely-used Role-based access control (RBAC), we took great pains to avoid the highly ambiguous term “role.”

import flask_login  # Only necessary if using KegBouncer to protect you views.
from sqlalchemy import import Column, Integer, String

Base = sqlalchemy.ext.declarative.declarative_base()

class User(Base, flask_login.UserMixin, keg_bouncer.model.mixins.PermissionMixin):
    __tablename__ = 'users'
    id = Column(Integer, primary_key=True)

[alembic]
version_locations = alembic/versions keg_bouncer:alembic/versions

$ alembic heads
51ba1b47505e (application) (head)
13d265b97e4d (keg_bouncer) (head)

$ alembic merge -m "pull KegBouncer into application" 51ba1b 13d265
Generating /path/to/app/alembic/versions/31b094b2844f_pull_keg_bouncer_into_application.py ... done

$ alembic heads
31b094b2844f (application, keg_bouncer) (head)

Password-based Authentication

To add password-based authentication to your entity, you need to dynamically construct a password mixin object and mix it in to your entity.

from keg_bouncer.model import mixins
from passlib.context import CryptContext
import sqlalchemy as sa

crypt_context = CryptContext(schemes=['bcrypt'])

# This mixin is optional but allows you to add additional fields to the password history table.
class OptionalAdditionalFields(object):
    another_field = sa.Column(sa.Integer)


password_history_mixin = mixins.make_password_mixin(
    OptionalAdditionalFields,    # [optional] Allows you to add more fields to the password
                                 # history table via a mixin
    crypt_context=crypt_context  # [optional, but must be provided here or via another means]
                                 # Configures the CryptContext for hashing and verifying
)


class User(password_history_mixin):
    default_crypt_context = crypt_context  # An alternative way of specifying your CryptContext

    # Yet another way to specify your CryptContext
    def get_crypt_context(self):
        return crypt_context


help(User.set_password)  # Adds password to password history

help(User.verify_password)  # Verifies a password against most recent password

help(User.is_password_used_previously)  # Looks for password in history

help(User.password_history_entity)  # SQLAlchemy entity defining password history entries

User.password_history  # SQLAlchemy relationship for past passwords;
                       # sorted in reverse chronological order

Note: If you use is_password_used_previously or a similar concept, your choice of a hashing algorithm can drastically impact performance since password verification is intentionally slow. For example, using bcrypt instead of sha256_crypt will allow you to verify passwords about twice as quickly. This makes a big difference when you’re sifting through past passwords.

Login History

To add login history to your entity, you need to dynamically construct a history mixin object and mix it in to your entity.

from keg_bouncer.model import mixins
import sqlalchemy as sa

# This mixin is optional but allows you to add additional fields to the login history table.
class OptionalAdditionalFields(object):
    another_field = sa.Column(sa.Integer)


login_history_mixin = mixins.make_login_history_mixin(
    OptionalAdditionalFields,  # [optional] Allows you to add more fields to the login history
                               # table via a mixin
)


class User(login_history_mixin):
    pass


help(User.login_history_entity)  # SQLAlchemy entity defining login history entries

User.login_history  # SQLAlchemy relationship for past logins;
                    # sorted in reverse chronological order

# Example use:
def register_login(user):
    user.login_history.insert(0, user.login_history_entity(is_login_successful=True))

Development

ln -s scripts/pre-commit .git/hooks