Enabling authentication

Sausagewiki itself does not implement authentication or authorization. In this document we will explore how to meaningfully add this in front of Sausagewiki using nginx.

1. Basic Auth
   1. Limit writes only
2. Third party authentication providers

Basic Auth

The simplest scheme is to enable HTTP Basic Authentication. Your location section in your nginx config should look something like this:

location / {
    proxy_pass http://127.0.0.1:7777/;
    proxy_http_version 1.1;
}

To add Basic Authentication, add the following lines inside this section:

    auth_basic 'Restricted';
    auth_basic_user_file /etc/nginx/basic_auth;

/etc/nginx/basic_auth could be any file path. It should contain a list of username and password pairs, separated by :, one pair per line. The passwords are hashed, and you can generate hashes with the command line openssl passwd -apr1:

USER=...
PASSWORD="$(openssl passwd -apr1)"
echo "$USER:$PASSWORD" >> /etc/nginx/basic_auth

This sets up your wiki instance to require login for any access.

Recording authors

Sausagewiki can also record the given username as the author of any changes to the wiki. To enable this, we need to make two changes:

1. Add proxy_set_header X-Identity $remote_user; to the nginx config
2. Add --trust-identity to the command line arguments of Sausagewiki. This flag instructs Sausagewiki to trust that the HTTP header X-Identity contains the correct username. This is only safe when there is a reverse proxy in front of Sausagewiki that always sets this header.

Our nginx config now looks more like this:

location / {
    auth_basic 'Restricted';
    auth_basic_user_file /etc/nginx/basic_auth;

    proxy_pass http://127.0.0.1:7777/;
    proxy_http_version 1.1;
    proxy_set_header X-Identity $remote_user;
}

Limit writes only

Many wikis are open for reading and require login for editing. To set this up with nginx, we can use the limit_except directive:

location / {
    limit_except GET HEAD OPTIONS {
        auth_basic 'Restricted';
        auth_basic_user_file /etc/nginx/basic_auth;
    }

    proxy_pass http://127.0.0.1:7777/;
    proxy_http_version 1.1;
    proxy_set_header X-Identity $remote_user;
}

Third-party authentication providers

For other authentication schemes, it is possible to use third party modules:

1. oauth2_proxy implements support for many authentication providers and works well with nginx
2. Custom authentication providers can be invoked with nginx's auth_request directive