Policy Engine#

Tinyauth's policy engine is the central access-control decision system that evaluates every inbound proxy request. It lives in internal/service/policy_engine.go and is invoked by ProxyController.proxyHandler.

Core Concepts#

Effect and Policy#

Each rule returns one of three outcomes 1:

When a rule abstains, effectToAccess resolves the outcome against the configured global policy:

• PolicyAllow (default) — abstain → allow
• PolicyDeny — abstain → deny

The global policy is set via auth.acls.policy (values: "allow" or "deny", default "allow") and was introduced in PR #852.

ACLContext#

Every rule receives an ACLContext carrying:

• ACLs — the matched *model.App (per-app config)
• UserContext — authenticated user (provider, email, groups)
• IP — client IP address
• Path — request path
• TrustedProxiesConfigured — whether trusted proxies are set (affects IP rules)

Rule Evaluation Order#

proxyHandler evaluates rules in strict sequence. Each rule short-circuits on a definitive outcome:

1. RuleIPBypassed 2 — If the client IP is in the global or per-app ip.bypass list, skip authentication entirely and return 200. Requires trusted proxies to be configured; otherwise always abstains. 3

2. RuleAuthEnabled 4 — Evaluates path.allow and path.block regex patterns. If the request path matches the allow pattern (and is not blocked), returns EffectAllow, bypassing authentication for that path. 5

3. RuleIPAllowed 6 — Merges global and per-app ip.block / ip.allow CIDR lists. Block list is checked first; then allow list. If no trusted proxies are configured, always returns EffectAllow to avoid blocking behind a Docker bridge. 7

4. RuleUserAllowed 8 — For OAuth users, checks the per-app oauth.whitelist (email filter). For local users, checks users.block first, then users.allow. An empty allow list returns EffectAbstain. 9

5. RuleOAuthGroup / RuleLDAPGroup 10 — Applied only to OAuth or LDAP users respectively. If no groups are configured on the app, returns EffectAllow to avoid breaking deny-policy setups. Otherwise, the user must belong to at least one group in the configured list. 11

Request
  │
  ├─ IP in bypass list? → 200 (skip auth)
  ├─ Path bypasses auth? → 200 (skip auth)
  ├─ IP blocked/not allowed? → 403 /unauthorized
  ├─ User not allowed? → 403 /unauthorized
  ├─ Group check fails? → 403 /unauthorized
  └─ Unauthenticated? → 401 redirect to /login

OAuth Access Control#

For OAuth users, two rules are relevant:

• Email whitelist (RuleUserAllowed): AppOAuth.Whitelist is a comma-separated list of allowed email addresses or glob patterns. A match returns EffectAllow; no match returns EffectDeny. If the whitelist is empty, EffectDeny is still returned for OAuth users — unlike local users where an empty allow list abstains — so OAuth users require an explicit whitelist entry. 12

• Group membership (RuleOAuthGroup): AppOAuth.Groups restricts access to users whose provider-supplied groups include at least one entry matching the configured list. Providers registered in model.OverrideProviders skip the group check entirely. 13

Key Files#

Configuration Reference#

All ACL fields are comma-separated strings unless noted. Label-based equivalents follow the pattern tinyauth.apps.<name>.<field>.