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

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

@@ -20,9 +20,17 @@ Features include
* Authelia [Community](https://discord.authelia.com/) Support * Authelia [Community](https://discord.authelia.com/) Support
* Full list of features can be viewed [here](https://www.authelia.com/docs/features/) * 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 ### Setup data locations
@@ -30,106 +38,113 @@ First, we create a directory to hold the data which authelia will serve:
```bash ```bash
mkdir /var/data/config/authelia 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 !!! 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. 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"
###############################################################
# Authelia configuration #
###############################################################
server: ```yaml
host: 0.0.0.0 ###############################################################
port: 9091 # Authelia configuration #
###############################################################
log: server:
level: warn host: 0.0.0.0
port: 9091
# This secret can also be set using the env variables AUTHELIA_JWT_SECRET_FILE log:
# I used this site to generate the secret: https://www.grc.com/passwords.htm level: warn
jwt_secret: SECRET_GOES_HERE
# https://docs.authelia.com/configuration/miscellaneous.html#default-redirection-url # This secret can also be set using the env variables AUTHELIA_JWT_SECRET_FILE
default_redirection_url: https://auth.example.com # I used this site to generate the secret: https://www.grc.com/passwords.htm
jwt_secret: SECRET_GOES_HERE
totp: # https://docs.authelia.com/configuration/miscellaneous.html#default-redirection-url
issuer: authelia.com default_redirection_url: https://authelia.example.com
period: 30
skew: 1
authentication_backend: totp:
file: issuer: authelia.example.com
path: /config/users_database.yml period: 30
# customize passwords based on https://docs.authelia.com/configuration/authentication/file.html skew: 1
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 authentication_backend:
access_control: file:
default_policy: one_factor path: /config/users_database.yml
rules: # customize passwords based on https://docs.authelia.com/configuration/authentication/file.html
- domain: "*.example.com" password:
policy: one_factor algorithm: argon2id
iterations: 1
salt_length: 16
parallelism: 8
memory: 1024 # blocks this much of the RAM. Tune this.
- domain: "bitwarden.example.com" # https://docs.authelia.com/configuration/access-control.html
policy: two_factor access_control:
default_policy: one_factor
rules:
- domain: "bitwarden.example.com"
policy: two_factor
session: - domain: "whoami-authelia-2fa.example.com"
name: authelia_session policy: two_factor
# 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: - domain: "*.example.com"
max_retries: 3 policy: one_factor
find_time: 120
ban_time: 300
storage:
encryption_key: SECRET_GOES_HERE
local:
path: /config/db.sqlite3
notifier: session:
smtp: name: authelia_session
username: SMTP_USERNAME # This secret can also be set using the env variables AUTHELIA_SESSION_SECRET_FILE
# This secret can also be set using the env variables AUTHELIA_NOTIFIER_SMTP_PASSWORD_FILE # Used a different secret, but the same site as jwt_secret above.
# password: # use docker secret file instead AUTHELIA_NOTIFIER_SMTP_PASSWORD_FILE secret: SECRET_GOES_HERE
host: SMTP_HOST expiration: 3600 # 1 hour
port: 587 #465 inactivity: 300 # 5 minutes
sender: SENDER_EMAIL domain: example.com # Should match whatever your root protected domain is
# For testing purpose, notifications can be sent in a file. Be sure map the volume in docker-compose. regulation:
# filesystem: max_retries: 3
# filename: /tmp/authelia/notification.txt find_time: 120
ban_time: 300
``` storage:
encryption_key: SECRET_GOES_HERE_20_CHARACTERS_OR_LONGER
local:
path: /config/db.sqlite3
### Create User Accounts
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: 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: /config/notification.txt
```
### 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 Create `/var/data/config/authelia/users_database.yml` this will be where we can create user accounts and give them groups
```yaml ```yaml
# To create a hashed password you can run the following command:
# `docker run authelia/authelia:latest authelia hash-password YOUR_PASSWORD``
users: users:
username: batman: # each new user should be defined in a dictionary like this
displayname: "Funky Penguin" displayname: "Batman"
password: "HASHED_PASSWORD" # replace this with your hashed password. This one, for the purposes of testing, is "password"
email: myemail@example.com password: "$argon2id$v=19$m=65536,t=3,p=4$cW1adlh3UjhIRE9zSmZyZw$xA4S2X8BjE7LVb4NndJCZnoyHgON5w3FopO4vw5AQxE"
email: batman@example.com
groups: groups:
- admins - admins
- dev - dev
@@ -138,102 +153,101 @@ users:
To create a hashed password you can run the following command To create a hashed password you can run the following command
`docker run authelia/authelia:latest authelia hash-password YOUR_PASSWORD` `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" --8<-- "premix-cta.md"
```yaml ???+ note "Much scroll, very YAML. Click here to collapse it for better readability"
version: "3.2"
```yaml
version: "3.2"
services:
authelia:
image: authelia/authelia
volumes:
- /var/data/config/authelia:/config
networks:
- traefik_public
deploy:
labels:
# traefik common
- traefik.enable=true
- traefik.docker.network=traefik_public
# traefikv1
- traefik.frontend.rule=Host:authelia.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.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://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-1fa:
image: containous/whoami
networks:
- traefik_public
deploy:
labels:
# traefik
- "traefik.enable=true"
- "traefik.docker.network=traefik_public"
# traefikv1
- "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-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"
services:
authelia:
image: authelia/authelia
volumes:
- /var/data/config/authelia:/config
networks: networks:
- traefik_public traefik_public:
deploy: external: true
labels: ```
# traefik common
- traefik.enable=true
- traefik.docker.network=traefik_public
# traefikv1
- traefik.frontend.rule=Host:auth.example.com
- traefik.port=80
- 'traefik.frontend.auth.forward.address=http://authelia:9091/api/verify?rd=https://auth.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.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"
# This simply validates that traefik forward authentication is working
whoami:
image: containous/whoami
networks:
- traefik_public
deploy:
labels:
# traefik
- "traefik.enable=true"
- "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"
# 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"
networks: !!! question "Why not just use Traefik Forward Auth?"
traefik_public: [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.
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"`
## Serving ## 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>``` 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" --8<-- "recipe-footer.md"