GitHub OAuth

Workers Auth supports GitHub OAuth 2.0 as a first-class authentication strategy. Users click a link, authorize on GitHub, and are redirected back with a session cookie — no client-side token handling needed.

How it works

1. User clicks "Sign in with GitHub"  ->  GET /auth/github
2. Server generates state, stores in KV, redirects to GitHub
3. User authorizes the app on GitHub
4. GitHub redirects back              ->  GET /auth/github/callback?code=xxx&state=xxx
5. Server validates state, exchanges code for access token
6. Server fetches user's primary email from GitHub API
7. Server creates user (if new), creates session
8. Server sets session cookie and redirects to your app

Setup

1. Create a GitHub OAuth App

1. Go to GitHub Developer Settings > OAuth Apps
2. Click New OAuth App
3. Set Authorization callback URL to https://your-app.workers.dev/auth/github/callback
4. Copy the Client ID and generate a Client Secret

2. Set secrets

wrangler secret put GITHUB_CLIENT_ID
wrangler secret put GITHUB_CLIENT_SECRET

3. Configure the strategy

import { GitHubStrategy } from 'workers-auth/authn/github';

GitHubStrategy({
  clientId: process.env.GITHUB_CLIENT_ID!,
  clientSecret: process.env.GITHUB_CLIENT_SECRET!,
  scopes: ['user:email'], // default
});

Configuration

Option	Type	Default	Description
clientId	string	required	GitHub OAuth App Client ID
clientSecret	string	required	GitHub OAuth App Client Secret
scopes	string[]	['user:email']	OAuth scopes to request

Routes registered

Route	Method	Description
/auth/github	GET	Redirects to GitHub authorization page
/auth/github/callback	GET	Handles the OAuth callback

User matching

Workers Auth fetches the user’s primary verified email from the GitHub API. If a user with that email already exists (e.g. from a magic link sign-in), the existing account is used. Otherwise, a new user is created.

This means users can sign in with either magic link or GitHub and are linked to the same account as long as they use the same email.

Frontend integration

<a href="/auth/github">Sign in with GitHub</a>

The entire flow is server-side redirects. No JavaScript required.