Settings reference

Since RestAuth is implemented as a Django project, RestAuth not only uses all settings available in Django, but also features a few additional settings that ease administration and configure RestAuth. This document is a complete reference of settings that are either specific to RestAuth or are normal Django settings that RestAuth handles in a different way.

Location of localsettings.py

The file localsettings.py is referenced throughout the documentation. The name and location of this file varies depending on how you installed RestAuth. Here is an overview of known locations:

Installation method Location
from source RestAuth/RestAuth/localsettings.py
with pip Copy RestAuth/config/localsettings.py.example manually to RestAuth/config/localsettings.py.
Debian/Ubuntu /etc/restauth/settings.py
Fedora Unknown
Archlinux Unknown

Note

If you start digging deeper into RestAuth and Django configuration, you will notice, that many configuration variables normally present in a Django settings file are missing from that file. This is because the file is only included in the real settings.py file. This is why you can set any Django setting in your localsettings.py and overwrite any existing Django setting.

CACHES

Default: see Django documentation

This setting is available in Django. Please see the official documentation on how to use this setting.

Warning

If you change this setting, please also see SECURE_CACHE.

CONTENT_HANDLERS

Default:

(
   'RestAuthCommon.handlers.JSONContentHandler',
   'RestAuthCommon.handlers.FormContentHandler',
   'RestAuthCommon.handlers.PickleContentHandler',
   'RestAuthCommon.handlers.YAMLContentHandler',
)

New in version 0.6.1.

The handlers used to encode/decode content. If you write custom content handlers, add them here.

GROUP_BACKEND

New in version 0.6.1.

Default: 'backends.django_backend.DjangoGroupBackend'

The backend to use to store groups. Please see Group backends for a more comprehensive description of available backends. The default is the only backend shipping with RestAuth, but other backends may be available elsewhere.

If you need a custom backend to store groups, please see Custom backends.

GROUP_RECURSION_DEPTH

New in version 0.6.0: In version 0.5.3 and earlier the recursion depth was hard-coded to 10.

Default: 3

When calculating group memberships RestAuth supports nested groups, where a group may have parent groups and inherit additional memberships from its parent groups.

Note

Parent groups do not have to belong to the same service if you configure them using restauth-group. This lets you, for example, configure an administration service that can define memberships for its own groups and other, lesser privileged services, automatically inherit memberships from the groups of the administration service.

A GROUP_RECURSION_DEPTH of 3 means that RestAuth will check 3 levels of parent groups. Take this example, where Group A is a parent group of Group B and so on:

Group A
|- Group B
  |- Group C
     |- Group D
        |- Group E

If a user is a member of Group A, he will also be considered a member of Group B, Group C and Group D but no longer a member of Group E, because the third level of parent-groups above is Group B, where the user is not a “direct” member.

Setting GROUP_RECURSION_DEPTH to 0 will disable nested groups entirely.

Warning

Do not set this setting to a value greater then necessary. Checking nested groups is relatively performance intensive. Set this setting to a value as low as possible.

LOGGING

Default: please see source-code

This setting is available in Django. RestAuth has (unlike Django) an extensive default. Various views assume the presence of configured loggers, so it is not recommended to change this setting yourself. If you really know what you are doing, read the real settings.py on how to imitate the required loggers.

LOG_HANDLER

Default: 'logging.StreamHandler'

You can define a different destination of any log messages using LOG_HANDLER. The setting should be a string containing the classname of any available handler. See logging.handlers for whats available. Of course nothing stops you from implementing your own handler.

LOG_HANDLER_KWARGS

Default: {}

Any additional keyword arguments the log handler defined in LOG_HANDLER LoggingHandler will get.

Here is an example for a SocketHandler:

LOG_HANDLER_KWARGS = { 'host': 'localhost', 'port': 10000 }

LOG_LEVEL

Default: 'ERROR'

The default log-level to use. Available values are:

Level Description
CRITICAL Only log errors due to an internal malfunction.
ERROR Also log errors due to misbehaving clients.
WARNING Also log requests where an implicit assumption doesn’t hold. (i.e. when a client assumes that a user exists that in fact does not)
INFO Also log successfully processed requests that change data.
DEBUG Also log idempotent requests, i.e. if a user exists, etc.

MAX_USERNAME_LENGTH

Default: 255

The maximum length of new usernames. Note that this setting might have any effect if a validator restricts the maximum length even further.

MIDDLEWARE_CLASSES

Default:

(
    'django.middleware.common.CommonMiddleware',
    'common.middleware.RestAuthMiddleware',
)

RestAuth uses middlewares like any other Django project. The default however only contains the bare minimum of required middlewares.

MIN_PASSWORD_LENGTH

Default: 6

