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. Recording authors
   2. Limit writes only
2. Third party authentication providers
   1. Recording authors
   2. Limit writes only

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

Recording authors

For a setup with auth_request you can extract the relevant user identity information from the HTTP response headers from the authentication provider:

auth_request_set $user $upstream_http_x_auth_request_user;

This directive instructs nginx to set the variable $user to the contents of the X-Auth-Request-User header in the response from your chosen authentication provider. The correct header name depends on the authentication provider, adjust as necessary.

To forward this value to Sausagewiki, set it in the X-Identity header.

proxy_set_header X-Identity $user;

Sausagewiki must be started with the --trust-identity command line argument to read this value.

With this configured, all changes to the wiki will be signed with the signed in user name.

Limit writes only

The limit_except directive we used with Basic authentication above only works with auth_basic and not with auth_request. To limit write-access only, the authentication provider has to implement this feature.