Local HTTPS for OAuth callbacks
Some OAuth providers refuse an http:// redirect URI, even on localhost.
The https compose profile puts Caddy in front of integration-server at
https://localhost, signed by Caddy’s own local CA. You don’t need a domain,
Let’s Encrypt, or any inbound access to your machine. The OAuth callback is a
browser redirect, so the provider never connects to it.
Adapters that work on http://localhost:3010 today keep working as they are.
Only the adapters whose provider needs https get an https Redirect URI.
1. Start the profile
Section titled “1. Start the profile”docker compose --profile https up -dOr put COMPOSE_PROFILES=https in .env to have every compose command
include it. The profile adds one container, caddy, which publishes
127.0.0.1:443 (loopback only) and proxies everything to
integration-server:3010. Config: deploy/local-https/Caddyfile.
2. Trust the local CA (once)
Section titled “2. Trust the local CA (once)”scripts/trust-local-https-ca.shThe script copies Caddy’s root certificate out of the container and adds it to
the system trust store: the macOS System keychain (you’ll be asked for sudo),
update-ca-certificates on Debian/Ubuntu, or trust anchor on Fedora/Arch.
It does nothing if the CA is already trusted. Firefox and Linux browsers can
keep their own store; the script prints what to do if they still warn.
Check it:
curl -sS -o /dev/null -w '%{http_code}\n' https://localhost/health # 200, no -kThe CA lives in the caddy-data volume. If you remove that volume, Caddy
creates a new CA, and you need to run the script again.
Security: anyone who has the CA key (the
caddy-datavolume) can mint certificates this machine will accept for any hostname. Use the profile only on dev machines, and runscripts/trust-local-https-ca.sh --removewhen you’re done with it.
3. Point the adapter at https
Section titled “3. Point the adapter at https”For each platform whose provider needs https:
- In the admin console, open the platform under Platforms and set Redirect URI to
https://localhost/auth/{vertical}/{platform}/callback. - Register the same URL in the provider’s developer console. Most providers accept several redirect URIs, so you can keep an http entry next to it while you migrate.
Leave every other adapter alone. PUBLIC_BASE_URL stays
http://localhost:3010, so Connect Links are still served over http. After
the https callback, the customer lands back on
http://localhost:3010/connect/<token>/done as before. TRUST_PROXY is not
needed either, because PUBLIC_BASE_URL is pinned.
Why http and https adapters can coexist
Section titled “Why http and https adapters can coexist”The token exchange repeats the redirect_uri that the adapter’s authorize URL
actually sent, as RFC 6749 §4.1.3 requires. That value comes from the
adapter’s own Redirect URI field. The URI derived from PUBLIC_BASE_URL is
used only when an authorize URL carries none. So the scheme is chosen per
adapter, and both callback origins reach the same /auth/{vertical}/{platform}/callback
route. See the OAuth sequence in
architecture/runtime-flows.md.
When this is not enough
Section titled “When this is not enough”- Port 443 is taken. Publish another host port in
docker-compose.override.yml:Then useservices:caddy:ports: !override- '127.0.0.1:8443:443'https://localhost:8443/auth/…/callbackas the Redirect URI. Some providers reject a URI that includes a port. - The provider rejects
localhostaltogether, or insists on a public domain. Use a tunnel (Cloudflare Tunnel, ngrok) with a real hostname and certificate, then follow deployment/custom-domain.md. - Inbound webhooks. These are server-to-server, so the provider does have to reach you. A tunnel is the only local option here too.
docker compose --profile https stop caddyscripts/trust-local-https-ca.sh --remove # if you won't need it againopensteward.dev ·Plans and free license ·Terms ·Privacy ·support@opensteward.dev
© 2026 Falco Consulting AB. Built from open-steward/opensteward@a3961d8. This site sets no cookies, runs no analytics and loads nothing from other sites, except platform logos from Brandfetch on the Platforms page.