Configuration - AuthKit Cookbook

Introduction

AuthKit has been designed to be totally configurable either directly in Python code or from a config file.

Configuration options fall into three categories:

Global setup
Configuration of induvidual middleware components
Custom config options for your own setup

A logical way of structuring these three sets of options in a config file might be this:

authkit.setup.*      (setup options)
authkit.middleware.* (middleware options)
authkit.config.*     (custom config options)

However, since most of the configuration actually relates to the middleware setup the options are structured like this:

authkit.setup.*  (setup options)
authkit.*        (middleware options)
authkit.config.* (custom config options)

This means that you can't create middleware named setup or config since the options would conflict. This setup has been chosen to reduce the amount of typing and the depth of config options for the middleware setup.

Passing the Options To AuthKit

All the configuration options should be passed to the AuthKit authenticate middleware as the app_conf dictionary. For Pylons users who specify the AuthKit options in the [app:main] section of their development.ini config file the app_conf dictionary is automatically availble in their make_app() function in config/middleware.py. Users of other systems will have to generate the app_conf dictionary from whichever config file format they use.

Regardless of how the information is obtained from the config file your framework uses, you should end up with an app_conf dictionary similar to this:

{
    'authkit.setup.middleware':'form, cookie',
    ... etc ...
}

You can then pass this dictionary to the authenticate middleware:

from authkit.authenticate import middleware
app = middleware(app, app_conf)

The middleware will then be correctly configured.

Changing the Prefix

If you are setting up your app_conf dictionary but don't want to use authkit. as the prefix to all your config options you can specify the correct prefix when setting up the middleware.

For example if your config file was in this format:

myauth.setup.*
myauth.*
myauth.config.*

then you would setup the prefix like this:

from authkit.authenticate import middleware
app = middleware(app, app_conf, prefix="myauth.")

Remembering to include the . at the end of the prefix otherwise your config options will not be correctly matched

Alternatively, if you don't want to use a prefix at all any your config file was in this format:

setup.*
*
config.*

you could setup the middleware like this:

from authkit.authenticate import middleware
app = middleware(app, app_conf, prefix="")

Specifying Options Directly

In addition to specifying options via the app_conf dictionary you can also specify options directly.

Any options you specify directly will override the options set in the app_conf dictionary and will result in a warning being issued.

Options specified directly do not have any prefix and have any . characters replaced by _ characters. For example authkit.setup.middleware would be specified as setup_middleware.

You specify the direct options when setting up the middleware like this:

from authkit.authenticate import middleware
app = middleware(app, app_conf, setup_middleware="form, cookie", cookie_name="test", ... )

Configuration Considerations for Middleware Implementors

See the Implement Your Own Authentication Method guide.

Advanced Configuration Options

In addition to authkit.setup.method you can also specify some other authkit.setup configuration variables:

authkit.setup.enable

This defaults to True if not specified.

authkit.setup.intercept

The default is just to intercept 401 status responses.

If specified should be a comma separated list of status codes you would like the authkit middleware to respond to. For example if you want 403 Unauthorized pages to also prompt the visitor to sign in you could do this:
authkit.setup.intercept = 401, 403
If you wanted only authenticated users to see error reports you could use:
authkit.setup.intercept = 500
If 401 isn't one of the supplied codes, a warning is issued.

Cookie Options

Some of the AuthKit middleware plugins such as passurl, cookie and form require cookie options to be set. They all take the same cookie options which are described here.

These settings aren't quite correct!

Please bear in mind that cookie options are used for various parts of the configuration so you will need to prepend the appropriate string to the name of the cookie option. For example, authkit.cookie.name for cookie_name.

cookie_name

The name of the cookie, default is auth_tkt.

cookie_includeip

Should be True or False. If True, the IP address of the user is also included in the encryped ticket to prevent the same cookie being used from a different IP address and hence to try to improve security.

cookie_signout

A path which when visited will cause the cookie to be removed and the user to therefore be signed out. The application should still display a page at this path otherwise the user will see a 404 page and think there is a problem

cookie_secret

A string you can set used to make the encryption on the cookie data more random. You should set a secret and make sure it isn't publically available.

cookie_enforce

If a cookie expires param is set, and this is set to True then there will also be server-side checking of the expire time to ensure the user is signed out even if the browser fails to remove the cookie.

cookie_params

This should be a string of any cookie params which can be set and which the browser will respond to. The string should have each param on a different line in the form name:value.

The available options are expires, path, comment, domain, max-age, secure and version. These are the values described in RFC 2109 but for convenience expires can be set as the number of seconds and will be converted automatically.

So, for example to have a cookie that expires after 20 seconds with a cookie name test and comment hi when using the forward method:

# AuthKit Options
authkit.enable = true
authkit.method = forward
authkit.cookie.secret = random string
authkit.cookie.name = test
authkit.cookie.params = expires: 10
                        comment: hi

If you are really worried about security add:

authkit.cookie.enforce = True
authkit.cookie.includeip = True

The first does a server side check on the cookie expire time as well as trusting the browser to do it. The second checks the IP address too and will only work from the same IP address.