Environment Variable Parsing#

Tinyauth reads configuration from environment variables using the paerser library — a Go library for loading configuration into structs from multiple sources. All Tinyauth env vars share the prefix TINYAUTH_ 1, and a dedicated EnvLoader handles the full parsing lifecycle.

How It Works#

The parsing pipeline runs in two steps inside EnvLoader.Load:

1. Filter — env.FindPrefixedEnvVars inspects the target configuration struct via reflection and returns only the env vars whose names start with a field-derived prefix 2. This avoids processing irrelevant env vars.

2. Decode — env.Decode converts the filtered vars into a typed Go struct through four internal stages 3:

   • Strip the TINYAUTH_ prefix and lowercase + normalize: TINYAUTH_SERVER_PORT → tinyauth.server.port (underscores become dots)
   • parser.DecodeToNode splits each dot-separated key into a tree of untyped nodes
   • parser.AddMetadata augments nodes with type/kind info inferred from the target struct
   • parser.Fill populates the typed struct from the annotated node tree

The full three-stage parser pipeline is defined in parser.Decode.

Naming Conventions#

For slices, multiple values are comma-separated in a single env var 4.

Dynamic Map Keys#

The most nuanced aspect is how paerser resolves map keys at runtime. Because env var names are static strings, the segment that represents a map key is inferred positionally by comparing the remaining path segments against the struct type. When paerser encounters a map[string]T field during AddMetadata, the next path segment becomes the map key.

For example, a map[string]UserAttributes field named UserAttributes is populated by:

TINYAUTH_AUTH_USERATTRIBUTES_alice_EMAIL=alice@example.com
TINYAUTH_AUTH_USERATTRIBUTES_bob_EMAIL=bob@example.com

The segment after USERATTRIBUTES (alice, bob) becomes the map key, and everything after is decoded into the value struct. This is demonstrated exhaustively in the paerser test suite, including nested maps (map[string]struct{ Bar map[string]struct{ Value string } }) decoded from a single flat env var like TRAEFIK_FOO_NAME1_BAR_NAME2_VALUE=bar 5.

In documentation and generated reference output, dynamic map keys are shown as <NAME> (the MapNamePlaceholder constant, value "<name>") — e.g. TINYAUTH_AUTH_USERATTRIBUTES_<NAME>_EMAIL 6.

Key Configuration Struct Fields Using Maps#

From the Tinyauth config model, the main map-keyed fields that can be configured via env vars are:

• auth.UserAttributes → map[string]UserAttributes — per-user OIDC claim overrides 7
• Apps → map[string]App — per-application ACL rules 8
• oauth.Providers → map[string]OAuthServiceConfig — named OAuth provider configs
• oidc.Clients → map[string]OIDCClientConfig — named OIDC client configs

Key Entry Points#