falcon-policy

Falcon Middleware: Policy Middleware |Build Status| |codecov.io|

The falcon-policy package provides a middleware component that enables simple policy controls such as role-based access on routes via configuration.

The configuration approach to policy rules enables dynamic authorization use-cases where the policy needs to be adjusted on-demand without a new service deployment.

Installation

.. code:: bash

$ pip install falcon-policy

Usage

The RoleBasedPolicy middleware class examines each incoming request and verifies the roles list from the request context; which should be populated by an authentication middleware. If the request context isn't populated with a roles list, then the middleware will fall back on the X-Roles header for the appropriate role given the request being made. Usage of the X-Roles header, is primarily used when handling authentication outside of the middleware stack or for development with authentication disabled.

Implementation Note:

If the request context type isn't a dictionary, the middleware will assume that req.context is an Object with a roles attribute.

Getting Started:

• Create a policy configuration
• Create an instance of RoleBasedPolicy using the configuration
• Pass the instance to the falcon.API() initializer:

.. code:: python

from falcon_policy import RoleBasedPolicy

policy_config = {
    'roles': [
        'admin',
        'creator',
        'observer',
    ],
    'groups': {
        'create': ['admin', 'creator'],
        'update': ['admin', 'creator'],
        'read': ['admin', 'creator', 'observer'],
        'delete': ['admin'],
    },
    'routes': {
        '/quote': {
            'GET': ['read'],
            'POST': ['create'],
            'PUT': ['update'],
            'DELETE': ['delete'],
        },
        '/quote/{id}': {
            'GET': ['read'],
            'POST': ['create'],
            'PUT': ['update'],
            'DELETE': ['delete'],
        },
        '/status': {
            'GET': ['@any-role'],
            'HEAD': ['@passthrough'],
        },
    },
}

app = falcon.API(
    middleware=[
        RoleBasedPolicy(policy_config)
    ]
)

If validation fails an instance of falcon.HTTPForbidden is raised.

Configuration

The policy configuration is separated into three sections:

• Roles: Is a list of names that correspond with Role values provided by your authentication system.
• Groups: Is an alias/grouping of multiple role names for convenience.
• Routes: A structure containing role and/or group permissions for a given Falcon route and method.

Specialty Roles:

``falcon-policy`` offers two specialty roles types that should be used with
care:

* ``@any-role``: Allows any defined role
* ``@passthrough``: Allows all users (authenticated and unauthenticated)

About Falcon

Falcon is a bare-metal Python web framework <http://falconframework.org/index.html>__ for building lean and mean cloud APIs and app backends. It encourages the REST architectural style, and tries to do as little as possible while remaining highly effective <http://falconframework.org/index.html#Benefits>__.

.. |Build Status| image:: https://travis-ci.org/falconry/falcon-policy.svg :target: https://travis-ci.org/falconry/falcon-policy .. |codecov.io| image:: https://codecov.io/gh/falconry/falcon-policy/branch/master/graph/badge.svg :target: https://codecov.io/gh/falconry/falcon-policy