The minimum length for new passwords. This of course only affects new passwords.

MIN_USERNAME_LENGTH

Default: 3

The minimum length of new usernames. Note that this setting might have any effect if a validator restricts the minimum length even further.

PASSWORD_HASHERS

New in version 0.6.1: This standard Django setting now replaces the old HASH_FUNCTIONS and HASH_ALGORITHMS settings. Please see the upgrade notes for 0.6.1 for more information.

Default:

PASSWORD_HASHERS = (
    'django.contrib.auth.hashers.PBKDF2PasswordHasher',
    'common.hashers.Sha512Hasher',
    'common.hashers.MediaWikiHasher',
    'common.hashers.Apr1Hasher',
    'common.hashers.Drupal7Hasher',
    'common.hashers.PhpassHasher',
    'django.contrib.auth.hashers.PBKDF2SHA1PasswordHasher',
    'django.contrib.auth.hashers.BCryptPasswordHasher',
    'django.contrib.auth.hashers.SHA1PasswordHasher',
    'django.contrib.auth.hashers.MD5PasswordHasher',
    'django.contrib.auth.hashers.UnsaltedMD5PasswordHasher',
    'django.contrib.auth.hashers.CryptPasswordHasher',
)

RestAuth can store password hashes in different formats. RestAuth ships with additional hashers for MediaWiki, Apr1 (Apache .htaccess files) and SHA-512 hashes. Thanks to these hashers, RestAuth understands and can even create hashes as used by the respective systems.

If you need to import hashes from a different system, you can easily write your own password hasher. Please see Custom password hashes for more information.

Note

This setting is by default also used for services. You can speed up RestAuth with the SERVICE_PASSWORD_HASHER setting.

PROPERTY_BACKEND

New in version 0.6.1.

Default: 'backends.django_backend.DjangoPropertyBackend'

The backend to use to store user properties. RestAuth comes with two property backends:

'backends.django_backend.DjangoPropertyBackend'
Use the standard Django ORM to store property data. This backend requireds that you also use the DjangoUserBackend.
'backends.redis_backend.RedisPropertyBackend'
Use a Redis server to store properties.

Please see Property backends for a more comprehensive description of available backends. Other backends may be available elsewhere, if you need to develop your own backend, please see Custom backends.

RELAXED_LINUX_CHECKS

Default: False

When this variable is set to True, the validator will apply a more relaxed check. Please see the linux validator for more information.

SECRET_KEY

Never forget to set a SECRET_KEY in localsettings.py.

SECURE_CACHE

New in version 0.6.1.

Changed in version 0.6.4: The default is now True, it used to be False previously.

Default: True

By default, RestAuth caches service credentials. This is fine with the default settings, since Django by default uses an in-memory cache (see CACHES) and once an attacker is able to read in-memory datastructures, all information protected by the credentials are already compromised anyway.

Depending on other settings, you might want to set this to False:

  • If you use a different caching backend, i.e. memcached or redis.
  • If you use a cache on another host, it is highly recommended to set this to False.
  • If you want to make it as unlikely as possible for an attacker to get service credentials on an already compromised RestAuth server.

SERVICE_PASSWORD_HASHER

New in version 0.6.1.

default: default

You may override the hasher used for hashing service passwords. Since the passwords used for service authentication are usually not very valuable (auto-generated, easily changeable) you may choose a faster hashing algorithm from any algorithm found in PASSWORD_HASHERS. The special value default (which is the default) means the first hasher in PASSWORD_HASHERS. This speeds up RestAuth significantly, but has the security drawback that an attacker might be able to retrieve service credentials from the cache..

USER_BACKEND

New in version 0.6.1.

Default: 'backends.django_backend.UserBackend'

The backend used for storing user data. Please see User backends for a more comprehensive description of available backends. The default is the only backend shipping with RestAuth, but other backends may be available elsewhere.

If you need a custom backend to store user data, please see Custom backends.

VALIDATORS

New in version 0.5.3: In version 0.5.2 and earlier SKIP_VALIDATORS configured roughly the inverse. Please see the upgrade notes if you still use the old setting.

Default: []

By default, usernames in RestAuth can contain any UTF-8 character except a slash (‘/’), a backslash (‘\’) and a colon (‘:’). You can add additional validators to restrict usernames further to ensure that new usernames are compatible with all systems you use.

Note

Validators are only used when creating new accounts. This way existing users can still login to existing systems if you enable additional validators later on, even if their username is illegal in a new system.

Example configuration for disabling the registration of accounts incompatible with either MediaWiki or XMPP:

VALIDATORS = [
    'Users.validators.mediawiki',
    'Users.validators.xmpp',
]

Please see Username validation for information on what validators exist and how to write your own validators.