Differences

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

--- services:authelia [2024/08/29 12:12] – [Autostart] willy
+++ services:authelia [2024/09/18 13:56] (current) – willy
@@ Line 3: / Line 3: @@
 [[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.
+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.
@@ Line 31: / Line 31: @@
 ===== Configuration =====
-Now you need to copy the provided example configuration and edit to your needs:
+You need to copy the provided example configuration and edit to your needs:
 <code bash>
-cd bin/config-example.yml configuration.yml
+cp bin/config-example.yml configuration.yml
 </code>
-As an example, here is my configuration.yml, stripped to the bone:
+As an example, here is my configuration.yml, split into separate sections because it's very long:
 <file - configuration.yml>
 ---
 theme: 'auto'
 server:
   address: 'tcp://127.0.0.1:9071/' # port 9071, default would collide with another service
   endpoints:
-    authz:
+    <<< see below >>>
-      auth-request:
-        implementation: 'AuthRequest'
 log:
-  level: 'debug'
+    <<< see below >>>
-  format: 'text'
-  file_path: '/home/authelia/logs/authelia.log'
 telemetry:
   metrics:
     enabled: false
 totp:
   disable: false
 webauthn:
   disable: false
 identity_validation:
   reset_password:
     jwt_secret: '<<< put a good secret here >>>>'
 authentication_backend:
-  password_reset:
+    <<< see below >>>
-    disable: false
-  file: # For simplicity, i use a file based storage for users
-    path: '/home/authelia/config/users_database.yml'
-    watch: true
 password_policy:
   standard:
@@ Line 86: / Line 70: @@
     enabled: false
     min_score: 3
 privacy_policy:
   enabled: false
   require_user_acceptance: false
   policy_url: ''
 access_control:
-  default_policy: 'deny'
+    <<< see below >>>
-  rules:
-    - domain: '*.mydomain.com'
-      policy: 'one_factor'
 session:
   secret: '<<< another, different, secret here >>>>'
@@ Line 111: / Line 89: @@
   remember_me: '1M'
+storage:
+  <<< see below >>>
+notifier:
+  <<< see below >>>
+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.
+=== Access Control ===
+This section is used to define how to access domains, and with which policy. I use single factor at this time, so:
+<code>
+access_control:
+  default_policy: 'deny'
+  rules:
+    - domain: '*.mydomain.com'
+      policy: 'one_factor'
+</code>
+=== 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>
+See below on how to add/create users.
+=== 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: false
+  disable_startup_check: true
   filesystem: # Using email notifier is probably better: TBD
     filename: '/home/authelia/config/notification.txt'
-...
+</code>
-</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.
+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.
@@ Line 156: / Line 348: @@
   * 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..

Willy's Wiki

User Tools

Differences