Quickstart to setting up RestAuth

This is a quickstart guide for getting RestAuth up and running. It assumes a simple setup with RestAuth as a Apache/WSGI application, a MySQL database and no complex settings.

Install RestAuth

Installation instructions are available for a variety of plattforms:

If your plattform is not listed here, you have to install from source.

Configure RestAuth

RestAuth has a central configuration file called localsettings.py. The location varies depending on how you installed RestAuth. Follow the previous link to get an overview where this file might me stored.

The configuration file is a plain Python file. Don’t worry if you have no experience writing Python, the syntax is pretty straight forward. Be careful of syntax errors, though, as this would cause hard-to-debug errors.

The only settings you really have to make are the DATABASES, SECRET_KEY and ALLOWED_HOSTS settings, which are almost at the beginning of the file. After your editing, the relevant sections should look like this:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.mysql', # Add 'postgresql_psycopg2', 'postgresql', 'mysql', 'sqlite3' or 'oracle'.
        'NAME': 'restauth', # Or path to database file if using sqlite3.
        'USER': 'restauth',                      # Not used with sqlite3.
        'PASSWORD': 'changeme',                  # Not used with sqlite3.
        'HOST': '',                      # Set to empty string for localhost. Not used with sqlite3.
        'PORT': '',                      # Set to empty string for default. Not used with sqlite3.

        # REMOVE THIS AFTER YOU CREATED YOUR DATABASE:
        'OPTIONS': {
            'init_command': 'SET storage_engine=INNODB',
        },
    }
}

# ...
SECRET_KEY = 'pleasechangethisstring'

ALLOWED_HOSTS = (
    '127.0.0.1',  # IP, i.e. if your setup allows local connections
    'auth.example.com',  # hostname used by your RestAuth server
)

Warning

Please do not forget to set the password for the database (line 6) and SECRET KEY (line 18) to some random string. The two strings should not be the same strings.

Feel free to look around the config-file, it has lots of comments to make it easy for you to customize RestAuth to your needs.

Create a database

The next step is creating your database (detailed instructions). This is done by two simple commands on the shell:

mysql -uroot -pYOUR_PASSWORD -e "CREATE DATABASE restauth CHARACTER SET utf8;"
mysql -uroot -pYOUR_PASSWORD -e "GRANT ALL PRIVILEGES ON restauth.* TO 'restauth'@'localhost' IDENTIFIED BY 'changeme';"

Warning

Please set the password (‘changeme’) to whatever you configured in your config-file.

On some systems (i.e. Debian based systems) there is no root-password for MySQL and you connect, as root system user, using a config-file. Here is an example for Debian/Ubuntu:

mysql --defaults-file=/etc/mysql/debian.cnf -e "CREATE DATABASE matitest CHARACTER SET utf8;"
mysql --defaults-file=/etc/mysql/debian.cnf -e "GRANT ALL PRIVILEGES ON restauth.* TO 'restauth'@'localhost' IDENTIFIED BY 'changeme';"

Setup database

Next you need to populate your database with the necessary tables. This couldn’t be simpler, using restauth-manage:

restauth-manage syncdb --noinput
restauth-manage migrate

Note

If you choose to use different backends, you still need to configure your database, as access restrictions are still managed in the database.

Configure Webserver

RestAuth is an HTTP based protocol, and every RestAuth implementation thus needs a webserver. The easiest way to setup RestAuth is using Apache and mod_wsgi, described in the following sections.

Note that more detailed documentation is available.

Add daemon user

Note

This step is not necessary if you installed using our Debian/Ubuntu packages, as the user is added automatically.

In this setup, RestAuth WSGI daemons run as a dedicated system user. Depending on the system, you first need to create this user:

adduser --system --group --home /path/to/sources --no-create-home --disabled-login restauth

The home-directory is basically irrelevant but it should exist.

Add Apache virtual host

Note

General Apache webserver setup is outside the scope of this document. Please consult the (excellent) Apache documentation for more information.

Next you need to actually configure your Webserver. It is recommended to add a dedicated virtual host. The exact locations of Apache webserver configuration files and what your basic (virtual) host setup is greatly depends on your plattform. Here are the relevant parts for RestAuth:

<VirtualHost *:443>
    # your basic configuration here...

    # Django/WSGI application (WSGIScriptAlias needs full path, see below)
    WSGIScriptAlias / /path/to/your/wsgi.py
    WSGIPassAuthorization on
    WSGIProcessGroup restauth
    WSGIDaemonProcess restauth user=restauth group=restauth processes=1 threads=10
</VirtualHost>

The wsgi-script (see line 5) is located in different locations depending on how you installed RestAuth:

  • from source: RestAuth/RestAuth/wsgi.py in your source folder
  • on Debian/Ubuntu: /usr/share/restauth/wsgi.py
  • on Redhat/Fedora: unkown.
  • on ArchLinux: /usr/share/restauth/wsgi.py

Note

If you have installed from source, RestAuth (or one of its depending libraries) are probably not in your python path. Please add them to the wsgi script. See the script itself for an example.

Don’t forget to restart your Apache after you’ve added the configuration.

Add services that use RestAuth

The final step to get a working RestAuth server is to add services to RestAuth. A service is a system (i.e. a Wiki, a CMS, a Unix system, ...) that uses RestAuth. RestAuth needs to know about the services using it, where they connect from and what they are allowed to do. Managing services is done via restauth-service. Adding a service works like this:

restauth-service add --gen-password wiki.example.com
restauth-service set-hosts 127.0.0.1
restauth-service set-permissions users_list user_verify_password user_change_password

In the above example the command in line 1 adds the service. A generated password is printed to standard output. Use these credentials in the configuration of the service that uses RestAuth. The command in line 2 specifies that the service connects from 127.0.0.1 (that is, it runs on the same machine as the RestAuth server). Line 3 specifies that the service is allowed to get a list of all users, verify and change user passwords.

Further reading

The most recommended pages in this documentation are: