Authelia

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.

Authelia has 2 modes of operation (Forward-Auth and OpenID Connect). Read below for more information.

Warning: this service is a new addition to the playbook. It may not fully work or be configured in a suboptimal manner.

Dependencies

This service requires the following other services:

a database
- (optional) a Postgres database - if enabled for your Ansible inventory host, Authelia will be connected to the Postgres server automatically
- (optional) a MySQL / MariaDB database - if enabled for your Ansible inventory host (and you don't also enable Postgres), Authelia will be connected to the MariaDB server automatically
- or SQLite, used by default when none of the above database choices is enabled for your Ansible inventory host
(optional, but recommended) Redis
- for storing session information in a persistent manner
- if Redis is not enabled, session information is stored in-memory and restarting Authelia destroys user sessions
a Traefik reverse-proxy server
- for serving the Authelia portal website
- for protecting other Traefik-based services by adding the Authelia forward-auth middleware to them when Protecting services with Authelia's forward-auth

Configuration

To enable this service, add the following configuration to your vars.yml file and re-run the installation process:

########################################################################
#                                                                      #
# authelia                                                             #
#                                                                      #
########################################################################

authelia_enabled: true

authelia_hostname: authelia.example.com

# The base domain that session cookies related to authentication will be set on.
#
# Forward-auth services that you will protect need to be hosted on subdomains under this base domain.
# (e.g. service1.example.com, service2.example.com)
#
# For OpenID Connect-protected services, this value does not matter.
#
# In any case, `authelia_config_session_domain` needs to be a subdomain of `authelia_hostname`.
authelia_config_session_domain: example.com

# The database encryption password.
# Changing this subsequently will cause trouble unless you use the CLI to migrate.
# Generating a strong password (e.g. `pwgen -s 64 1`) is recommended.
authelia_config_storage_encryption_key: ''

# Authelia supports either LDAP or a file-based authentication (user) database.
#
# Using the file-based database is easiest and it's what we do by default here
# by defining `authelia_config_authentication_backend_file_content`.
#
# To use LDAP, remove `authelia_config_authentication_backend_file_content` and define various
# `authelia_config_authentication_backend_ldap_*` variables.
authelia_config_authentication_backend_file_content: |
  ---
  users:
    john:
      disabled: false
      displayname: John Doe
      password: PASSWORD_HASH_HERE
      email: john@example.com
      groups:
        - admins
        - dev
    peter:
      disabled: false
      displayname: Peter Johnson
      password: PASSWORD_HASH_HERE
      email: peter@example.com
      groups:
        - dev
  ...  

# You can define various authentication rules for each protected service here.
authelia_config_access_control_rules:
 - domain: 'service1.example.com'
   policy: one_factor

# The configuration below connects Authelia to the Redis instance, for session storage purposes.
# You may wish to run a separate Redis instance for Authelia, because Redis is not multi-tenant.
# Read more in docs/services/redis.md.
# If Redis is not available, session data will be stored in memory and will be lost on container restart.
authelia_config_session_redis_host: "{{ redis_identifier if redis_enabled else '' }}"

########################################################################
#                                                                      #
# /authelia                                                            #
#                                                                      #
########################################################################

URL

In the example configuration above, we configure the service to be hosted at https://authelia.example.com.

While the Authelia Ansible role provides an authelia_path_prefix variable, Authelia does not support being hosted at a subpath right now.

On the Authelia base URL, there's a portal website where you can log in and manage your user account.

Session storage

As mentioned in the default configuration above (see authelia_config_session_redis_host), you may wish to run Redis for storing session data.

You may wish to run a separate Redis instance for Authelia, because Redis is not multi-tenant. See our Redis documentation page for additional details. When running a separate instance of Redis, you may need to connect Authelia to the Redis instance's container network via the authelia_container_additional_networks_custom variable.

Authentication storage providers

Authelia supports LDAP and file-based storage providers for the user database.

The default configuration above enables the file-based provider with the authelia_config_authentication_backend_file_content variable.

To use LDAP, remove the authelia_config_authentication_backend_file_content variable and define a bunch of authelia_config_authentication_backend_ldap_* variables.

Modes of operation

Authelia has 2 modes of operation which can be enabled simultaneously:

Forward-Auth: Forward-Auth is useful for protecting services which are not aware of authentication at all or which can receive authentication/authorization data via HTTP headers. Forward-Auth can act as a replacement for HTTP Basic Authentication. It does this by acting as a companion to common reverse proxies, like Traefik which is frequently used by this playbook. To learn more, see Protecting a service with Authelia's forward-auth
OpenID Connect: experimental OpenID Connect support support, so that services which are OpenID Connect-compatible can use Authelia as an identity provider. To learn more, see Protecting a service with OpenID Connect

Protecting a service with Authelia's forward-auth

If you're using Traefik, you can easily protect services running on the same host by adding additional Traefik labels to them.

Forward-Auth is useful for protecting services which are not aware of authentication at all or which can receive authentication/authorization data via HTTP headers.

Here's an example configuration for Hubsite (a service which does not support authentication at all):

hubsite_container_labels_additional_labels: |
  traefik.http.routers.{{ hubsite_identifier }}.middlewares={{ authelia_identifier }}@docker

The Hubsite component does not use any Traefik middlewares, so defining a .middlewares configuration key and pointing it to the Authelia middleware works well.

For most other components, middlewares are in use in their default Traefik labels, so adding an additional .middlewares key will not work. You may need to inject additional middlewares on top of the default ones. Not all components may (yet) have a variable for doing so. Consider contributing to various roles to allow additional middlewares to be injected dynamically!

Protecting a service with OpenID Connect

For services which support OpenID Connect, you can enable the experimental OpenID Connect identity provider in Authelia.

You will need some additional configuration like this:

authelia_config_identity_providers_oidc_clients:
  - id: grafana
    description: Grafana
    secret: HASH_OF_THE_SHARED_SECRET
    public: false
    authorization_policy: one_factor
    redirect_uris:
      - https://mash.example.com/grafana/login/generic_oauth
    scopes:
      - openid
      - profile
      - groups
      - email
    userinfo_signing_algorithm: none

authelia_config_identity_providers_oidc_issuer_private_key: |
  KEY CONTENT GOES HERE.
  TO GENERATE A KEY, USE: `openssl genpkey -algorithm RSA -out FILE_NAME`

The example configuration above configures a single OpenID Connect client (application) called grafana (see the Grafana service supported by this playbook), which supposedly lives at the base URL of https://mash.example.com/grafana.

You will need to create a shared secret and hash its value (e.g. php -r 'echo password_hash("PASSWORD_HERE", PASSWORD_ARGON2ID);'). Feel free to use another language (or tool) for creating a hash as well. A few different hash algorithms are supported besides Argon2id.

Finally, configure your application, hooking it to Authelia's OpenID Connect identity provider. You can get inspired by the sample configuration we have created for Grafana.

Extending the Authelia configuration

The Authelia Ansible role provides various variables for configuring Authelia. You can see their default values in the defaults/main.yml file of the Authelia role.

If a dedicated variable is not available for you to use or if you wish to override some hardcoded default, you can always use the authelia_configuration_extension_yaml Ansible variable for extending/overriding the default configuration.

authentik - An open-source Identity Provider focused on flexibility and versatility.
Keycloak - An open source identity and access management solution

11 KiB Raw Blame History