Debug Next.js OAuth Behind an HTTPS Tunnel

Understand the OAuth request path before changing settings

A tunneled OAuth flow crosses several boundaries. The browser begins at a public HTTPS address, the authorization request goes to the identity provider, the provider redirects the browser to a registered callback URI, and the tunnel carries that callback to a Next.js service listening on a local interface or inside a container. The application then validates temporary OAuth data, exchanges the authorization code where required, creates a session, and redirects the browser again.

Every participant must agree on the externally visible origin. In this article, public origin means the scheme and authority visible to the browser, such as https://public-name.example. The complete callback URI also includes the callback path expected by the authentication implementation. A mismatch in scheme, host, port, path, slash handling, or letter case can be significant because OAuth providers generally compare redirect URIs strictly.

The local target is different. It is the IP address and port where the Localtonet client can reach Next.js. It might use plain HTTP even though the browser uses HTTPS, because these values describe different legs of the request. The public callback must not be rewritten to the local target merely because Next.js ultimately receives the request there.

Collect the exact values and version-specific requirements

Do not begin by copying environment variables from an unrelated tutorial. Next.js authentication integrations have changed over time, providers expose different console interfaces, and trusted-host or proxy behavior can depend on the installed authentication-library version. The private evidence supplied for this draft did not establish a specific Next.js release, Auth.js release, provider, callback route, environment-variable name, or trusted-host option. We therefore do not invent them.

Before troubleshooting, record the following values from the application and the current official documentation for the versions actually installed:

• The Next.js version and whether the relevant authentication route uses the App Router or Pages Router.
• The authentication package name and exact installed version.
• The OAuth provider and the provider’s currently registered callback URI.
• The callback path implemented by the installed package or custom route.
• The local listening address and port used by the running Next.js process.
• Whether Next.js runs directly on the client device, in Docker, or behind another local reverse proxy.
• The public HTTPS URL assigned to the Localtonet tunnel after it starts.
• The documented mechanism, if any, for setting the external application URL or trusting proxy-derived host information.
• The expected cookie names and attributes as observed in the browser, rather than inferred from another package version.

If a package manager lockfile is present, use it to identify the installed authentication version. If the application uses custom OAuth code, inspect the route that creates the authorization request and the route that receives the callback. In either case, determine where the callback URI comes from. It may be fixed in configuration, built from an application base URL, inferred from request headers, or supplied explicitly to the provider client.

Verify the Next.js application before adding remote access

The first useful boundary is the application itself. Confirm that the expected local service is running and that the Localtonet client device can reach it. A process merely appearing in a task list is not enough. It must listen on the intended address and port, and the authentication route must exist in the running build.

Test the local HTTP service

Set LOCAL_URL to the actual local URL already used by the application. Do not assume a framework default port.

export LOCAL_URL="http://LOCAL_IP:LOCAL_PORT"
curl -i "$LOCAL_URL"

A successful response proves only that the selected route is reachable. Next, test a harmless authentication entry route or callback route according to the installed implementation. A callback without provider parameters may intentionally return an error, but it should reach the expected Next.js handler rather than a different service, a container gateway error, or a generic 404.

If the service cannot be reached locally, stop here. Fix the listening address, local firewall policy, process state, port selection, container publishing, or reverse-proxy route before creating a public tunnel. OAuth configuration cannot repair a TCP connection that never reaches Next.js.

Capture a clean browser baseline

Use a fresh private browsing session or clear only the cookies associated with the test host. Start the sign-in flow once and inspect the browser’s network panel. Record:

• The first application URL used to initiate sign-in.
• The authorization request’s redirect_uri value, with sensitive values redacted.
• The provider response status and redirect location.
• The callback request host, path, status code, and response location.
• Which temporary cookies are created before leaving the application.
• Whether those cookies are attached to the callback request.

Avoid mixing local and public origins during a single test. If sign-in starts at a localhost URL but the provider returns to a public tunnel hostname, host-scoped cookies created on localhost will not automatically belong to the tunnel hostname. Start the entire test from the public URL once the tunnel is configured.

Expose the verified Next.js service with a Localtonet HTTP tunnel

With Localtonet, the client on the device establishes an outbound connection to one of our relay servers. This exposes the local service without inbound router port forwarding, firewall changes, VPN setup, or a public IP address. For a browser-based Next.js application, use an HTTP tunnel so the public side receives an HTTPS address while the tunnel points to the local IP address and port.

