talons 0.1

A simple usage example

A simple Falcon API application is constructed like so:

import falcon

# falcon.API instances are callable WSGI apps
app = falcon.API()

To add middleware to a Falcon API application, we simply instantiate the desired talons.auth middleware and supply it to the falcon.API() call:

import falcon
from talons.auth import middleware
from talons.auth import basicauth, httpheader, htpasswd

# Assume getappconfig() returns a dictionary of application configuration
# options that may have been read from some INI file...
config = getappconfig()

auth_middleware = middleware.create_middleware(identify_with=[
                                                 basicauth.Identifier,
                                                 httpheader.Identifier],
                                               authenticate_with=htpasswd.Authenticator,
                                               **config)

app = falcon.API(before=[auth_middleware])

Identifiers

Each class that derives from talons.auth.interfaces.Identifies is called an “Identifier”. Each class implements a single method, identify(), that takes the incoming falcon.request.Request object as its sole parameter. If the identity of the authenticating user can be determined, then the Identifier object stores a talons.auth.interfaces.Identity object in the WSGI environ’s wsgi.identity key and returns True.

Multiple Identifier classes can be supplied to the talons.auth.middleware.create_middleware method to support a variety of ways of gleaning identity information from the WSGI request. Each Identifier’s identify() method checks to see if the wsgi.identity key is already set in the WSGI environs. If it is, the method simply returns True and does not attempt to process anything further.

httpheader_user=x-auth-user
httpheader_key=x-auth-password
httpheader_domain=x-auth-domain

Authenticators

Each class that derives from talons.auth.interfaces.Authenticates is called an “Authenticator”. Each Authenticator implements a single method, authenticate(), that takes a talons.auth.interfaces.Identity object as its sole parameter.

The authenticate method verifies that the supplied identity can be verified (authenticated). Different implementations will rely on various backend storage systems to validate the incoming identity/credentials. If authentication was successful, the method returns True, False otherwise.

Talons comes with a few simple examples of Authenticator plugins.

import hashlib

import redis

_AUTH_DB = redis.StrictRedis(host='localhost', port=6379, db=0)


def _pass_matches_stored_pass(pass, stored_pass):
    # Assume that passwords are stored in Redis in the following format:
    # salt:hashedpass
    # and that the passwords have been hashed with SHA-256
    salt, stored_hashed_pass = stored_pass.split(':')
    hashed_pass = hashlib.sha256(salt.encode() + pass.encode()).hexdigest()
    return hashed_pass == stored_hashed_pass


def authenticate(identity):
    user = identity.login
    pass = identity.key

    stored_pass = _AUTH_DB.get(user)
    if stored_pass:
        return _pass_matches_stored_pass(pass, stored_pass)
    return False

Contributing

Jay Pipes maintains the Talons library. You can usually find him on the Freenode IRC #openstack-dev channel. Interested in improving and enhancing Talons? Pull requests are always welcome.

License and Copyright

Copyright 2013, Jay Pipes

Licensed under the Apache License, Version 2.0 (the “License”); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.