What you will set up
authentik is an identity provider: it holds your users, their passwords and their second factors, and your apps let authentik check who is logging in. Each person has one account for everything, and when someone leaves, you turn off one account instead of one in every app. Apps connect to it with OpenID Connect, SAML or LDAP, which most self-hosted apps support.
Here it runs in a pod with PostgreSQL, under a user of its own called authentik, behind Caddy from the Podman guide. As an example, it becomes the login for the Matrix server from the Matrix guide.
Every step below was run on a Melonslab server with Debian 13:
- The first setup was done through an SSH tunnel, before authentik was on the internet, and authentik logged the new admin in straight away. Behind Caddy, authentik's event log showed each visitor's real address.
- A user created in the admin interface logged in to Matrix with single sign-on, and got a Matrix account with their name. An existing Matrix account was linked the same way.
- With two-factor authentication required, a user without an authenticator app had to set one up at their next login. After that, logging in asked for a code, and a wrong code was refused.
- A new password shorter than 12 characters was refused, and after five failed logins the right password was refused too.
- authentik's test email arrived at a test mail catcher on the server.
- An uploaded file was still there after a restart, and everything came back by itself after a reboot. authentik was restored from a backup into an empty database, and the user logged in with the same password and code.
authentik used between 700 MB and 1 GB of memory, and PostgreSQL about 30 MB. It needs at least 2 GB on the server.
authentik's interface and emails are not available in Swedish. It has, for example, Norwegian, Finnish and German, and shows English to a browser set to Swedish.
Before you start
You need:
- a server set up as in the Podman guide, with Caddy running, and at least 2 GB of memory;
- an A record and an AAAA record for
auth.example.compointing at your server; - an email account that can send through your email provider's SMTP server, such as
auth@example.com.
The examples use auth.example.com for authentik and 203.0.113.10 for your server's IPv4 address, which ip -brief address show eth0 shows. Replace them throughout.
1. Create the user
As root:
useradd -m -s /bin/bash authentik
loginctl enable-linger authentik
machinectl shell authentik@
Steps 2 to 4 run as authentik.
2. Create the secrets
openssl rand -hex 24 | tr -d '\n' | podman secret create authentik-db-password -
openssl rand -base64 60 | tr -d '\n' | podman secret create authentik-secret-key -
The first is the database password. The second is authentik's secret key, which signs its sessions and tokens. Neither is written into the files below.
3. Describe the pod
mkdir -p ~/.config/containers/systemd ~/authentik/data
podman unshare chown 1000:1000 ~/authentik/data
authentik runs as user 1000 inside its containers, and the chown lets that user write to the data folder, where authentik keeps files you upload, such as app icons.
Create ~/.config/containers/systemd/authentik.pod:
[Pod]
PodName=authentik
# Only Caddy, on this server, can reach authentik: the port is not open to the internet.
PublishPort=127.0.0.1:8092:9000
ShmSize=512m
[Install]
WantedBy=default.target
Create ~/.config/containers/systemd/authentik-db.container:
[Container]
ContainerName=authentik-db
Image=docker.io/library/postgres:18-alpine
Pod=authentik.pod
Volume=authentik-db:/var/lib/postgresql
Environment=POSTGRES_USER=authentik POSTGRES_DB=authentik
Secret=authentik-db-password,type=env,target=POSTGRES_PASSWORD
AutoUpdate=registry
[Service]
Restart=always
Create ~/.config/containers/systemd/authentik-server.container:
[Unit]
After=authentik-db.service
[Container]
ContainerName=authentik-server
Image=ghcr.io/goauthentik/server:2026.8
Pod=authentik.pod
Exec=server
EnvironmentFile=%h/authentik/authentik.env
Secret=authentik-db-password,type=env,target=AUTHENTIK_POSTGRESQL__PASSWORD
Secret=authentik-secret-key,type=env,target=AUTHENTIK_SECRET_KEY
Volume=%h/authentik/data:/data
AutoUpdate=registry
[Service]
Restart=always
Create ~/.config/containers/systemd/authentik-worker.container:
[Unit]
After=authentik-db.service
[Container]
ContainerName=authentik-worker
Image=ghcr.io/goauthentik/server:2026.8
Pod=authentik.pod
Exec=worker
EnvironmentFile=%h/authentik/authentik.env
# The server already uses these ports in the pod.
Environment=AUTHENTIK_LISTEN__HTTP=[::]:9001 AUTHENTIK_LISTEN__METRICS=[::]:9301
Secret=authentik-db-password,type=env,target=AUTHENTIK_POSTGRESQL__PASSWORD
Secret=authentik-secret-key,type=env,target=AUTHENTIK_SECRET_KEY
Volume=%h/authentik/data:/data
AutoUpdate=registry
[Service]
Restart=always
And ~/authentik/authentik.env, the settings both share:
AUTHENTIK_POSTGRESQL__HOST=127.0.0.1
AUTHENTIK_POSTGRESQL__USER=authentik
AUTHENTIK_POSTGRESQL__NAME=authentik
# Caddy's connections reach the pod from the server's own IPv4 address.
AUTHENTIK_LISTEN__TRUSTED_PROXY_CIDRS=203.0.113.10/32
The server answers web requests, and the worker runs background tasks. Both run the same image. In a pod they share one network, so the worker's two ports are moved away from the server's. authentik trusts the address Caddy sends for each visitor only from the addresses in TRUSTED_PROXY_CIDRS, and with rootless Podman, Caddy's connections come from the server's own IPv4 address.
The tag 2026.8 gets every fix to authentik 2026.8. Step 12 covers moving to the next version.
4. Start it
systemctl --user daemon-reload
systemctl --user start authentik-pod
The first start downloads the images, and then authentik sets up its database, which took about three minutes on our test server. Check it:
curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8092/-/health/ready/
It answers 503 while authentik is still starting, and 200 when it is ready. Until then, the worker's log shows warnings about missing tables, which stop by themselves.
5. Create the admin account
Until the admin account has a password, whoever opens authentik first gets to set it. That is why its port is on 127.0.0.1 only, and why you do this through SSH, before Caddy puts authentik on the internet. From your own computer:
ssh -L 8092:127.0.0.1:8092 root@203.0.113.10
Keep that session open, and open http://localhost:8092 in your browser. authentik shows its first setup page for its admin user, akadmin. Enter your email address and a strong password twice. Base URL shows the tunnel's address, http://localhost:8092: change it to https://auth.example.com, and choose Continue.
authentik logs you in as akadmin straight away, and the setup page is closed from then on. Close the SSH session.
6. Put Caddy in front
Go back to root with exit, switch to machinectl shell caddy@, and add this block at the end of ~/Caddyfile:
auth.example.com {
reverse_proxy 127.0.0.1:8092
}
Restart Caddy with systemctl --user restart caddy. Log in at https://auth.example.com as akadmin. The admin interface is at https://auth.example.com/if/admin/.
7. Add your users
In the admin interface:
- Open Directory, then Users, and choose New User.
- Choose Internal User, and enter a Username, a Display Name and an Email Address. Choose Create.
- Choose the new user in the list. Under Recovery, choose Set password, enter a password, and choose Set Password.
The person logs in at https://auth.example.com, and can change the password under the gear icon, in User details.
8. Email
authentik sends email from flows that have an email stage, such as a password reset or an email confirmation at sign-up, and for notifications you choose to get by email. The setup in this guide has none of those yet, so nothing stops working without email. Set it up before you add such a flow.
As authentik, store the SMTP password as a secret:
printf %s 'the-smtp-password' | podman secret create authentik-email-password -
Add these lines to ~/authentik/authentik.env, with your own server, account and sender address:
AUTHENTIK_EMAIL__HOST=smtp.example.com
AUTHENTIK_EMAIL__PORT=587
AUTHENTIK_EMAIL__USE_TLS=true
AUTHENTIK_EMAIL__USERNAME=auth@example.com
AUTHENTIK_EMAIL__FROM=auth@example.com
And add this line to both authentik-server.container and authentik-worker.container, under the other Secret lines:
Secret=authentik-email-password,type=env,target=AUTHENTIK_EMAIL__PASSWORD
Restart, wait for the health check from step 4 to answer 200, and send a test email:
systemctl --user daemon-reload
systemctl --user restart authentik-server authentik-worker
podman exec authentik-worker ak test_email you@example.com
USE_TLS=true on port 587 uses STARTTLS. For port 465, which uses TLS from the start, set the port to 465 and replace AUTHENTIK_EMAIL__USE_TLS=true with AUTHENTIK_EMAIL__USE_SSL=true. We sent the test email to a test mail catcher on the server, not through a real email provider.
9. Require two-factor authentication
Out of the box, two-factor authentication is up to each person. To require it for everyone, open Flows and Stages, then Stages, in the admin interface, and edit default-authentication-mfa-validation:
- Under Device classes, keep Static Tokens, TOTP Authenticators and WebAuthn Authenticators.
- Set Not configured action to Force the user to configure an authenticator.
- Under Configuration stages, move default-authenticator-totp-setup to Selected Stages.
- Choose Update.
At their next login, after the password, everyone without an authenticator, akadmin too, sees a QR code. They scan it with an authenticator app, such as the one built into their phone's password manager, and enter the code it shows. From then on, authentik asks for a code from the app after the password.
Under the gear icon, then Credentials and MFA Devices, each person can add a WebAuthn device, for passkeys and security keys, and Static tokens, one-time codes to print and keep in case the phone is lost.
10. Passwords and failed logins
authentik comes with a password policy, default-password-change-password-policy, which checks new passwords when people change their own. It asks for 8 characters and rejects easily guessed passwords. To ask for 12, open Customization, then Policies, edit the policy, set Minimum length to 12, and choose Update. Leave Check haveibeenpwned.com off unless you want authentik to send the start of each new password's hash to that service. Passwords you set for someone under Set password in the admin interface are not checked, so make those long.
authentik has no lockout counter as such. It keeps a reputation score for each username and address: each failed login, a wrong password or a wrong code, lowers it by one, and each successful login raises it by one, between -5 and 5. A reputation policy acts on that score. To stop logins at -5:
- Under Customization, then Policies, choose Create, then Reputation Policy. Name it
failed-logins, keep Check IP and Check Username on and Threshold at-5, and choose Finish. - Under Flows and Stages, then Stages, choose Create, then Deny Stage. Name it
too-many-failed-logins, enter a Deny message such asToo many failed logins. Try again tomorrow, or ask an admin., and choose Finish. - Under Flows and Stages, then Flows, open default-authentication-flow, then Stage Bindings, and choose Bind existing stage. Choose
too-many-failed-logins, set Order to15, turn Evaluate when flow is planned off and Evaluate when stage is run on, and choose Create. - Expand the new binding in the list, choose Bind existing policy/group/user, choose the policy
failed-logins, and choose Create.
The deny stage now runs after the username, and only when the score is at -5 or lower. In our test, after five wrong passwords, the right one never got asked for: authentik showed the deny message. Know what it does and does not do:
- It is not a timed lock. A score is forgotten 24 hours after its last change, or when an admin deletes it under Customization, then Reputation scores.
- The policy adds up the scores of the username from every address, and of the address for every username. Someone who knows a username can lock that person out from anywhere, and five failures from one office address lock out everyone there. Turning off Check IP or Check Username trades one of those for the other.
- A user who has just logged in successfully a few times has a score above 0, and gets more tries.
11. Connect an app
Each app gets an application and a provider in authentik. Here the app is Matrix: people then log in to Element with their authentik account. In the admin interface:
- Open Applications, then Applications, and choose New Application.
- Enter
Matrixas the Application Name, and choose Next. - Choose OAuth2/OpenID Provider, and Next.
- Set Authorization Flow to default-provider-authorization-implicit-consent, which logs people in without asking them to approve the app each time.
- Copy the Client ID and Client Secret.
- Under Redirect URIs/Origins, choose Add entry, keep Strict, and enter
https://matrix.example.com/_synapse/client/oidc/callback. - Choose Next twice, then Create Application, and Finish.
Without anything under Configure Bindings, every user in authentik can log in to the app. authentik's address for the app is https://auth.example.com/application/o/matrix/, with the name in lower case.
Then, as root, switch to machinectl shell matrix@, and add this to ~/matrix/synapse.yaml, with the ID and secret you copied:
oidc_providers:
- idp_id: authentik
idp_name: authentik
discover: true
issuer: "https://auth.example.com/application/o/matrix/"
client_id: "CLIENT_ID"
client_secret: "CLIENT_SECRET"
scopes: ["openid", "profile", "email"]
allow_existing_users: true
user_mapping_provider:
config:
localpart_template: "{{ user.preferred_username }}"
display_name_template: "{{ user.name }}"
authentik runs on the same server, so Synapse has to reach it through the server rather than inside its own pod, as in the Podman guide. Add this line to ~/.config/containers/systemd/matrix.pod, under PublishPort:
AddHost=auth.example.com:host-gateway
Then restart Matrix:
systemctl --user daemon-reload
systemctl --user restart matrix-pod
Element's login page now has Continue with authentik. A person logging in for the first time gets a Matrix account with their authentik user name, such as @bob:example.com. With allow_existing_users: true, an authentik user with the same name as an existing Matrix account logs in to that account, so turn it on only if the names in authentik belong to the same people as in Matrix.
Other apps follow the same steps, with the redirect address from the app's own documentation. authentik's documentation has a page for many of them.
12. Keep it up to date
As authentik, turn on Podman's daily updates:
systemctl --user enable --now podman-auto-update.timer
That keeps authentik on the newest 2026.8 release, and PostgreSQL on the newest 18. authentik releases a new version every few months, such as 2026.11. Upgrade one version at a time, without skipping any, because authentik cannot go back to an older version: read the release notes, back up as in step 13, change the tag in both authentik-server.container and authentik-worker.container, and run systemctl --user daemon-reload and systemctl --user restart authentik-pod.
13. Back up
As authentik:
umask 077
mkdir -p ~/backup
podman exec authentik-db pg_dump -U authentik authentik > ~/backup/authentik-db.sql
tar -czf ~/backup/authentik-data.tar.gz -C ~/authentik data
podman secret inspect --showsecret --format '{{.SecretData}}' authentik-secret-key > ~/backup/authentik-secret-key
umask 077 makes the backup files readable by authentik only. The database holds the users, their passwords and second factors, and every application. The secret key is needed to restore it. Copy ~/backup to another machine, for example with restic, and keep it private.
To restore into an empty pod, as authentik, with the backup in ~/backup:
systemctl --user stop authentik-pod
podman volume rm authentik-db
podman unshare rm -rf ~/authentik/data
tar -xzf ~/backup/authentik-data.tar.gz -C ~/authentik
podman unshare chown -R 1000:1000 ~/authentik/data
systemctl --user start authentik-db
systemctl --user stop authentik-server authentik-worker
until podman exec authentik-db pg_isready -q -h 127.0.0.1 -U authentik; do sleep 2; done
podman exec -i authentik-db psql -q -U authentik -d authentik < ~/backup/authentik-db.sql
systemctl --user start authentik-server authentik-worker
Starting the database starts the whole pod, so stop the server and the worker before loading the backup. Otherwise authentik sets up an empty database first, and loading the backup fails with a long list of errors. The until line waits for PostgreSQL to be ready. On a new server, create the secret key from the backup instead of a new one in step 2, and the email password as in step 8:
tr -d '\n' < ~/backup/authentik-secret-key | podman secret create authentik-secret-key -
We restored on the same server.
Troubleshooting
An app's login fails, and https://auth.example.com/application/o/matrix/.well-known/openid-configuration shows addresses starting with http://. authentik does not trust Caddy. Check that AUTHENTIK_LISTEN__TRUSTED_PROXY_CIDRS in step 3 is your server's IPv4 address, and restart with systemctl --user restart authentik-server.
The first setup page shows Not Found. authentik is still setting itself up. Wait a minute after the health check in step 4 answers 200, and open http://localhost:8092 again.
Synapse cannot reach authentik. The AddHost line from step 11 is missing from matrix.pod, or names a different host.
Login stops after the username with "Too many failed logins". The reputation policy from step 10 has blocked the username or the address. Delete the score under Customization, then Reputation scores.