User Tools

Differences

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

Link to this comparison view

Next revision		Previous revision
services:authelia [2024/08/27 12:08] – created willyservices: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 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 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> <file - authelia>
 #!/sbin/openrc-run #!/sbin/openrc-run
Line 55: Line 431:
 } }
 </file> </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!
 +
  

This website uses technical cookies only. No information is shared with anybody or used in any way but provide the website in your browser.

More information