ADR2: Configuration via Environment and Secrets

Date: August 11, 2025

Status#

Proposed

Submitters#

• James Elliott, Authelia

Change Log#

Context#

Authelia provides configuration layers which consist of files, environment variables, and secrets. The environment variables and secrets layers offer a convenient way for users to declaratively define values outside of a configuration file.

Lists which contain values which do not have a primitive (integer, string, boolean) type and instead have a object or dictionary cannot be configured using this method due to limitations in the tooling available. To be able to achieve this a difficult to maintain completely custom parser would have to be developed.

Proposed Design#

Templates can be easily leveraged to accomplish the same objective. These templates allow loading environment variables or secret files directly into the configuration either at the same time or separately and formatting them appropriately. This solution is easy to maintain while still being relatively user-friendly.

In addition the template features offer a much richer experience where users can manipulate these files much easier, reuse them, etc; all as part of the same system.

Developing a custom parser should realistically be seen as a last resort, and as an alternative means has been developed that’s significantly easier to maintain this is the proposed solution.

Decision#

N/A

Consequences#

Configuration of elements that fit the context described may have a slight usability cost compared to the alternative. However arguably a custom parser is going to be prone to implementation errors, and use errors.

Specifically defining something like this will likely include a custom format that would require users to understand it which has a usability cost as well.

Related ADRs#

N/A