ADR3: Using Docker Labels for Authorization Rules

Date: April 4, 2026

Status#

Rejected

Submitters#

• James Elliott, Authelia

Change Log#

Context#

A recurring community request is the ability to define Authelia access control rules via Docker container labels rather than in the Authelia configuration file. This has been raised multiple times over the years:

• Issue #870 (April 2020): The original feature request proposed labels such as authelia.accesscontrol.policy=one_factor to define per-container policies directly in Docker Compose files.
• Discussion #5023 (March 2023): A revisited proposal suggesting custom Authelia-specific labels with hierarchical naming and explicit priority labels. A community member built a workaround helper container that reads labels and generates configuration files.
• Discussion #11509 (March 2026): Raised again, motivated by stale configuration entries when containers are removed and configuration file clutter.

The motivation is to co-locate authorization policy with the service it protects, similar to how reverse proxy routing is often configured via labels with tools like Traefik. Proponents argue this simplifies management by keeping everything in a single Docker Compose file and avoids stale rules when services are removed.

Authelia’s access control system evaluates rules in a strictly ordered, first-match manner. Each rule can include several complex criteria including domain, domain_regex, resources, query, methods, subject, and networks. The first rule whose criteria match the request determines the policy applied. If no rule matches, the default_policy is used. This ordering is fundamental to the correctness of the access control system.

Proposed Design#

The proposed design would allow administrators to define access control rules as Docker labels on individual containers. Authelia would discover these labels at startup or via the Docker API and merge them into the access control rule set alongside any rules defined in the configuration file. Various approaches have been suggested including hierarchical label naming schemes (e.g. authelia.rules.0.domain=example.com), explicit priority labels to control ordering, and helper containers that generate configuration files from labels as an intermediate step.

Decision#

This proposal is rejected for the following reasons:

Rule Ordering#

Docker labels are an unordered key-value store. There is no reliable mechanism to enforce a specific ordering of labels across containers or even within a single container. Since Authelia’s access control system is strictly first-match and the evaluation order of rules directly determines the security outcome, an unordered source of rules is fundamentally incompatible. Any attempt to impose ordering (e.g. via numeric prefixes in label keys) would be fragile, error-prone, and a source of subtle security misconfigurations. While explicit priority labels have been proposed as a workaround, this approach is brittle when rules are distributed across many containers and provides no guarantees about the order of rules with the same priority.

Rule Complexity#

Access control rules can contain multiple complex criteria that interact with each other. Expressing these as Docker labels would require either a custom encoding scheme within label values (reducing readability and increasing the likelihood of syntax errors) or a very large number of labels per rule. For example, a single rule with domain, resources, subject, and policy criteria would require at minimum four labels, and rules with list-valued criteria (e.g. multiple groups or resource patterns) would require even more. Neither approach offers a practical improvement over the existing configuration file.

Merging Reliability#

Combining rules sourced from Docker labels with rules defined in the configuration file introduces significant ambiguity. It would be unclear where label-sourced rules are inserted relative to file-sourced rules, how conflicts or overlaps are handled, and how an administrator can reason about the effective rule ordering. This undermines the ability to audit and understand the security posture of the deployment.

Dynamic Mutation#

If labels are read dynamically (e.g. when containers start or stop), the access control rules would change at runtime without an explicit configuration change. This makes the security policy dependent on the state of the container orchestrator, which is difficult to audit, version control, or reproduce reliably. While this is presented as a benefit by proponents (e.g. automatic removal of stale rules), it introduces a class of problems where the security policy silently changes based on infrastructure state.

Docker Socket Security#

Implementing label-based configuration would require Authelia to have access to the Docker socket. Exposing the Docker socket to a container increases the attack surface, and while a socket proxy with read-only access mitigates some risk, it still provides the container with visibility into all running containers and their metadata, and the socket proxy itself still effectively has full root access to the system. This is a security trade-off that is difficult to justify for a security-critical application.

Deployment Scope#

Docker labels are only available in containerized deployments. Implementing and maintaining a label-based configuration system would add significant complexity for a feature that is inherently unavailable to users deploying Authelia on bare metal, in virtual machines, or via non-Docker orchestrators. The existing configuration file approach works uniformly across all deployment models.

Consequences#

Administrators must continue to define all access control rules in the Authelia configuration file. This ensures that the rule ordering is explicit, auditable, and under version control. While this requires maintaining a separate configuration file rather than co-locating policy with each service, it preserves the correctness and predictability of the access control system.

Users who desire a label-driven workflow can use external tooling (e.g. helper containers or scripts) to generate Authelia configuration files from Docker labels as a pre-processing step outside of Authelia itself.

Related ADRs#

N/A