Horizon
GuidesSign-in and OAuth

Test GitHub sign-in locally

Test GitHub OAuth App sign-in on localhost with a stable HTTPS callback URL from a Horizon tunnel and Auth.js.

Sign in with GitHub on your laptop while GitHub redirects to a stable HTTPS URL.

Before you begin

  • A Horizon account and the CLI (see Getting started)
  • A reserved subdomain for -s. Reserve one on the Subdomains page.
  • A Next.js App Router app with Auth.js installed (npm install next-auth@beta)
  • A GitHub account

This page covers a GitHub OAuth App, not a GitHub App.

Start a tunnel

Use -s with a subdomain you reserved. Without it, the subdomain is random and changes every run, so the callback URL you register in GitHub would point at a dead URL after a restart. Reserved subdomains are a paid feature, see Pricing.

hrzn tunnel http://localhost:3000 -s my-app
Output
HORIZON: Tunnel connected
  URL          https://my-app.hrzn.run (reserved)
  Forwarding   http://localhost:3000
  Request log  https://hrzn.run/dashboard/tunnels/my-app

Your public URL is https://my-app.hrzn.run. Keep this terminal open.

Create the OAuth App in GitHub

  1. Select your profile picture in the upper-right corner, then select Settings.
  2. In the left sidebar, select Developer settings, then OAuth apps.
  3. Select New OAuth App. On your first app, the button reads Register a new application.
  4. Set Application name to a name you recognize.
  5. Set Homepage URL to https://my-app.hrzn.run.
  6. Set Authorization callback URL to https://my-app.hrzn.run/api/auth/callback/github.
  7. Select Register application.
  8. On the app's page, copy the client ID and generate a client secret. Copy the secret.

GitHub accepts up to 10 callback URLs. To add another, select Add callback URL.

Configure Auth.js

Auth.js builds the redirect URI from the request. Horizon sets Host to localhost:3000 and sends the public host in X-Forwarded-Host. AUTH_TRUST_HOST=true tells Auth.js to trust X-Forwarded-Host. AUTH_URL pins the public URL. Auth.js says AUTH_URL is mostly unnecessary in v5, so treat it as a second guard.

Generate the secret.

npx auth secret

Add the environment variables.

.env.local
AUTH_SECRET=replace-with-the-generated-secret
AUTH_URL=https://my-app.hrzn.run
AUTH_TRUST_HOST=true
AUTH_GITHUB_ID=replace-with-your-client-id
AUTH_GITHUB_SECRET=replace-with-your-client-secret

Configure the provider.

auth.ts
import NextAuth from "next-auth";
import GitHub from "next-auth/providers/github";

export const { handlers, signIn, signOut, auth } = NextAuth({
  providers: [GitHub],
});

Expose the route handlers. This path makes the callback /api/auth/callback/github.

app/api/auth/[...nextauth]/route.ts
import { handlers } from "@/auth";

export const { GET, POST } = handlers;

Add a sign-in button.

app/page.tsx
import { signIn } from "@/auth";

export default function Home() {
  return (
    <form
      action={async () => {
        "use server";
        await signIn("github");
      }}
    >
      <button type="submit">Sign in with GitHub</button>
    </form>
  );
}

Start the app on port 3000.

npm run dev

Sign in through the public URL

Open https://my-app.hrzn.run in your browser. On the first visit, select Continue to site on the Before you continue page. Horizon shows this page once every 7 days per IP address. Then select Sign in with GitHub.

Don't start from http://localhost:3000. Your app would then send a different origin to GitHub.

Check it works

GitHub shows its authorization page. After you approve, your browser lands back on https://my-app.hrzn.run.

Your Horizon terminal prints a line for the callback. The status is a 3xx, because Auth.js redirects after it sets the session.

Output
  GET     302  /api/auth/callback/github

Troubleshooting

GitHub says the redirect_uri MUST match the registered callback URL

GitHub's error text is "The redirect_uri MUST match the registered callback URL for this application."

  • Compare Authorization callback URL with https://my-app.hrzn.run/api/auth/callback/github.
  • Check that the subdomain in GitHub matches the one you pass to -s.

The redirect URI in the request contains localhost

Your app built the redirect URI from the Host header, which Horizon sets to localhost:3000. Set AUTH_TRUST_HOST=true and AUTH_URL=https://my-app.hrzn.run in .env.local. Restart npm run dev, because Next.js reads .env.local at start.

Auth.js throws an UntrustedHost error

Auth.js requires trustHost to be true because it relies on the request's host header. Set AUTH_TRUST_HOST=true in .env.local and restart npm run dev.

The URL changed after a restart

You started the tunnel without -s, so Horizon gave you a new random subdomain. Restart with -s my-app and the registered URL stays valid. -s needs a subdomain you reserved, see Pricing.

The browser shows a Before you continue page

Horizon shows this page once every 7 days per IP address. Select Continue to site.

Nothing reaches your app

  • Check that the Horizon terminal is still running. If its last line is Connection lost. Reconnecting…, wait for Reconnected.
  • Check that the app listens on port 3000, the port in your tunnel command.

Next steps

Test Facebook Login locally

Test Facebook Login on localhost with a stable HTTPS redirect URI from a Horizon tunnel and Auth.js.

Test GitLab OAuth login locally

Sign in with GitLab on localhost by registering a stable HTTPS Redirect URI from a Horizon tunnel, with Auth.js in Next.js.

On this page

Before you beginStart a tunnelCreate the OAuth App in GitHubConfigure Auth.jsSign in through the public URLCheck it worksTroubleshootingGitHub says the redirect_uri MUST match the registered callback URLThe redirect URI in the request contains localhostAuth.js throws an UntrustedHost errorThe URL changed after a restartThe browser shows a Before you continue pageNothing reaches your appNext steps