A very lightweight authentication service for Traefik

Boréale is a tiny and simple self-hosted service to handle forward authentication for services behind Traefik reverse proxy.

• Very lightweight, less than 60 MB.
• User can use a custom login page.
• SSO for all subdomains.
• Has no external dependencies.
• Easy management through the Boréale CLI.
• Secure and encrypted cookie.
• Easy to deploy.

Traefik currently supports some authentication schemes like basic auth and digest. While these works great, they are very limited, non-customizable and requires to log in each time you restart your browser.

There exists many services similar to Boréale, but they either rely on external services like Google OAuth, LDAP, keycloak, etc, or pack many features that are more suitable for a large organization.

The main goal of Boréale is to have a tiny self-contained solution that is more appropriate for a home server usage.

• Authelia If you are looking for a complete solution for organizations.

• Traefik Forward Auth If you are looking for a Google OAuth-based authentication.

Boréale is written in Elixir and compiled using Distillery. This allows for self-contained executable (named OTP releases) that can be run anywhere, without relying on the Elixir and Erlang environements.

As such, you can simply download the release from GitHub releases and directly run it.

To start it, simply run ./bin/boreale foreground

To start it in a background processs, simply run ./bin/boreale start

Note: Make sure all required environment variables are set before launching the app. You can see a list of all the variables here. How the environment variables are set is entirely up to you.

While the OTP release is nice and very easy to use, it has the downside of needing to be compiled on an environment similar to the target environment. Currently, I only provide binaries compiled on Ubuntu 18.04 and MacOS Mojave.

This is why the recommended method for deploying Boréale is through Docker. The provided Docker image still uses an OTP release internally, but the release is actually compiled in the image build process. This has the advantage of having the same environment for running and compiling the release. The overall size is still very small, currently sitting at 58 MB.

The easiest way to get started with the Docker release is using docker-compose. First, create a directory for the Boréale configurations to live in. It can be anywhere. Since I use an unRAID system, I put mine with my other docker applications in /mnt/user/appdata.

So inside /mnt/user/appdata/boreale, place the .env and docker-compose.yml files from the examples here and edit them accordingly. Avoid leaving empty variables inside the .env. Check all the variables here to see which ones are required or optional.

Create a data directory inside the previous directory for the docker volume. For me that would be /mnt/user/appdata/boreale/data. You can name it however you want as long as the correct name is set in the docker-compose.yml file.

Run docker-compose up to launch Boréale.

Of course using docker-compose is optional. You can use any containers manager you wish. Here's an example on how to run it directly from the docker CLI. Check the docker-compose section for more info on the .env file and data/ directory.

docker run \
  --name=boreale \
  --env-file <path to .env file> \
  -p 5252:4000 \
  -v <path to data/ dir>:/opt/app/data \
  lewazo/boreale

While Boréale isn't available on the Community Applications plugin, you can still install it and use it the same way as any other Docker containers installed with CA by using my template.

Most of the Boréale configuration is done through its CLI. To use the CLI, follow the instructions below depending on your environement.

When using the OTP release, simply run ./bin/boreale cli to access the CLI.

When using docker-compose, simply run docker-compose exec boreale bin/boreale cli in the same directory as your docker-compose.yml file.

When using the Docker CLI, you first need to get the container's ID. Run docker ps and find the container that has the lewazo/boreale image. Then, run docker exec -it <CONTAINER ID> bin/boreale cli.

In order for Traefik to forward the authentication to Boréale, there are some configurations that needs to be done.

In your traefik.toml, add the following lines under [entryPoints.https.tls].

[entryPoints.https.auth.forward]
    address = "https://127.0.0.1:5252"
    [entryPoints.https.auth.forward.tls]
      insecureSkipVerify = true

Edit 127.0.0.1 for the IP of the host that runs Boréale. Match the port with the one defined in your docker-compose.yml or equivalent.

We use insecureSkiVerify = true so Traefik can trust our self-signed certificate. More info on that here.

SSO (Single sign-on) can be achieved using the domain cookie attribute. If your services are setup by subdomains like service1.domain.tld, service2.domain.tld, then you can use the SSO feature. If you use completely different domains like service1-domain.tld and service2-domain.tld then this won't work because of the same origin policy.

To enable SSO, set the SSO_DOMAIN_NAME environment variable to your root domain, e.g., domain.tld. This will make all *.domain.tld and domain.tld requests share the same cookie. So a user only has to login to one service. The user will then be authentified on every other services.

Not setting the variable will disable SSO.

An authorized user is a user who's allowed to log in and access all the web services behind Traefik.

To list all authorized users, use the CLI's users command.

To add a new user, use the CLI's users add command.

To delete a user, use the CLI's users remove command.

A public domain is a FQDN that is meant to access a public server, i.e., it shouldn't ask for any authentication when visiting that domain.

To list all public domains, use the CLI's domains command.

To add a new public domain, use the CLI's domains add command.

To delete a public domain, use the CLI's domains remove command.

These are the environment variables that should be set in your .env file or set in your environment.

Boréale ships with a default login form, but using your own is very easy.

Simply add a login.html and login.css inside the data/ directory and it will be automatically used. The only constraints is to have username and password inputs and a form with the id form. Take a look at the examples here to see the code for the default login form.

The following screenshot shows the default login form.

Boréale is meant to be accessed directly by forwarding the auth. As such, you should not add it as a backend in Traefik, i.e., you should not have a boreale.yourdomain.tld or anything.

With this premise in mind, Boréale automatically creates a self-signed certificate in order to provide a complete HTTPS connection between Traefik and Boréale. This allows the server to set a secure cookie on the browser.

Since Boréale is only accessed through Traefik's authentication, using a self-signed certificate is perfectly fine if you trust your private network.

To protect your services from cookie hijacking and protocol downgrade attacks, you should have HSTS enabled. Since Traefik is the one that's terminating the connection, HSTS should be enabled on it rather than on Boréale.

The source code and binaries of Boréale is subject to the MIT License.

The above logo is made by perdanakun and is available here and subject to the Creative Commons BY 3.0 license.