public/geek-cookbook
1
0
Fork 0
mirror of https://github.com/funkypenguin/geek-cookbook/ synced 2025-12-15 18:56:24 +00:00
Code Issues Releases Wiki Activity

Improve Authelia recipe

Browse Source 
Signed-off-by: David Young <davidy@funkypenguin.co.nz>
This commit is contained in:
David Young
2022-07-26 14:27:06 +12:00
parent c78e30dcaa
commit ae1c6425d5
1 changed files with 183 additions and 167 deletions
Download Patch File Download Diff File Expand all files Collapse all files

168
manuscript/docker-swarm/authelia.md
View File

@@ -20,9 +20,17 @@ Features include
* Authelia [Community](https://discord.authelia.com/) Support
* Full list of features can be viewed [here](https://www.authelia.com/docs/features/)
--8<-- "recipe-tfa-ingredients.md"
## Authelia requirements
## Preparation
!!! summary "Ingredients"
Already deployed:
* [X] [Docker swarm cluster](/docker-swarm/design/) with [persistent shared storage](/docker-swarm/shared-storage-ceph/)
* [X] [Traefik](/docker-swarm/traefik/) configured per design
New:
* [ ] DNS entry for your auth host (*"authelia.yourdomain.com" is a good choice*), pointed to your [keepalived](/docker-swarm/keepalived/) IP
### Setup data locations
@@ -30,17 +38,18 @@ First, we create a directory to hold the data which authelia will serve:
```bash
mkdir /var/data/config/authelia
cd /var/data/config/authelia
```
### Create config file
### Create Authelia config file
Authelia configurations are defined in `/var/data/config/authelia/configuration.yml`. Some are required and some are optional. So begin by creating an empty configuration.yml file and add content to it as defined below. Optional configuration settings can be viewed on Authelia's [Documentation](https://www.authelia.com/docs/configuration/)
Authelia configurations are defined in `/var/data/config/authelia/configuration.yml`. Some are required and some are optional. The following is a variation of the default example config file. Optional configuration settings can be viewed on in [Authelia's documentation](https://www.authelia.com/docs/configuration/)
!!! warning
Your variables may vary significantly from what's illustrated below, and it's best to read up and understand exactly what each option does.
```yml
???+ note "Much scroll, very text. Click here to collapse it for better readability"
```yaml
###############################################################
# Authelia configuration #
###############################################################
@@ -57,10 +66,10 @@ log:
jwt_secret: SECRET_GOES_HERE
# https://docs.authelia.com/configuration/miscellaneous.html#default-redirection-url
default_redirection_url: https://auth.example.com
default_redirection_url: https://authelia.example.com
totp:
issuer: authelia.com
issuer: authelia.example.com
period: 30
skew: 1
@@ -79,11 +88,15 @@ authentication_backend:
access_control:
default_policy: one_factor
rules:
- domain: "bitwarden.example.com"
policy: two_factor
- domain: "whoami-authelia-2fa.example.com"
policy: two_factor
- domain: "*.example.com"
policy: one_factor
- domain: "bitwarden.example.com"
policy: two_factor
session:
name: authelia_session
@@ -100,36 +113,38 @@ regulation:
ban_time: 300
storage:
encryption_key: SECRET_GOES_HERE
encryption_key: SECRET_GOES_HERE_20_CHARACTERS_OR_LONGER
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
# 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: batman@example.com # customize for your setup
# For testing purpose, notifications can be sent in a file. Be sure map the volume in docker-compose.
# filesystem:
# filename: /tmp/authelia/notification.txt
filesystem:
filename: /config/notification.txt
```
### Create User Accounts
### Create Authelia user Accounts
Create `/var/data/config/authelia/users_database.yml` this will be where we can create user accounts and give them groups
```yaml
# To create a hashed password you can run the following command:
# `docker run authelia/authelia:latest authelia hash-password YOUR_PASSWORD``
users:
username:
displayname: "Funky Penguin"
password: "HASHED_PASSWORD"
email: myemail@example.com
batman: # each new user should be defined in a dictionary like this
displayname: "Batman"
# replace this with your hashed password. This one, for the purposes of testing, is "password"
password: "$argon2id$v=19$m=65536,t=3,p=4$cW1adlh3UjhIRE9zSmZyZw$xA4S2X8BjE7LVb4NndJCZnoyHgON5w3FopO4vw5AQxE"
email: batman@example.com
groups:
- admins
- dev
@@ -138,12 +153,14 @@ users:
To create a hashed password you can run the following command
`docker run authelia/authelia:latest authelia hash-password YOUR_PASSWORD`
### Setup Docker Swarm
### Authelia Docker Swarm config
Create a docker swarm config file in docker-compose syntax (v3), something like this:
Create a docker swarm config file in docker-compose syntax (v3), something like this example:
--8<-- "premix-cta.md"
???+ note "Much scroll, very YAML. Click here to collapse it for better readability"
```yaml
version: "3.2"
@@ -161,22 +178,22 @@ services:
- traefik.docker.network=traefik_public
# traefikv1
- traefik.frontend.rule=Host:auth.example.com
- traefik.frontend.rule=Host:authelia.example.com
- traefik.port=80
- 'traefik.frontend.auth.forward.address=http://authelia:9091/api/verify?rd=https://auth.example.com/'
- 'traefik.frontend.auth.forward.address=http://authelia:9091/api/verify?rd=https://authelia.example.com/'
- 'traefik.frontend.auth.forward.trustForwardHeader=true'
- 'traefik.frontend.auth.forward.authResponseHeaders=Remote-User,Remote-Groups,Remote-Name,Remote-Email'
# traefikv2
- "traefik.http.routers.authelia.rule=Host(`auth.example.com`)"
- "traefik.http.routers.authelia.rule=Host(`authelia.example.com`)"
- "traefik.http.routers.authelia.entrypoints=https"
- "traefik.http.services.authelia.loadbalancer.server.port=9091"
- "traefik.http.middlewares.authelia.forwardauth.address=http://authelia:9091/api/verify?rd=https://auth.example.com"
- "traefik.http.middlewares.authelia.forwardauth.trustForwardHeader=true"
- "traefik.http.middlewares.authelia.forwardauth.authResponseHeaders=Remote-User, Remote-Groups"
# - "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"
# This simply validates that traefik forward authentication is working
whoami:
whoami-1fa:
image: containous/whoami
networks:
- traefik_public
@@ -187,53 +204,50 @@ services:
- "traefik.docker.network=traefik_public"
# traefikv1
- "traefik.frontend.rule=Host:whoami.example.com"
- "traefik.http.services.whoami.loadbalancer.server.port=80"
- "traefik.frontend.auth.forward.address=http://authelia:9091/api/verify?rd=https://auth.example.com"
- "traefik.frontend.auth.forward.authResponseHeaders=X-Forwarded-User"
- "traefik.frontend.auth.forward.trustForwardHeader=true"
- "traefik.frontend.rule=Host:whoami-authelia-1fa.example.com"
- traefik.port=80
- 'traefik.frontend.auth.forward.address=http://authelia:9091/api/verify?rd=https://authelia.example.com/'
- 'traefik.frontend.auth.forward.trustForwardHeader=true'
- 'traefik.frontend.auth.forward.authResponseHeaders=Remote-User,Remote-Groups,Remote-Name,Remote-Email'
# traefikv2
- "traefik.http.routers.whoami.rule=Host(`whoami.example.com`)"
- "traefik.http.routers.whoami.entrypoints=https"
- "traefik.http.services.whoami.loadbalancer.server.port=80"
- "traefik.http.routers.whoami.middlewares=forward-auth@file"
- "traefik.http.routers.whoami-authelia-1fa.rule=Host(`whoami-authelia-1fa.example.com`)"
- "traefik.http.routers.whoami-authelia-1fa.entrypoints=https"
- "traefik.http.routers.whoami-authelia-1fa.middlewares=authelia"
- "traefik.http.services.whoami-authelia-1fa.loadbalancer.server.port=80"
whoami-2fa:
image: containous/whoami
networks:
- traefik_public
deploy:
labels:
# traefik
- "traefik.enable=true"
- "traefik.docker.network=traefik_public"
# traefikv1
- "traefik.frontend.rule=Host:whoami-authelia-2fa.example.com"
- traefik.port=80
- 'traefik.frontend.auth.forward.address=http://authelia:9091/api/verify?rd=https://authelia.example.com/'
- 'traefik.frontend.auth.forward.trustForwardHeader=true'
- 'traefik.frontend.auth.forward.authResponseHeaders=Remote-User,Remote-Groups,Remote-Name,Remote-Email'
# traefikv2
- "traefik.http.routers.whoami-authelia-2fa.rule=Host(`whoami-authelia-2fa.example.com`)"
- "traefik.http.routers.whoami-authelia-2fa.entrypoints=https"
- "traefik.http.routers.whoami-authelia-2fa.middlewares=authelia"
- "traefik.http.services.whoami-authelia-2fa.loadbalancer.server.port=80"
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://auth.example.com"
trustForwardHeader: true
authResponseHeaders:
- "Remote-User"
- "Remote-Groups"
```
We will then need to add the following to `traefik.toml`
```yaml
[providers.file]
filename = "/etc/traefik/middlewares.yml"
```
!!! Why not just use Traefik Forward Auth
The default Traefik forward Auth is a very minimal authentication service that provides google and openID authentication. Authelia provides more features such as multiple methods of authentication (Hardware, OTP, Email) and push notifications.
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"`
!!! question "Why not just use Traefik Forward Auth?"
[Traefik Forward Auth][tfa] is a very minimal authentication layer that provides google and openID authentication. Authelia provides more features such as multiple methods of authentication (*Hardware, OTP, Email*) and push notifications.
## Serving
@@ -241,12 +255,14 @@ Now if we wish to put authelia behind a service all we will need to do is add th
Launch the Authelia stack by running ```docker stack deploy authelia -c <path -to-docker-compose.yml>```
## Testing
## Test Authelia
To test the service works successfully. Try to access a service that you had added the middleware label to. If it works successfully you will be presented with a login screen
To test the service works successfully, try logging into authelia itself first, as a user whose password you've setup in `/var/data/config/authelia/users_database.yml`. You'll notice that upon successful login, you're requested to setup 2FA. You probably didn't configure an SMTP server, but the contents of the email request should be found in ``/var/data/config/authelia/notifications.txt`
![Authelia Screenshot](../images/authelia_login.png){ loading=lazy }
Now you're ready to test 1FA and 2FA auth, against the two "whoami" services defined in the docker-compose file.
[^1]: The inclusion of Authelia was due to the efforts of @bencey in Discord (Thanks Ben!)
Try to access each in turn, and confirm that you're _not_ prompted for 2FA on whoami-authelia-1fa, but you _are_ prompted for 2FA on whoami-authelia-2fa ;)
[^1]: The initial inclusion of Authelia was due to the efforts of @bencey in Discord (Thanks Ben!)
--8<-- "recipe-footer.md"