Fediversity

Feature Specification: Component authelia

Created: 2026-10-07

Status: Implemented

Input: Reconstructed from the code of core/components/shared/authelia/ and its wiring in the setups at 14504f80d, pull requests #1383, #1822, #1835, #1852 and #1874.

User Scenarios & Testing (mandatory)

User Story 1 - Give a group one single sign-on portal (Priority: P1)

Each group needs one place where people sign in. The authelia component provides oidc, so its node answers the oidc requests of the group (see oidc). The setup puts the daemon, the OIDC clients of the group and the secret delivery on this node.

Why this priority: Without the portal, no application can sign a user in, and no admin UI behind forward-auth is reachable.

Independent Test: A unit test of the component covers the operator settings and the database storage. Unit tests of the setups cover the routing of oidc requests.

Acceptance Scenarios:

  1. Given an application that requests oidc, When the setups evaluate, Then its client is on the portal node.

User Story 2 - Sign users in against the group directory (Priority: P2)

When the group has an lldap machine, the setup gives the portal an LDAP first factor. The bind account is a consumer in a dedicated bind group, and OpenBao rotates its password (see ldap). When the group has an smtp machine, the portal also gets a mail account for its notifications.

Why this priority: The portal works without a directory, but has no users then.

Independent Test: A VM test of the OpenBao LDAP engine covers the rotation of the bind password.

Acceptance Scenarios:

  1. Given lldap and smtp machines, When the setups evaluate, Then the portal has an LDAP backend and a mail account with its password in OpenBao.

User Story 3 - Keep the logins over a restart of the portal (Priority: P2)

When the group has a valkey machine, the portal keeps its sessions in its own redis namespace on that machine. A restart of the daemon, for example after a password rotation or a deploy, then does not log out the users, also the users who selected "remember me". OpenBao rotates the password of the namespace, and a rotation restarts the daemon.

Why this priority: Without it, each restart logs out all users, but the portal still works.

Independent Test: Unit tests of the component cover the session settings from the redis result, the TLS of the connection, the restart on a rotation, and the settings without a result. No VM test runs the portal against valkey.

Acceptance Scenarios:

  1. Given a redis result for authelia, When the node evaluates, Then the daemon keeps its sessions at the host and port of the result, as the application user, with the password of the namespace and the session secret.
  2. Given a result with TLS, When the node evaluates, Then the daemon verifies the listener against the name of the host.
  3. Given a rotation of the password of the namespace, When the OpenBao agent renders it, Then the daemon restarts and keeps the sessions.

User Story 4 - Show the portal in the catalog (Priority: P3)

The catalog shows the portal with its name, the upstream logo and its UI subdomain.

Why this priority: The entry is informational.

Independent Test: The catalog test.

Acceptance Scenarios:

  1. Given the catalog, When a surface renders it, Then the authelia entry shows the upstream logo.

Edge Cases

  • Without lldap the portal has no LDAP backend, and without smtp no notifier.
  • With a central OpenBao for the operator hosts, the LDAP engine of a group is a mount per group and namespace on it. The central group, which provides the vars backend, uses the main LDAP mount. Else there is no LDAP engine.
  • The central group also holds the OIDC clients of each group that asks for central login, for example hypervisor.
  • Without a postgresql provider, the portal keeps its state in local SQLite, which has no offsite backup.
  • Without a redis provider, the portal keeps its sessions in memory, and each restart logs out all users.

Requirements (mandatory)

Functional Requirements

  • FR-001: The component MUST provide oidc.
  • FR-002: The component MUST declare one UI subdomain label, and the setup MUST compose the portal name and the issuer from it.
  • FR-003: The component MUST request spiffe, so that the node reads its rotated secrets from OpenBao.
  • FR-004: The component MUST request public HTTP and HTTPS ports, because people reach the login UI from the internet.
  • FR-005: The component MUST NOT request forward-auth for itself, because it is the portal.
  • FR-006: The setup MUST configure the daemon, the clients, the LDAP backend, the secret delivery and the notifier through the oidc resource.
  • FR-007: The component MUST request a postgresql database and user, and the node MUST render the storage from the result. Without a result, it MUST render nothing, so that the daemon keeps SQLite.
  • FR-008: The component MUST request a garage backup bucket and a streaming backup of the database with restic, as the daemon user.
  • FR-009: The component MUST request the authelia namespace of the redis resource, and the node MUST render the session store from the result. Without a result, it MUST render nothing, so that the daemon keeps its sessions in memory.
  • FR-010: The component MUST request the session secret as a generateFiles instance of its own, which only the daemon user can read. The component, not the oidc resource, owns this secret, because the sessions are not a part of OIDC.
  • FR-011: A rotation of the password of the redis namespace MUST restart the daemon, because the daemon reads the password only at start.
  • FR-012: The component MUST mark the Duo secret key in the settings as a secret of the operator, and MUST fail the evaluation when the settings hold a value for it. When the key is set, the node MUST read it from the OpenBao KV of the deployment as a credential of the daemon. A key that is not set MUST NOT stop the start. Unless Duo is disabled, the evaluation MUST fail when the Duo settings have some but not all of the host name, the integration key and the secret key, and name the keys that are not set.

Key Entities

  • Portal request: The oidc request of the setup, with the portal and cookie domains, the instance name and the switch for admin UIs.
  • LDAP backend: The bind account and the OpenBao LDAP engine.
  • Option audit table: The audience of each option. Most are for the project, some for the operator.

Success Criteria (mandatory)

Measurable Outcomes

  • SC-001: The unit tests of the component, of the oidc routing and of the valkey coordinates and of the secrets of the operator, the LDAP engine VM test and the catalog test pass.

Assumptions

  • The hosting-provider and operator groups each run their own portal.
  • The OIDC provider implementation is in the oidc resource.

Known Deviations

None.