Username validation

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

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.

Which validators to enable (and when)

We recommend that you enable as few validators as possible. RestAuth in principle supports almost any username and has full UTF-8 support. Many validators restrict usernames to ASCII characters and even there forbid many special characters, some do not allow spaces. Please refer to the available validators for exact documentation on what validators restrict which usernames.

On the other hand, make sure that you enable validators for systems you might use in the future right away. This way users cannot register usernames that will be unusable on any future system.

Available validators

The following validators ship with RestAuth. These validators are implemented to the best knowledge available, but are of course in no way guaranteed to really catch all illegal usernames. If you find inconsistencies, please consider to contribute.

class Users.validators.EmailValidator[source]

This validator ensures that usernames are valid username-parts of email-addresses. You can use this validator if you want to provide email-addresses of the form <username>@example.com.

This validator applies the following restrictions:

  • All characters must be ASCII characters.
  • The following ASCII characters are forbidden: (, ), ,, ;, <, >, @, [ and ]
  • No spaces are allowed
  • Usernames must not be longer than 64 characters.

A good reference for valid email addresses is WikiPedia.

class Users.validators.MediaWikiValidator[source]

This validator ensures that usernames are compatible with MediaWiki.

This validator applies the following restrictions:

  • Usernames must not be longer than 255 bytes. An UTF-8 character may have more than one byte, so the maximum username length is dependent on the characters used.
  • The following ASCII characters are forbidden: #, <, >, |, [, ], and {}
  • The following usernames are reserved by MediaWiki and are thus blocked: mediawiki default, conversion script, maintenance script, msg:double-redirect-fixer and template namespace initialisation script

See also: Manual:$wgReservedUsernames

class Users.validators.LinuxValidator[source]

This validator ensures that usernames are Linux system users.

This validator applies the following restrictions:

  • All characters must be ASCII characters
  • Usernames must not be longer than 32 characters
  • Usernames must not start with a dash (-)

Unless you set RELAXED_LINUX_CHECKS to True, the following additional restrictions apply:

  • Usernames must start with a letter or an underscore (_)
  • Usernames may consist only of letters, digits, underscores (_) and dashes (-)
class Users.validators.WindowsValidator[source]

This validator ensures that usernames are valid Windows system users.

Warning

This validator is completely untested as no Windows systems are available. This means that this validator is likely not allow some accounts that are in fact not valid. If you can, please consider to contributing.

This validator applies the following restrictions:

  • All characters must be ASCII characters
  • The following characters are forbidden: ", [, ], ;, |, =, +, *, ?, < and >
  • The following usernames are reserved and thus blocked: anonymous, authenticated user, batch, builtin, creator group, creator group server, creator owner, creator owner server, dialup, digest auth, interactive, internet, local, local system, network, network service, nt authority, nt domain, ntlm auth, null, proxy, remote interactive, restricted, schannel auth, self, server, service, system, terminal server, this organization, users and world

For a list of reserved windows usernames, see this KnowledgeBase article.

class Users.validators.XMPPValidator[source]

This validator ensures that usernames are valid username-parts for Jabber/XMPP accounts. You can use this validator if you want to provide XMPP-addresses of the form <username>@example.com.

This validator applies the following restrictions:

  • It does not allow any whitespace characters (i.e. space, tab, etc.)
  • The following characters are forbidden: ", &`, ``', <, > and @
class Users.validators.DrupalValidator[source]

This validator ensures that usernames are valid Drupal usernames.

This validator applies the following restrictions:

  • Usernames must not start or end with a space or contain multiple spaces in a row
  • Various special characters (see Warning)

Warning

The function is more or less a direct copy of user_validate_name. Unlike the Drupal function, the regular expressions actually work and filter a wide range of weird characters. For example, ‘ä’ and ‘ö’ are allowed, while ‘ü’ is not. It is thus not advisable to use this validator at this moment.

Implement your own validators

You can easily implement your own validators, if you now a little Python. This chapter assumes at least a little knowledge of Python, but you don’t have to be an expert.

To implement a validator, simply inherit from Validator and override any fields or methods. This is the class you want to inherit from:

class Users.validators.Validator[source]
ALLOW_WHITESPACE = True

If this system allows whitespace. The default is True.

FORCE_ASCII = False

If this system requires usernames to contain only ASCII characters. The default is False.

ILLEGAL_CHARACTERS = set([])

A set of characters that are forbidden on this system. By default, no characters are forbidden.

RESERVED = set([])

A set of reserved usernames. By default, no usernames are reserved.

More complex validations

If the fields in Validator do not cover your needs, you can add a method called check to implement your own, more complex checks. This method must raise common.errors.UsernameInvalid if the check fails.

Example

Here is a full example of what a validator might look like. Remember, every single part of this can be skipped, if you don’t need it (and you should, to improve performance).

from common.validators import Validator
from common.errors import UsernameInvalid

class MyOwnValidator(Validator):
    # The characters 'a', 'f' and '#' are not allowed:
    ILLEGAL_CHARACTERS = set(['a', 'f', '#'])

    # We do not allow whitespace (default is True):
    ALLOW_WHITESPACE = False

    # We do allow UTF-8 characters (default is True):
    FORCE_ASCII = True

    # "user", "admin" and "root" are reserved usernames:
    RESERVED = set(["user", "root", "admin"])

    def check(self, username):
        """A more advanced check: Usernames must not end with a 'z'."""
        if username.endswith('z'):
            raise UsernameInvalid("Usernames must not end with a 'z'")

All you need to do to enable this validator is to put this validator in a .py file somewhere where the Python interpreter will find it and add the classpath to your VALIDATORS:

VALIDATORS = [
    # ...
    'some.path.myvalidators.MyOwnValidator',
]

Contribute validators

RestAuth is Free Software and invites everyone to contribute. Validators are a particular easy way to contribute to RestAuth. You do not even have to provide an implementation, you already provide great help if you just collect all the information necessary to implement a validator for the given system.

Please feel free to get in touch with us (see contribute) if you need RestAuth to provide a validator for an additional system.