====== Authelia  ======

[[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 =====

You need to copy the provided example configuration and edit to your needs:
<code bash>
cp bin/config-example.yml configuration.yml
</code>

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:
    <<< 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 >>>
...
</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: 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
# 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
}
</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!