HTTP tunnels support Random Sub Domain, Custom Sub Domain, and Custom Domain process types. All three serve the same target content at a public HTTPS address. Availability can vary, so use only the choices currently presented for your account. Exact custom-domain DNS instructions are intentionally not included here because they must be checked against current Localtonet documentation.

For the current dashboard workflow, consult our Localtonet documentation alongside the fields shown in your account. Tunnel configuration and application authentication configuration are separate tasks. A tunnel can deliver requests correctly even while the OAuth provider rejects the callback URI, and an OAuth configuration can be correct while the local target remains unreachable.

Align the redirect URI, application origin, and forwarded request information

After the public application loads, construct the callback URI using two verified pieces: the assigned public HTTPS origin and the exact callback path required by the installed authentication implementation. Register that complete URI with the OAuth provider. Then verify what the application actually sends as redirect_uri in the authorization request.

These values should describe the same callback:

• The redirect URI registered in the provider console.
• The redirect_uri sent in the authorization request.
• The callback location to which the provider redirects the browser.
• The external origin expected by Next.js or the authentication library.
• Any allowlist or trusted-host setting required by the installed version.

Diagnose a provider-side redirect URI mismatch

A provider-side error usually occurs before the provider sends the browser back to Next.js. Compare the complete URI character by character. Pay particular attention to http versus https, an old tunnel hostname, an explicit port, the callback path, a trailing slash, and accidental whitespace in configuration.

Do not solve this by registering a broad or guessed set of callbacks. Register the precise public callback required for the active environment. If the provider has separate development and production applications, keep their credentials and callback registrations clearly separated.

Diagnose an incorrect callback generated by the application

If the authorization request contains localhost, an internal container hostname, plain HTTP, or a stale public hostname, the application is constructing its external URL incorrectly. Determine whether the installed authentication package expects an explicit application URL, derives it from the incoming request, or supports a documented trusted-proxy mode.

Use only the configuration name documented for the exact installed version. Auth.js and related integrations have version-specific behavior, and this draft has no verified evidence for one universal environment variable or trusted-host switch. Adding a plausible but unsupported variable can conceal the real problem while leaving the application on its default behavior.

Inspect forwarded host and protocol carefully

Reverse proxies commonly communicate the original host and scheme through forwarded request headers. However, this article does not claim a specific Localtonet header set because that detail is not established by the supplied product context. Inspect what the application actually receives in your environment.

Add temporary, sanitized server-side diagnostics around the authentication route if the framework and deployment permit it. Log only the request URL, host-related header names and sanitized values, protocol-related header names and values, and route path. Never log cookies, authorization headers, OAuth codes, state, nonce, or tokens.

If another reverse proxy sits between the Localtonet target and Next.js, that proxy may overwrite, append, or discard forwarded information. Test each hop independently. First target Next.js directly if that is safe and practical. Then reintroduce the local proxy. A result that changes when the local proxy is added points to that proxy’s host or protocol handling rather than to the provider.

Debug missing state, nonce, PKCE, and session cookies

OAuth implementations use temporary browser state to bind the callback to the sign-in attempt. Depending on the provider and library, this can include state, nonce, and PKCE verifier data. If the callback reaches Next.js but the corresponding cookie is absent, expired, scoped to another host or path, or rejected by the browser, the application may report a state or nonce error, fail the PKCE exchange, or restart sign-in.

Start and finish on one public hostname

The cleanest rule is to initiate the OAuth flow from the same public hostname that receives the callback. Opening the application at localhost and returning through the tunnel crosses hostname boundaries. A host-only cookie created for localhost is not sent to the public tunnel hostname.

Tunnel hostnames can also change when a tunnel is recreated or when a different process type is selected. If the public hostname changes, update the provider registration and the application’s verified external-origin configuration, then start a new private browsing session. Old cookies and cached redirects can otherwise make the new test look inconsistent.

Inspect attributes rather than guessing cookie names

In the browser’s storage and network tools, identify the temporary cookie set immediately before the redirect to the provider. Record its domain or host scope, path, Secure status, SameSite value, expiry, and whether the browser reports that it was blocked. On the callback request, confirm whether the browser sends it.

