Differences

This shows you the differences between two versions of the page.

--- services:authelia [2024/08/27 12:08] – created willy
+++ services:authelia [2024/09/18 13:56] (current) – willy
@@ Line 1: / Line 1: @@
-https://www.authelia.com/integration/prologue/get-started/
+====== Authelia  ======
-https://github.com/authelia/authelia/releases
+[[https://www.authelia.com/|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 [[https://www.authelia.com/integration/prologue/get-started|Get Started]] page and the linked references before you proceed.
+===== Installation =====
+First of all, your NGINX must be compiled with **auth_request** module, but if you followed my NGINX guide ([[selfhost:nginx|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:
+<code bash>
 useradd -m authelia
+</code>
+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|https://github.com/authelia/authelia/releases]] and install it under user **bin** folder:
+<code bash>
 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
+</code>
+===== Configuration =====
-wget https://github.com/authelia/authelia/releases/download/v4.38.10/authelia-v4.38.10-linux-amd64.tar.gz
+You need to copy the provided example configuration and edit to your needs:
+<code bash>
+cp bin/config-example.yml configuration.yml
+</code>
-mkdir bin
+As an example, here is my configuration.yml, split into separate sections because it's very long:
-cd bin
+<file - configuration.yml>
-tar xvf ../authelia-v4.38.10-linux-amd64.tar.gz
+---
-cd ..
+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'
-creare file configuration.yml (vedi esempio)
+storage:
+  <<< see below >>>
-mkdir config db logs
+notifier:
+  <<< see below >>>
-lancia authelia
+identity_providers:
+  oidc:
+    <<< see below >>>
+...
+</file>
+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.
-NGINX auth_request
-www-servers/nginx NGINX_MODULES_HTTP: auth_request auth_pam dav dav_ext gunzip sub realip xslt
+=== Access Control ===
-crea file org.gardiol/authelia_proxy.conf (file)
+This section is used to define how to access domains, and with which policy. I use single factor at this time, so:
-crea file org.gardiol/login/login.conf (file)
+<code>
-crea org.gardiol/authelia_location.conf (file)
+access_control:
-crea org.gardiol/authelia_authrequest.conf (file)
+  default_policy: 'deny'
+  rules:
+    - domain: '*.mydomain.com'
+      policy: 'one_factor'
+</code>
-configura ogni subdomain auth
+=== Authentication Backend ===
+I choose to store passwords and users in a yaml text file, for my few users this is perfect and simple enough:
+<code>
+  password_reset:
+    disable: false
+  file:
+    path: '/home/authelia/config/users_database.yml'
+    watch: true
+</code>
-Creazione passwords:
+See below on how to add/create users.
-./authelia-linux-amd64 crypto hash generate --help
+=== Storage ===
+Due to my very limited use case (less than 10 users) i am using SQLite3 as storage backend:
+<code>
+storage:
+  encryption_key: '<<< put a good string here >>>>'
+  local:
+    path: '/home/authelia/db/db.sqlite3'
+</code>
+=== Notifier ===
+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:
+<code>
+notifier:
+  disable_startup_check: true
+  filesystem: # Using email notifier is probably better: TBD
+    filename: '/home/authelia/config/notification.txt'
+</code>
+SMTP / email notifier:
+<code>
+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>'
+</code>
+Note the **disable_startup_check**: you should set it to true to prevent authelia to crash at boot if network is not yet reachable.
+=== Endpoints ===
+Please note the **endpoints** configuration below: i have created two different endpoints:
+  * standard: which will be used by all supported services
+  * basic: which will be needed by some protocols like WebDAV and such
+<code>
+  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'
+</code>
+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.
+=== Log ===
+Moving logging to a separate file, remember to //logrotate// it, because it will grow a lot over time:
+<code>
+log:
+  level: 'debug'
+  format: 'text'
+  file_path: '/var/log/authelia/authelia.log'
+</code>
+For the log file, you need to create and set permissions to **/var/log/authelia**:
+<code bash>
+mkdir /var/log/authelia
+chown authelia:authelia /var/log/authelia
+chmod 750 /var/log/authelia
+</code>
+=== OIDC Provider ===
+Setting up Authelia as OIDC Provider is useful to support services that support this protocol, like Jellyfin. See [[https://www.authelia.com/configuration/identity-providers/openid-connect/provider/|here]] for more details.
+Add the following section to your configuration.yml:
+<code>
+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
+</code>
+To generate **hmac_secret** use the following command:
+<code bash>
+/home/authelia/bin/authelia-linux-amd64  crypto rand --length 64 --charset alphanumeric
+</code>
+To generate the **PRIVATE KEY** use the following command:
+<code bash>
+openssl genrsa -out private.pem 4096 && cat private.pem
+</code>
+You can delete the generated files afterward.
+=== OIDC Client ===
+Each OIDC client must have it's own section in the Authelia configuration file. See [[https://www.authelia.com/integration/openid-connect/jellyfin/| here]] for an example.
+<code>
+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'
+</code>
+To generate the **client_id**:
+<code bash>
+./home/authelia/bin/authelia-linux-amd64 crypto rand --length 72 --charset rfc3986
+</code>
+To generate **client_secret**:
+<code bash>
+  /home/authelia/bin/authelia-linux-amd64 crypto hash generate pbkdf2 --variant sha512 --random --random.length 72 --random.charset rfc3986
+</code>
+=== Customization ===
+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:
+<code>
+server:
+  asset_path: '/home/authelia/config/assets'
+</code>
+and drop in that folder two files:
+  * favicon.ico (must be an ico)
+  * logo.png (must be a png)
+=== Logout ===
+You can logout by going to the URL **https://login.mydomain.com/logout**.
+==== NGINX support files ====
+From this point onward, always refer to [[https://www.authelia.com/integration/proxies/nginx/|Authelia documentation]] to understand what i am doing.
+This is the associated NGINX config file **/etc/nginx/mydomain/login/login.conf**:
+<file - 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;
+        }
+}
+</file>
+In addition to this one, you need also che following specific NGINX config files:
+  * The **/etc/nginx/com.mydomain/authelia_proxy.conf**: see [[https://www.authelia.com/integration/proxies/nginx/#proxyconf|here]]
+  * The **/etc/nginx/com.mydomain/authelia_location.conf**: see [[https://www.authelia.com/integration/proxies/nginx/#authelia-locationconf|here]]
+  * The **/etc/nginx/com.mydomain/authelia_location-basic.conf**: see [[https://www.authelia.com/integration/proxies/nginx/#authelia-location-basicconf|here]]
+  * The **/etc/nginx/com.mydomain/authelia_authrequest.conf**: see [[https://www.authelia.com/integration/proxies/nginx/#authelia-authrequestconf|here]]
+  * The **/etc/nginx/com.mydomain/authelia_authrequest-basic.conf**: see [[https://www.authelia.com/integration/proxies/nginx/#authelia-authrequest-basicconf|here]]
+Now, you need to edit the **authelia_location.conf** and replace the first line to match the __standard endpoint__ defined above:
+<code>
+set $upstream_authelia http://127.0.0.1:9071/api/authz/normal;
+</code>
+And, similarly, you need to edit the **authelia_location-basic.conf** and replace the first line to match the __basic endpoint__ defined above:
+<code>
+set $upstream_authelia http://127.0.0.1:9071/api/authz/basic;
+</code>
+I have added the specific endpoints (normal / basic) to the URL..
+===== Enable Authelia in NGINX =====
+Well, you can enable Authelia support in any subdomain you want by simply adding the following three lines to your NGINX configurations:
+<code>
+# 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";
+</code>
+===== Adding and editing users =====
+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:
+<file - users_database.yml>>
+# 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
+</file>
+To create passwords, you can use the Authelia binary itself:
+<code bash>
+/home/authelia/bin/authelia-linux-amd64 crypto hash generate --help
+</code>
+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.
+===== Autostart =====
+Create the following file as **/etc/init.d/authelia**:
 <file - authelia>
 #!/sbin/openrc-run
@@ Line 55: / Line 431: @@
 }
 </file>
+Make it executable, and enable on boot:
+<code bash>
+chmod +x /etc/init.d/authelia
+rc-update add authelia default
+/etc/init.d/authelia start
+</code>
+===== Update =====
+Download a new binary, replace old, restart service!

Willy's Wiki

User Tools

Differences