Configuration HTTP Integrations

Configuration HTTP Integrations

Purpose

Use this skill to wire caddy-security's route-level HTTP integrations: authenticate [<matcher>] with <portal> and authorize [<matcher>] with <policy>.

The security app defines authentication portals and authorization policies; the HTTP integrations attach those configured objects to Caddy routes. Portal internals belong to configuration-authentication; policy internals belong to configuration-authorization. Route mounting does not require reloading either owner unless its configuration also needs changes.

Prefer names that reveal the referenced object type in generated examples, such as myportal or local_portal for portals and app_policy or local_policy for policies. Policy names are not required to end in _policy, but the suffix makes authorize with <policy> intent clear.

Use authentication portal myportal with authenticate with myportal, or choose a descriptive portal name. Avoid authentication portal portal in examples, fixtures, and tests; the repeated word obscures the declaration's name.

Read these files when details matter:

• plugin_authn.go for authenticate syntax and directive order.
• plugin_authz.go for authorize syntax and directive order.
• assets/config/Caddyfile, assets/config/home.Caddyfile, and assets/config/multiportal.Caddyfile for current route shapes.
• testdata/caddyfile_adapt/testcase_authenticate_ok.Caddyfile, testdata/caddyfile_adapt/testcase_authorize_ok.Caddyfile, and testdata/caddyfile_adapt/testcase_authenticate_with_registration.Caddyfile for focused adapt fixtures.

Caddy Host Defaults

Cross-device login uses the existing portal handler for its entire mount-relative /cross-device namespace. Preserve the prefix and library strict-origin Referrer-Policy; no extra handler or CORS layer is needed. Provider realms named cross-device retain their own namespace. Use configuration-authentication-cross-device to review transfer paths, HTTPS/Origin boundaries and root/nested mount tests.

The selected Caddy v2.11.7 limits request headers to 16 KiB by default and defaults idle request-body reads and response writes to 60 seconds. Review large JWT/cookie sets and slow uploads or streams when upgrading. Tune Caddy's global servers options (max_header_size, timeouts read_body_idle and timeouts write_idle) only for a measured deployment need; these are host settings, not security directives. An idle deadline measures stalled I/O, not the whole request duration.

Caddy drops incoming dot-containing headers by default and controls underscore headers separately. Prefer ordinary hyphenated names for identity and proxy metadata. If a trusted integration needs other spellings, configure the host's expected_dot_headers or expected_underscore_headers deliberately and review hyphen/underscore/dot aliases together. The allowlists do not establish trust in client-supplied identity; trusted-proxy and authorization rules still apply.

The legacy Caddy authentication chain buffers individual provider responses when several providers are configured. Only the successful provider's response headers are retained; a failed provider must not contaminate another provider's success. Current authorize routes use AuthorizationHandler directly and preserve handled gatekeeper responses. See the published v2.11.6 changes and v2.11.7 fixes.

Route Roles

authenticate serves the authentication portal. Put it on the portal host or portal path, such as /auth and /auth/*. It is not the access-control layer for a file server or upstream app.

authorize protects resource routes. It loads an authorization policy, checks tokens or configured auth proxy methods, injects authenticated identity where configured, and redirects unauthenticated browser users to the policy's auth URL.

Keep portal and protected-resource routes separate:

example.com {
	@portal path /auth /auth/*
	route @portal {
		authenticate with myportal
	}

	route /app* {
		authorize with app_policy
		reverse_proxy 127.0.0.1:8080
	}
}

For same-host browser login, put the portal route before a catch-all protected route so the portal is not itself protected by authorize:

https://localhost:8443 {
	@portal path /auth /auth/*
	route @portal {
		authenticate with local_portal
	}

	route {
		authorize with local_policy
		root * /srv/files
		file_server browse
	}
}

The referenced policy should point browser users to the portal:

authorization policy local_policy {
	crypto key verify {env.JWT_SHARED_KEY}
	set auth url /auth
	allow roles authp/user
}

For split-host deployments, put authenticate on the auth host and authorize only on the protected app or asset host. Use a full auth URL when the portal is on a different host. A redirect alone does not transfer a host-only access cookie to the app host. For browser access across sibling hosts, coordinate the access-cookie domain/path, its policy-discovered name, and signing/verification keys; only trusted hosts may share that domain. OIDC/refresh cookies retain their own host and issuer constraints and must not be broadened automatically. Use configuration-authentication-cookies to configure cross-host access-cookie scope and validate prefix restrictions. For unrelated domains, a shared Domain attribute is impossible; choose an explicit token or separate authentication integration instead.

Edge Trust

Caddy owns trusted-proxy selection. The plugins preserve the trusted host and client-address interpretation before authcrunch sees a request; arbitrary forwarded headers cannot establish it. Read edge trust for direct/forwarded behavior, duplicate hints, current IPv6 limits, exact mount matching, and verification through actual Caddy TLS.

Public JWKS Routing

The portal serves access-token public keys at <mount>/.well-known/jwks.json through the existing authenticate handler. Place the portal before any protected catch-all and use path-segment boundaries when the deployment must keep neighboring prefixes private:

example.com {
	@portal path /auth /auth/*
	route {
		route @portal {
			authenticate with myportal
		}
		route {
			authorize with app_policy
			reverse_proxy 127.0.0.1:8080
		}
	}
}

This routes /auth/.well-known/jwks.json publicly while /authentication/ stays under the policy. A /tenant/auth mount uses /tenant/auth and /tenant/auth/* in the matcher. A dedicated root portal exposes /.well-known/jwks.json with the existing root authenticate route.

Do not put authorize before authenticate on the portal route or add a generic suffix-based bypass to the gatekeeper. Caddy owns mount selection; the library owns public discovery, method validation, and serialization. There is no discovery enable directive. See the HTTP contract.

Direct OAuth Routing

Direct OAuth without a portal uses the policy's own callback/logout namespace. Route that namespace and application resources through the same authorize handler. See direct OAuth. The directive now emits http.handlers.authorization, which preserves handled responses without allowing the protected handler to run. Legacy manually written JSON using authentication.providers.authorizer retains Caddy's generic authentication-chain behavior and should be regenerated for direct OAuth.