A Secure cookie requires an HTTPS browser context. The Localtonet HTTP tunnel provides a public HTTPS address for this workflow, but the application must still recognize the external request context correctly when deciding how to create cookies. If the application incorrectly believes the external origin is HTTP, its generated cookie or redirect behavior may not match the public flow.

SameSite behavior depends on the exact navigation and cookie configuration. Do not force a particular SameSite value based on a generic tutorial. Use the authentication library’s documented defaults for the installed version unless there is a verified need to override them. If an override is necessary, evaluate the security effect as well as whether it makes the callback work.

Recognize the common callback loop

A loop often looks like this: the callback reaches the application, the application cannot validate temporary state or establish a session, it redirects to sign-in, and the cycle begins again. The first failed callback is the important request. Later requests are consequences.

Inspect the first callback response and ask:

• Did the callback request contain the expected temporary cookie?
• Did the callback reach the correct route and application instance?
• Did the application calculate the expected public origin?
• Was a session cookie returned, and did the browser accept it?
• Did the response redirect to the public hostname or switch to localhost, HTTP, or an old hostname?
• Are multiple application instances using compatible secret and session configuration?

Clear stale cookies only after preserving enough evidence to identify why the browser rejected or omitted them. Repeatedly clearing cookies can temporarily hide a scope problem without explaining it.

Fix callbacks that reach the tunnel but not the Next.js container

Docker introduces a separate routing question: which address is reachable from the device running the Localtonet client? A container’s internal address, the host’s loopback interface, a published host port, and a service name on a container network are not interchangeable.

The safest target is the exact host-side address and port that already succeeds when tested from the Localtonet client’s environment. If the client runs on the Docker host, verify that the container publishes the intended application port to an appropriate host interface. If the Localtonet client itself runs in another container, both containers need an intentional network path, and a host loopback address inside one container does not refer to the other container.

Separate bind failures from tunnel failures

A Next.js process may be healthy inside its container while listening only on an interface that is not reachable through the published path. Conversely, Docker may publish a port but direct it to the wrong internal port. Use the project’s actual startup configuration and container definition to confirm both sides. This article does not prescribe a port or listening-host flag because no version-specific application configuration was supplied.

Test from progressively closer locations:

1. From inside the application container, request the application’s actual listening endpoint.
2. From the Docker host, request the published host address and port.
3. From the Localtonet client environment, request the precise target configured in the tunnel.
4. Only after all three succeed, test the public HTTPS URL.

If step one fails, investigate Next.js startup. If step one succeeds but step two fails, investigate the container bind or port publication. If step two succeeds but step three fails, investigate which network namespace contains the Localtonet client. If all local tests succeed but the public request fails, check the selected device, tunnel state, target values, and whether the request is reaching the expected service.

Use a boundary-by-boundary diagnostic workflow

The fastest investigation changes one variable at a time and identifies the first boundary that fails. Do not simultaneously replace the callback URI, change cookie flags, add proxy-trust options, recreate the tunnel, and modify Docker networking. That produces a working or broken result without explaining which change mattered.

Interpret the final status code in context

A successful network delivery does not necessarily produce a successful OAuth result. A response from Next.js with an authentication error proves that the callback reached the application, which narrows the problem to route handling, provider exchange, temporary state, session creation, or origin validation. A connection failure indicates an earlier routing boundary. A provider-hosted redirect error indicates the request was rejected before the callback.

Similarly, a 404 can mean the callback path is incorrect, the deployed build lacks the route, a local reverse proxy removed a path prefix, or the tunnel targets another process. Compare the public callback path with the path received by the application before changing provider credentials.

Keep OAuth debugging safe

A development tunnel creates a real public entry point. Treat it as internet-accessible even if the hostname is difficult to guess. Expose only the service and routes needed for the test, retain application authentication, and stop or delete the tunnel when remote access is no longer required.

Use separate development OAuth credentials where the provider supports that operational model. Keep client secrets in the application’s approved secret-management mechanism, not in browser code or repository files. A public OAuth client may have different credential behavior from a confidential server-side client, so follow the provider’s current documentation rather than transferring assumptions between client types.

Redact query parameters from callback logs because authorization codes and state values can appear in them. Avoid recording full cookie headers. If temporary diagnostics must reveal host or protocol processing, log only the minimum fields and remove that code after the investigation.

Frequently asked questions