configuration-http-integrations

# Configuration HTTP Integrations ## Purpose Use this skill to wire caddy-security's route-level HTTP integrations: `authenticate [<matcher>] with <portal> [at <mount>]` 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](../configuration-authentication/SKILL.md); policy internals belong to [configuration-authorization](../configuration-authorization/SKILL.md). 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 at /auth`, 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_authenticate_explicit_mounts.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](../configuration-authentication-cross-device/SKILL.md) to review transfer paths, HTTPS/Origin boundaries and root/nested mount tests. The selected Caddy host 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. Check the selected Caddy `modules/caddyhttp/caddyauth/caddyauth.go` when reviewing this boundary. ## 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: ```caddyfile example.com { @portal path /auth /auth/* route @portal { authenticate with myportal at /auth } 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`: ```caddyfile https://localhost:8443 { @portal path /auth /auth/* route @portal { authenticate with local_portal at /auth } route { authorize with local_policy root * /srv/files file_server browse } } ``` The referenced policy should point browser users to the portal: ```caddyfile 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](../configuration-authentication-cookies/SKILL.md) 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](references/edge-trust.md) 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: ```caddyfile example.com { @portal path /auth /auth/* route { route @portal { authenticate with myportal at /auth } 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 `authenticate with myportal at /`. An explicit mount admits only its exact signing-key discovery path. Nested suffix impostors such as `/auth/other/.well-known/jwks.json` do not publish the keyset. Omitted mounts retain legacy dispatch and are not evidence of this explicit boundary. 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](../authentication-portal-api/SKILL.md#public-signing-key-discovery). ## 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](../configuration-authorization/SKILL.md#direct-oauth-without-a-portal). 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. ## Browser Refresh Routing Keep POST `<mount>/api/refresh_token`, `/api/refresh_session`, and `/api/logout` on the complete, unstripped portal route before any protected catch-all. The portal authenticates these operations using their own credentials, so expired access can renew or log out; other APIs stay protected. Forward the refresh/session headers, Origin/Fetch Metadata, cookies and body unchanged. Do not add retries, CORS allowances or gatekeeper suffix bypasses. Serve `<mount>/assets/js/refresh.js`, continuation, fresh login and logout confirmation through that same portal. Use top-level portal navigation for external application continuation; a GET link to `/api/refresh_token` is invalid. The embedded client does not renew arbitrary cross-origin applications. See the [browser HTTP/UI contract](../authentication-portal-api/references/browser-refresh.md). Native JSON login uses POST `<mount>/login` on the same unstripped portal route and requires neither admin nor profile APIs. Preserve the JSON body and error status/metadata. Do not synthesize Cookie, Origin or Fetch Metadata headers for native requests, strip supplied browser headers to evade transport validation, or infer an OIDC browser session from a bearer/API-key credential. The public Go client and explicit native refresh/logout contract are documented separately in [JSON/native interoperability](../authentication-portal-api/references/native-client.md). ## Portal Path Selection Default to exact `/auth` plus `/auth/*`, and point the policy's auth URL at that mount. Declare it with `authenticate with myportal at /auth`. Native handler JSON uses `"base_path": "/auth"`. The mount is a literal canonical absolute ASCII path requiring no URL escaping: use `/` for root, and omit the trailing slash for a nested mount. Semicolons are rejected because the path also scopes browser cookies. Placeholders and secret lookups are not supported in this field. Omitting `at`, or omitting/nulling native `base_path`, preserves legacy path inference. An explicit empty value is invalid. Caddy matchers still select the handler; the declaration adds validation and an independent request boundary. It neither creates a matcher nor inspects the enclosing route tree. If the upstream owns `/auth`, choose another namespace; a dedicated auth host can mount at `/`. Read [portal mount patterns](references/portal-mounts.md) for feature agreement, reserved names, path preservation and split-host alignment. ## Avoid Portal-Owned Prefixes Portal endpoint names constrain custom mount choices. Check the [reserved path contract](references/portal-mounts.md#avoid-portal-owned-prefixes) before choosing a prefix; an upstream namespace collision is resolved by moving the portal mount and its auth URL together. ## Syntax Prefer route blocks for clarity: ```caddyfile @portal path /auth /auth/* route @portal { authenticate with myportal at /auth } route /api/* { authorize with api_policy reverse_proxy 127.0.0.1:9000 } ``` The optional matcher form is valid when it keeps the surrounding Caddyfile smaller: ```caddyfile @portal path /auth /auth/* authenticate @portal with myportal at /auth authorize /api/* with api_policy ``` The portal or policy name must match a configured object in the `security` app. Keep subconfiguration inside `authentication portal <name>` and `authorization policy <name>` blocks. Do not put policy internals, such as `with api key auth ...`, under the route-level `authorize` directive; the route handler parser reads only the directive arguments. `authenticate` accepts no block; `at <mount>` occurs once at the end of its arguments. ## Directive Order Do not generate global Caddy directive-order overrides for caddy-security: ```caddyfile { order authenticate before respond order authorize before file_server } ``` Also do not generate `order authorize before basicauth` by default. The plugin already registers its order in code: - `authenticate` before `respond` - `authorize` before `basicauth` Only add global `order` directives when debugging a proven directive-order conflict with another third-party plugin, and explain the conflicting directive order. Do not use global order directives as a default fix for login failures, redirect loops, or authorization denials. Legacy docs-site examples and old solution briefs may still include global `order authenticate before respond` and `order authorize before basicauth` lines. Treat those examples as historical route-shape references, not as current guidance to copy into new Caddyfiles. ## Validation When changing mount syntax, use `TestAuthnMountCaddyfile`, `TestAuthnMountCaddyfileRejects`, `TestAuthnMountNativeValidation` and `TestCaddyfileAdaptAuthenticationToJSON`, followed by the app binding and real Caddy mount journeys described in the [mount reference](references/portal-mounts.md#validation). Parser success does not prove request containment or feature agreement. For skill-only edits, run the skill validator from `skill-creator`. ## Acceptance criteria - `/auth` and descendants reach the portal; `/authentic` does not. Protected handlers receive no call after denial or a handled OAuth callback. - An explicit custom mount preserves the original request path and aligns login, logout, callback, public JWKS and policy auth URLs. Reserved prefixes/segments and conflicting selected feature mounts reject the configuration. Legacy omission remains a compatibility mode with runtime inference. - A split-host browser login delivers the access cookie to the intended app and the policy finds and verifies it. Host-only cookie defaults cannot establish that flow. Preserve the narrower refresh/OIDC scopes and test both hosts. - Direct TLS and a configured trusted proxy agree on the intended identity and origin; hostile forwarded headers from untrusted peers cannot supply authority.