Google, GitHub & Microsoft login

Why

The login page offers Google, GitHub, Microsoft, and email magic link. Each social button is only enabled when that provider's client ID and client secret are set in your environment — if they aren't, the button is shown disabled and labelled "(not configured)".

If you don't want to set up OAuth, just use the magic-link email flow — no config needed beyond a working SMTP provider.

Environment variables

Add these to .env at the repo root (or whatever env file your deployment loads):

# Google OAuth
GOOGLE_CLIENT_ID=…
GOOGLE_CLIENT_SECRET=…

# GitHub OAuth
GITHUB_CLIENT_ID=…
GITHUB_CLIENT_SECRET=…

# Microsoft / Entra ID OAuth (optional)
MICROSOFT_CLIENT_ID=…
MICROSOFT_CLIENT_SECRET=…
MICROSOFT_TENANT_ID=common   # default "common"; set your tenant id for single-tenant apps

# Required for OAuth callback URLs to be computed correctly
BETTER_AUTH_URL=http://localhost:3000   # local dev; docker-compose self-host uses http://localhost:43300

Each social button enables only when BOTH the client id and secret are set — restart after editing env.

Microsoft / Entra ID is also supported — register an app in the Azure portal and set the two MICROSOFT_* vars above. The flow mirrors GitHub: create the app, add the callback URL, then copy the client id + secret. Use this redirect URI:

https://<your-host>/api/auth/callback/microsoft
# replace <your-host> with your real domain; http://localhost:3000 for local dev, :43300 for docker-compose

Google OAuth — step by step

1. Open the Google Cloud Console and create a new project (or pick an existing one).
2. Navigate to APIs & Services → OAuth consent screen. Choose External, fill in the app name ("Octopus self-hosted" works), your email, and a support email. Add any scopes you want — Octopus only needs email and profile.
3. Go to APIs & Services → Credentials → Create credentials → OAuth client ID. Choose application type Web application.
4. Add an Authorized redirect URI:

   http://localhost:3000/api/auth/callback/google
   # replace localhost:3000 with your real domain (docker-compose self-host: localhost:43300)

5. Click Create. Copy the Client ID and Client Secret from the modal that appears.
6. Paste them into .env as GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET, restart the server.

GitHub OAuth — step by step

1. Open github.com/settings/developers (or for an org: Settings → Developer settings → OAuth Apps).
2. Click New OAuth App.
3. Fill in:
   • Application name: Octopus self-hosted (or whatever you want users to see on the consent screen)
   • Homepage URL: http://localhost:3000 (or your deployment URL)
   • Authorization callback URL: http://localhost:3000/api/auth/callback/github
4. Click Register application.
5. On the resulting page, copy the Client ID. Click Generate a new client secret and copy that too.
6. Paste them into .env as GITHUB_CLIENT_ID and GITHUB_CLIENT_SECRET, restart the server.

Heads up — this is the OAuth app used for signing in, not the GitHub App used for repo access and webhooks. Those are separate and live under GitHub Apps in the same Developer Settings page.

Verifying

After restarting:

1. Visit /login.
2. The Google and GitHub buttons should be clickable (not greyed out).
3. Click one — you should be redirected to the provider's consent screen, approve, then land back on the Octopus dashboard.

If a button is still disabled, the server didn't pick up your env changes — confirm the variables are spelled correctly and the dev server was fully restarted (not just hot-reloaded).

Self-hosting checklist

See the self-hosting guide for the full env-var reference. The OAuth pair is optional; magic-link email auth works without it as long as you've set up an SMTP provider.