Fediversity

Feature Specification: Component lldap

Created: 2026-10-07

Status: Implemented

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

User Scenarios & Testing (mandatory)

User Story 1 - Keep the users of a group in one directory (Priority: P1)

Each group needs one user directory. The lldap component provides ldap, so its node answers the ldap requests of the group (see ldap). A provisioning step applies the seeded users and groups with OpenTofu.

Why this priority: The portal and the applications read users from this directory.

Independent Test: A contract test of the provider, and VM tests of the LDAP engine, the key seed isolation and the admin release. Unit tests cover the directory and grant wiring.

Acceptance Scenarios:

  1. Given lldap and authelia machines, When the setups evaluate, Then the directory has a bind account per group, the lldap machine is its host, and authelia has its bind group.

User Story 2 - Let users manage their own account (Priority: P2)

A user changes a password or a display name in the web UI. authelia protects the UI with one factor and no group restriction, so every signed-in user reaches it. Only the reset routes skip the protection, so that a user without a session can use a reset link, and a rate limit protects them.

Why this priority: The directory works without self-service.

Independent Test: A VM test does a reset through the front and checks that the other routes stay protected.

Acceptance Scenarios:

  1. Given a user without a session, When it requests a reset route, Then the request reaches lldap. When it requests login, token refresh or the API, Then it goes to authelia.

User Story 3 - Send password reset mail (Priority: P3)

When the group has an smtp machine, lldap gets a mail account and a sender on the relay (see smtp).

Why this priority: An admin can reset a password without mail.

Independent Test: The reset VM test and a unit test of the mail wiring.

Acceptance Scenarios:

  1. Given an smtp machine, When the setups evaluate, Then lldap has a mail account.

Edge Cases

  • Without an lldap machine, the directory name of the group is the host.
  • The public URL is the UI behind forward-auth when the node serves it, else the direct listener.
  • The admin user has the group name, which keeps it off the names that pixelfed reserves.
  • The OPAQUE server key comes from a seed in OpenBao, so a rebuilt node has the same key and a restored database works. lldap does not start when the key changes. A database with a key from another source needs one start with a forced key update, and then every user resets the password.

Requirements (mandatory)

Functional Requirements

  • FR-001: The component MUST provide ldap.
  • FR-002: The component MUST request spiffe, so that the node logs in to OpenBao.
  • FR-003: The component MUST request forward-auth for its UI on its own subdomain, with one factor and no group restriction, and MUST NOT register an OIDC client.
  • FR-004: The reset routes MUST skip the protection and MUST have a rate limit.
  • FR-005: The UI MUST NOT be an admin UI, so the switch for admin UIs does not gate it.
  • FR-006: The setup MUST configure the daemon, the provisioning and the bind accounts through the ldap resource.
  • FR-007: The component MUST request a postgresql database and user, and MUST give the URL to the daemon through its environment, because the daemon is a dynamic user. With a result, the configuration file MUST hold no database URL. Without one, the daemon MUST keep SQLite.
  • FR-008: The component MUST request a garage backup bucket and a streaming backup of the database with restic.
  • FR-009: The ldap resource MUST generate the key seed once per group. The daemon MUST read the rendered seed and MUST NOT use a key file.
  • FR-010: The ldap resource MUST generate the JWT secret once per group. The daemon MUST receive the rendered secret as a credential of systemd. A daemon with no jwtSecretFile MUST generate a secret in its state directory.

Key Entities

  • Directory request: The ldap request, with the directory name, the bind accounts, the admin user, the mail and the host.
  • Reset routes: The routes that skip forward-auth, under a rate limit.
  • Option audit table: The audience of each option. Almost all are for the project.

Success Criteria (mandatory)

Measurable Outcomes

  • SC-001: The provider contract test and the VM tests of the LDAP engine, seed isolation, admin release and reset mail pass.
  • SC-002: The unit tests of the directory, grant and mail wiring pass.

Assumptions

  • The hosting-provider and operator groups each run a directory.
  • The component has no icon.
  • The provider and the provisioning are in the ldap resource.

Known Deviations

None.