diff --git a/manuscript/ha-docker-swarm/authelia.md b/manuscript/ha-docker-swarm/authelia.md new file mode 100644 index 0000000..b187303 --- /dev/null +++ b/manuscript/ha-docker-swarm/authelia.md @@ -0,0 +1,208 @@ +# Authelia + +[Authelia](https://github.com/authelia/authelia) is an open-source authentication and authorization server providing 2-factor authentication and single sign-on (SSO) for your applications via a web portal. It acts as a companion of reverse proxies like Nginx, Traefik, or HAProxy to let them know whether queries should pass through. Unauthenticated users are redirected to Authelia Sign-in portal instead. + +Authelia can be installed manually or can be installed using [Docker](https://hub.docker.com/r/authelia/authelia). + +Features include + +* Multiple two-factor methods such as + * [Physical Security Key](https://www.authelia.com/docs/features/2fa/security-key) (Yubikey) + * OTP using Google Authenticator + * Mobile Notifications +* Lockout users after too many failed login attempts +* Highly Customizable Access Control using rules to match criteria such as subdomain, username, groups the user is in, and Network +* Authelia [Community](https://discord.authelia.com/) Support +* Full list of features can be viewed [Here](https://www.authelia.com/docs/features/) + + +![Authelia Screenshot](../images/authelia.png) + +--8<-- "recipe-tfa-ingredients.md" + + + +## Preparation + +### Setup data locations + +First, we create a directory to hold the data which authelia will serve: + +``` +mkdir /var/data/config/authelia +cd /var/data/config/authelia +``` + +### Create config file + +Authelia configurations are defined in configuration.yml. + +```yml +############################################################### +# Authelia configuration # +############################################################### + +host: 0.0.0.0 +port: 9091 +log_level: warn + +# This secret can also be set using the env variables AUTHELIA_JWT_SECRET_FILE +# I used this site to generate the secret: https://www.grc.com/passwords.htm +jwt_secret: SECRET_GOES_HERE + +# https://docs.authelia.com/configuration/miscellaneous.html#default-redirection-url +default_redirection_url: https://authelia.example.com + +totp: + issuer: authelia.com + period: 30 + skew: 1 + +authentication_backend: + file: + path: /config/users_database.yml + # customize passwords based on https://docs.authelia.com/configuration/authentication/file.html + password: + algorithm: argon2id + iterations: 1 + salt_length: 16 + parallelism: 8 + memory: 1024 # blocks this much of the RAM. Tune this. + +# https://docs.authelia.com/configuration/access-control.html +access_control: + default_policy: one_factor + rules: + - domain: "*.example.com" + policy: one_factor + + - domain: "bitwarden.example.com" + policy: two_factor + +session: + name: authelia_session + # This secret can also be set using the env variables AUTHELIA_SESSION_SECRET_FILE + # Used a different secret, but the same site as jwt_secret above. + secret: SECRET_GOES_HERE + expiration: 3600 # 1 hour + inactivity: 300 # 5 minutes + domain: example.com # Should match whatever your root protected domain is + +regulation: + max_retries: 3 + find_time: 120 + ban_time: 300 + +storage: + local: + path: /config/db.sqlite3 + + +notifier: + smtp: + username: SMTP_USERNAME + # This secret can also be set using the env variables AUTHELIA_NOTIFIER_SMTP_PASSWORD_FILE + # password: # use docker secret file instead AUTHELIA_NOTIFIER_SMTP_PASSWORD_FILE + host: SMTP_HOST + port: 587 #465 + sender: SENDER_EMAIL + +# For testing purpose, notifications can be sent in a file. Be sure map the volume in docker-compose. +# filesystem: +# filename: /tmp/authelia/notification.txt + +``` + + +### Create User Accounts +Create users_database.yml this will be where we can create user accounts and give them groups + +```yaml +users: + username: + displayname: "Funky Penguin" + password: "HASHED_PASSWORD" + email: myemail@example.com + groups: + - admins + - dev +``` + +To create a hashed password you can run the following command +`docker run authelia/authelia:latest authelia hash-password YOUR_PASSWORD` + + + +### Setup Docker Swarm + +Create a docker swarm config file in docker-compose syntax (v3), something like this: + +--8<-- "premix-cta.md" + + +```yaml +version: "3.4" + +services: + authelia: + image: authelia/authelia:4.21.0 + volumes: + - /var/data/config/authelia:/config + networks: + - traefik_public + deploy: + labels: + - "traefik.enable=true" + - "traefik.http.routers.authelia.entrypoints=https" + - "traefik.http.routers.authelia.rule=Host(`authelia.example.com`)" + - "traefik.http.middlewares.authelia.forwardauth.address=http://authelia:9091/api/verify?rd=https://authelia.example.com" + - "traefik.http.middlewares.authelia.forwardauth.trustForwardHeader=true" + - "traefik.http.middlewares.authelia.forwardauth.authResponseHeaders=Remote-User, Remote-Groups" + - "traefik.http.services.authelia.loadbalancer.server.port=9091" + + +networks: + traefik_public: + external: true +``` + + +### Traefik Configuration + +Now that we have created authelia we will need to configure traefik so we can run authelia in front of our services. We will first need to create a traefik middleware in `/var/data/config/traefik/middlewares.yml` + + +```yaml +http: + middlewares: + forward-auth: + forwardAuth: + address: "http://authelia:9091/api/verify?rd=https://authelia.bencey.co.nz" + trustForwardHeader: true + authResponseHeaders: + - "Remote-User" + - "Remote-Groups" +``` + +We will then need to add the following to `traefik.toml` + +```yaml +[providers.file] + filename = "/etc/traefik/dynamic.yml" +``` + +Now if we wish to put authelia behind a service all we will need to do is add the following to the labels + +`- "traefik.http.routers.service.middlewares=forward-auth@file"` + + + + +## Serving + +### Launch the Authelia! + +Launch the Authelia stack by running ```docker stack deploy authelia -c ``` + + +--8<-- "recipe-footer.md" diff --git a/manuscript/images/authelia.png b/manuscript/images/authelia.png new file mode 100644 index 0000000..ab573d4 Binary files /dev/null and b/manuscript/images/authelia.png differ diff --git a/mkdocs.yml b/mkdocs.yml index 7943ecf..0b1efe8 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -49,6 +49,7 @@ nav: - Dex (static): ha-docker-swarm/traefik-forward-auth/dex-static.md - Google: ha-docker-swarm/traefik-forward-auth/google.md - KeyCloak: ha-docker-swarm/traefik-forward-auth/keycloak.md + - Authelia: ha-docker-swarm/authelia.md - Registry: ha-docker-swarm/registry.md - Mail Server: recipes/mail.md - Duplicity: recipes/duplicity.md