Authelia is an open-source authentication and authorization server and portal fulfilling the identity and access management (IAM) role of information security in providing multi-factor authentication and single sign-on (SSO) for your applications via a web portal. It acts as a companion for common reverse proxies.
This is not simple stuff and it require some understanding of what you are doing: just copy-pasting configurations and finger-crossing will not work and only lead to frustration.
I strongly suggest you read the very good Get Started page and the linked references before you proceed.
First of all, your NGINX must be compiled with auth_request module, but if you followed my NGINX guide (here), you are all set.
While Authelia support docker images, there is really no reason to use a container since it's a single executable that you can simply download and start. So let's install on bare-metal!
As usual, let's create a dedicated user:
useradd -m authelia
in this case, you should let the home folder be under the /home/authelia since this is an authentication service, you want to have it always working even if the /media folder doesn't mount for any reason.
Now it's time to download the latest release from https://github.com/authelia/authelia/releases and install it under user bin folder:
su - authelia wget https://github.com/authelia/authelia/releases/download/vX.Y.Z/authelia-vX.Y.Z-linux-amd64.tar.gz mkdir bin config db logs cd bin tar xvf ../authelia-vX.Y.Z-linux-amd64.tar.gz
You need to copy the provided example configuration and edit to your needs:
cp bin/config-example.yml configuration.yml
As an example, here is my configuration.yml, split into separate sections because it's very long:
---
theme: 'auto'
server:
address: 'tcp://127.0.0.1:9071/' # port 9071, default would collide with another service
endpoints:
<<< see below >>>
log:
<<< see below >>>
telemetry:
metrics:
enabled: false
totp:
disable: false
webauthn:
disable: false
identity_validation:
reset_password:
jwt_secret: '<<< put a good secret here >>>>'
authentication_backend:
<<< see below >>>
password_policy:
standard:
enabled: false
min_length: 8
max_length: 0
require_uppercase: true
require_lowercase: true
require_number: true
require_special: true
zxcvbn:
enabled: false
min_score: 3
privacy_policy:
enabled: false
require_user_acceptance: false
policy_url: ''
access_control:
<<< see below >>>
session:
secret: '<<< another, different, secret here >>>>'
cookies:
-
domain: 'mydomain.com'
authelia_url: 'https://login.mydomain.com'
default_redirection_url: 'https://mydomain.com'
name: 'authelia_session'
same_site: 'lax'
inactivity: '5m'
expiration: '14h'
remember_me: '1M'
storage:
<<< see below >>>
notifier:
<<< see below >>>
identity_providers:
oidc:
<<< see below >>>
...
This file has a few assumptions, for example you need to create login.mydomain.com in your NGINX configuration, create the subdomain in your domain DNS, and generate the corrispective HTTPS certificate. Authelia will not work otherwise, by design.
This section is used to define how to access domains, and with which policy. I use single factor at this time, so:
access_control:
default_policy: 'deny'
rules:
- domain: '*.mydomain.com'
policy: 'one_factor'
I choose to store passwords and users in a yaml text file, for my few users this is perfect and simple enough:
password_reset:
disable: false
file:
path: '/home/authelia/config/users_database.yml'
watch: true
See below on how to add/create users.
Due to my very limited use case (less than 10 users) i am using SQLite3 as storage backend:
storage:
encryption_key: '<<< put a good string here >>>>'
local:
path: '/home/authelia/db/db.sqlite3'
Authelia support both on-flie notifier, which is pretty simple to setup, or email based notifier. While email requires you to setup a dedicated email address for Authelia, it will allow users to reset their password without your actions, which might be desirable.
File based, simple, notifier:
notifier:
disable_startup_check: true
filesystem: # Using email notifier is probably better: TBD
filename: '/home/authelia/config/notification.txt'
SMTP / email notifier:
notifier:
disable_startup_check: true
smtp:
address: 'smtp://mail.mydomain.com:587'
username: 'authelia@mydomain.com'
password: '<<< put email password here >>>'
sender: 'Authelia <authelia@mydomain.com>'
Note the disable_startup_check: you should set it to true to prevent authelia to crash at boot if network is not yet reachable.
Please note the endpoints configuration below: i have created two different endpoints:
endpoints:
authz:
normal: # This is used for the non-basic auth
implementation: 'AuthRequest'
authn_strategies:
- name: 'CookieSession'
basic: # this enables basic auth for services that don't uspport anything else
implementation: 'AuthRequest'
authn_strategies:
- name: 'HeaderAuthorization'
schemes:
- 'Basic'
This is different from the stock authelia configuration files and requires one important change to the NGINX snippets below, which i will point out. Do not forget to edit the snippets where indicated.
Moving logging to a separate file, remember to logrotate it, because it will grow a lot over time:
log: level: 'debug' format: 'text' file_path: '/var/log/authelia/authelia.log'
For the log file, you need to create and set permissions to /var/log/authelia:
mkdir /var/log/authelia chown authelia:authelia /var/log/authelia chmod 750 /var/log/authelia
Setting up Authelia as OIDC Provider is useful to support services that support this protocol, like Jellyfin. See here for more details.
Add the following section to your configuration.yml:
identity_providers:
oidc:
hmac_secret: '<<see below>>'
jwks:
- key_id: 'main'
use: 'sig'
key: |
-----BEGIN PRIVATE KEY-----
... <<< see below >>> ...
-----END PRIVATE KEY-----
enable_client_debug_messages: false
minimum_parameter_entropy: 8
enforce_pkce: 'public_clients_only'
enable_pkce_plain_challenge: false
enable_jwt_access_token_stateless_introspection: false
discovery_signed_response_alg: 'none'
discovery_signed_response_key_id: ''
require_pushed_authorization_requests: false
authorization_policies:
policy_name:
default_policy: 'one_factor'
rules:
- policy: 'deny'
subject: 'group:services'
lifespans:
access_token: '1h'
authorize_code: '1m'
id_token: '1h'
refresh_token: '90m'
cors:
endpoints:
- 'authorization'
- 'token'
- 'revocation'
- 'introspection'
allowed_origins:
- 'https://mydomain.com'
allowed_origins_from_client_redirect_uris: false
To generate hmac_secret use the following command:
/home/authelia/bin/authelia-linux-amd64 crypto rand --length 64 --charset alphanumeric
To generate the PRIVATE KEY use the following command:
openssl genrsa -out private.pem 4096 && cat private.pem
You can delete the generated files afterward.
Each OIDC client must have it's own section in the Authelia configuration file. See here for an example.
identity_providers:
oidc:
<< omissis, see OIDC Providers above >>
clients:
- client_id: ' <<< see below >>>'
client_name: 'Jellyfin'
client_secret: '<<< see below >>>'
public: false
authorization_policy: 'two_factor'
require_pkce: true
pkce_challenge_method: 'S256'
redirect_uris:
- 'https://client.example.com/sso/OID/redirect/authelia'
scopes:
- 'openid'
- 'profile'
- 'groups'
userinfo_signed_response_alg: 'none'
token_endpoint_auth_method: 'client_secret_post'
To generate the client_id:
./home/authelia/bin/authelia-linux-amd64 crypto rand --length 72 --charset rfc3986
To generate client_secret:
/home/authelia/bin/authelia-linux-amd64 crypto hash generate pbkdf2 --variant sha512 --random --random.length 72 --random.charset rfc3986
If you want to customize the look & feel of the login dialog, you can replace the logo and the favicon.
In your configuration path add the line:
server: asset_path: '/home/authelia/config/assets'
and drop in that folder two files:
You can logout by going to the URL https://login.mydomain.com/logout.
From this point onward, always refer to Authelia documentation to understand what i am doing.
This is the associated NGINX config file /etc/nginx/mydomain/login/login.conf:
server {
server_name login.mydomain.com;
listen 443 ssl;
listen 8443 ssl;
http2 on;
access_log /var/log/nginx/login.mydomain.com_access_log main;
error_log /var/log/nginx/login.mydomain.com_error_log info;
location / {
include com.mydomain/authelia_proxy.conf;
proxy_pass http://127.0.0.1:9071;
}
location = /api/verify {
proxy_pass http://127.0.0.1:9071;
}
location /api/authz/ {
proxy_pass http://127.0.0.1:9071;
}
}
In addition to this one, you need also che following specific NGINX config files:
Now, you need to edit the authelia_location.conf and replace the first line to match the standard endpoint defined above:
set $upstream_authelia http://127.0.0.1:9071/api/authz/normal;
And, similarly, you need to edit the authelia_location-basic.conf and replace the first line to match the basic endpoint defined above:
set $upstream_authelia http://127.0.0.1:9071/api/authz/basic;
I have added the specific endpoints (normal / basic) to the URL..
Well, you can enable Authelia support in any subdomain you want by simply adding the following three lines to your NGINX configurations:
# The following goes in the server section:
include "org.gardiol/authelia_location.conf";
# The following two can go either in specific location section, or directly in the server section to protect ALL locations:
include "org.gardiol/authelia_proxy.conf";
include "org.gardiol/authelia_authrequest.conf";
Since i choose file based storage, adding and editing users is a simple matter of editing the following text file /home/authelia/config/users_database.yml. If missing, create it from the following example:
>
# yamllint disable rule:line-length
---
###############################################################
# Users Database #
###############################################################
# This file can be used if you do not have an LDAP set up.
users:
myuser:
disabled: false
displayname: "Name Surname"
password: " << see below >>"
email: myuser@mydomain.com
groups:
- admins
- dev
...
# yamllint enable rule:line-length
To create passwords, you can use the Authelia binary itself:
/home/authelia/bin/authelia-linux-amd64 crypto hash generate --help
then copy & paste the password hash inside the above yaml file. Authelia should pickup autmatically the change without the need to reload.
I will be working on an automatic synchronization between /etc/passwd users and Authelia users to keep all the authentications in sync in the future.
Create the following file as /etc/init.d/authelia:
#!/sbin/openrc-run
# Copyright 1999-2021 Gentoo Authors
# Distributed under the terms of the GNU General Public License v2
description="Authelia - authenticator"
pidfile="/run/authelia.pid"
command_background=true
command="/home/authelia/bin/authelia-linux-amd64"
command_args="--config /home/authelia/configuration.yml"
command_user="authelia:authelia"
depend() {
need net
}
Make it executable, and enable on boot:
chmod +x /etc/init.d/authelia rc-update add authelia default /etc/init.d/authelia start
Download a new binary, replace old, restart service!