public/geek-cookbook
1
0
Fork 0
mirror of https://github.com/funkypenguin/geek-cookbook/ synced 2025-12-18 04:01:46 +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

218
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,41 +38,42 @@ 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
###############################################################
# Authelia configuration #
###############################################################
server:
host: 0.0.0.0 host: 0.0.0.0
port: 9091 port: 9091
log: log:
level: warn level: warn
# This secret can also be set using the env variables AUTHELIA_JWT_SECRET_FILE # 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 # I used this site to generate the secret: https://www.grc.com/passwords.htm
jwt_secret: SECRET_GOES_HERE jwt_secret: SECRET_GOES_HERE
# https://docs.authelia.com/configuration/miscellaneous.html#default-redirection-url # 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: totp:
issuer: authelia.com issuer: authelia.example.com
period: 30 period: 30
skew: 1 skew: 1
authentication_backend: authentication_backend:
file: file:
path: /config/users_database.yml path: /config/users_database.yml
# customize passwords based on https://docs.authelia.com/configuration/authentication/file.html # customize passwords based on https://docs.authelia.com/configuration/authentication/file.html
@@ -75,17 +84,21 @@ authentication_backend:
parallelism: 8 parallelism: 8
memory: 1024 # blocks this much of the RAM. Tune this. memory: 1024 # blocks this much of the RAM. Tune this.
# https://docs.authelia.com/configuration/access-control.html # https://docs.authelia.com/configuration/access-control.html
access_control: access_control:
default_policy: one_factor default_policy: one_factor
rules: rules:
- domain: "*.example.com"
policy: one_factor
- domain: "bitwarden.example.com" - domain: "bitwarden.example.com"
policy: two_factor policy: two_factor
session: - domain: "whoami-authelia-2fa.example.com"
policy: two_factor
- domain: "*.example.com"
policy: one_factor
session:
name: authelia_session name: authelia_session
# 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_SESSION_SECRET_FILE
# Used a different secret, but the same site as jwt_secret above. # Used a different secret, but the same site as jwt_secret above.
@@ -94,42 +107,44 @@ session:
inactivity: 300 # 5 minutes inactivity: 300 # 5 minutes
domain: example.com # Should match whatever your root protected domain is domain: example.com # Should match whatever your root protected domain is
regulation: regulation:
max_retries: 3 max_retries: 3
find_time: 120 find_time: 120
ban_time: 300 ban_time: 300
storage: storage:
encryption_key: SECRET_GOES_HERE encryption_key: SECRET_GOES_HERE_20_CHARACTERS_OR_LONGER
local: local:
path: /config/db.sqlite3 path: /config/db.sqlite3
notifier: notifier:
smtp: # smtp:
username: SMTP_USERNAME # username: SMTP_USERNAME
# This secret can also be set using the env variables AUTHELIA_NOTIFIER_SMTP_PASSWORD_FILE # # 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 # # password: # use docker secret file instead AUTHELIA_NOTIFIER_SMTP_PASSWORD_FILE
host: SMTP_HOST # host: SMTP_HOST
port: 587 #465 # port: 587 #465
sender: SENDER_EMAIL # 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. # For testing purpose, notifications can be sent in a file. Be sure map the volume in docker-compose.
# filesystem: filesystem:
# filename: /tmp/authelia/notification.txt filename: /config/notification.txt
```
``` ### Create Authelia user Accounts
### Create 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,16 +153,18 @@ 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"
services: ```yaml
version: "3.2"
services:
authelia: authelia:
image: authelia/authelia image: authelia/authelia
volumes: volumes:
@@ -161,22 +178,22 @@ services:
- traefik.docker.network=traefik_public - traefik.docker.network=traefik_public
# traefikv1 # traefikv1
- traefik.frontend.rule=Host:auth.example.com - traefik.frontend.rule=Host:authelia.example.com
- traefik.port=80 - 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.trustForwardHeader=true'
- 'traefik.frontend.auth.forward.authResponseHeaders=Remote-User,Remote-Groups,Remote-Name,Remote-Email' - 'traefik.frontend.auth.forward.authResponseHeaders=Remote-User,Remote-Groups,Remote-Name,Remote-Email'
# traefikv2 # 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.routers.authelia.entrypoints=https"
- "traefik.http.services.authelia.loadbalancer.server.port=9091" - "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.address=http://authelia:9091/api/verify?rd=https://authelia.example.com"
- "traefik.http.middlewares.authelia.forwardauth.trustForwardHeader=true" # - "traefik.http.middlewares.authelia.forwardauth.trustForwardHeader=true"
- "traefik.http.middlewares.authelia.forwardauth.authResponseHeaders=Remote-User, Remote-Groups" # - "traefik.http.middlewares.authelia.forwardauth.authResponseHeaders=Remote-User, Remote-Groups"
# This simply validates that traefik forward authentication is working # This simply validates that traefik forward authentication is working
whoami: whoami-1fa:
image: containous/whoami image: containous/whoami
networks: networks:
- traefik_public - traefik_public
@@ -187,53 +204,50 @@ services:
- "traefik.docker.network=traefik_public" - "traefik.docker.network=traefik_public"
# traefikv1 # traefikv1
- "traefik.frontend.rule=Host:whoami.example.com" - "traefik.frontend.rule=Host:whoami-authelia-1fa.example.com"
- "traefik.http.services.whoami.loadbalancer.server.port=80" - 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.authResponseHeaders=X-Forwarded-User" - 'traefik.frontend.auth.forward.trustForwardHeader=true'
- "traefik.frontend.auth.forward.trustForwardHeader=true" - 'traefik.frontend.auth.forward.authResponseHeaders=Remote-User,Remote-Groups,Remote-Name,Remote-Email'
# traefikv2 # traefikv2
- "traefik.http.routers.whoami.rule=Host(`whoami.example.com`)" - "traefik.http.routers.whoami-authelia-1fa.rule=Host(`whoami-authelia-1fa.example.com`)"
- "traefik.http.routers.whoami.entrypoints=https" - "traefik.http.routers.whoami-authelia-1fa.entrypoints=https"
- "traefik.http.services.whoami.loadbalancer.server.port=80" - "traefik.http.routers.whoami-authelia-1fa.middlewares=authelia"
- "traefik.http.routers.whoami.middlewares=forward-auth@file" - "traefik.http.services.whoami-authelia-1fa.loadbalancer.server.port=80"
networks: 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: traefik_public:
external: true 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` !!! 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.
```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"