Cookie Domain Resolution#

Overview#

Tinyauth determines the cookie domain once at startup and stores it in RuntimeConfig.CookieDomain 1. The domain controls the scope of session cookies and directly affects whether a single login works across subdomains. The behavior is governed by a single config flag: auth.subdomainsEnabled (default: true) 2.

Core Logic: GetCookieDomain#

All resolution is handled by GetCookieDomain in internal/utils/app_utils.go. Given the AppURL and the subdomainsEnabled flag, the function:

1. Parses and lowercases the hostname from the app URL.
2. Rejects IP addresses — cookies cannot be scoped to an IP 3.
3. Requires at least two domain labels — single-label hostnames like localhost are rejected 4.
4. Strips the leftmost label when subdomainsEnabled=true and the hostname has 3+ labels — e.g., auth.example.com → cookie domain example.com, enabling shared cookies across all subdomains 5.
5. Validates against the Public Suffix List (via github.com/weppos/publicsuffix-go) — prevents cookies from being set on a public suffix like co.uk or github.io in both modes .

When subdomainsEnabled=false (or the hostname has exactly 2 labels), the full hostname is returned as-is — cookies are scoped to that exact host only 7.

Bootstrap Wiring#

During startup, app_bootstrap.go calls GetCookieDomain and stores the result in runtime.CookieDomain. If subdomainsEnabled is false, a warning is logged: "Subdomains are disabled, cookies will be set for the current domain only" 8.

AuthService reads runtime.CookieDomain via the private getCookieDomain() helper, which returns an empty string (no domain attribute on the cookie) when subdomains are disabled, or the pre-computed domain otherwise. This domain is applied to every session cookie: creation, refresh, and deletion .

Modes at a Glance#

Setting subdomainsEnabled=false was introduced in PR #710 to support running Tinyauth on a standalone or top-level domain (e.g., as a dedicated OIDC provider). The single GetCookieDomain function handling both modes was consolidated in PR #950.

Public Suffix List Validation#

The PSL check runs in both modes. If the resolved domain (or hostname) is itself a public suffix — e.g., github.io or co.uk — GetCookieDomain returns an error and startup fails 10.

Private/internal TLDs like .home, .lan, or .internal are not in the Public Suffix List, so they pass validation normally. A known limitation: 2-part private hostnames (e.g., tinyauth.home) are not stripped further even when subdomain mode is enabled, which can prevent cross-subdomain cookie sharing in private DNS environments 11.

Domain Validator Utility (pkg/validators)#

PR #1000 introduced a separate DomainValidator in pkg/validators/domain_validator.go. This is not used for cookie domain resolution — it is used for OAuth redirect URI validation and ACL domain matching. Key behaviors 12:

• Normalizes hostnames: lowercases, removes trailing dot, converts to ASCII via IDNA (golang.org/x/net/idna)
• Rejects IP addresses
• Optionally enforces scheme and port matching
• Errors: ErrSchemeMismatch, ErrPortMismatch, ErrHostnameMismatch, ErrInvalidURL

Key Files and References#