Implement Github OAuth login with Next.js and FastAPI

[nemanjam]

I wrote a practical walkthrough on Github OAuth login with FastAPI and Next.js. It focuses on clean domain separation, HttpOnly cookies, ease of deployment and why handling cookies in Next.js APIs/server actions simplifies OAuth a lot. Includes diagrams and real code.

https://nemanjamitic.com/blog/2026-02-07-github-login-fastapi-nextjs

Interested to hear what others think or if you've taken a different approach.

[Sagargupta16]

Nice walkthrough. The domain separation approach (FastAPI handles OAuth token exchange, Next.js handles cookie setting via server actions) is clean and avoids the common mistake of exposing tokens to the browser.

A few thoughts from having built auth systems with similar stacks:

What I liked

• HttpOnly cookies via Next.js server actions — this is the right call. Keeping the access token out of localStorage or client-side JavaScript prevents XSS-based token theft entirely.
• Clean separation — FastAPI does the OAuth dance and token validation, Next.js handles session/cookie management. Each layer does what it's best at.
• No NextAuth/Auth.js dependency — understanding the raw OAuth flow is valuable, and it avoids the abstraction overhead when you need custom behavior.

A few considerations for production use

1. Token refresh handling

GitHub OAuth tokens don't expire by default (unless you use the beta expiring tokens feature). But if someone adapts this pattern for other OAuth providers (Google, Microsoft), they'll need refresh token rotation. Worth mentioning where refresh would fit in the flow:

Next.js middleware (on every request)
  → Check cookie expiry
  → If expired, call FastAPI /auth/refresh endpoint
  → FastAPI uses refresh_token to get new access_token
  → Next.js server action sets new cookie

2. CSRF protection on the callback

The blog mentions the state parameter for OAuth, which is correct. One thing to verify — the state should be:

• Generated per-request (not a static value)
• Stored in a short-lived server-side session or signed cookie
• Validated on callback before exchanging the code

Without this, the callback endpoint is vulnerable to CSRF where an attacker tricks a user into linking the attacker's GitHub account.

3. Cookie security attributes

For the HttpOnly cookie, make sure all these flags are set in production:

# FastAPI side (if setting cookies there)
response.set_cookie(
    key="session",
    value=session_token,
    httponly=True,        # not accessible via JavaScript
    secure=True,          # only sent over HTTPS
    samesite="lax",       # CSRF protection
    max_age=86400,        # 24 hours
    path="/",
    domain=".yourdomain.com"  # shared across subdomains if needed
)

Or in Next.js server actions:

cookies().set('session', sessionToken, {
  httpOnly: true,
  secure: process.env.NODE_ENV === 'production',
  sameSite: 'lax',
  maxAge: 86400,
  path: '/',
});

SameSite=Lax is important — it prevents the cookie from being sent on cross-origin POST requests while still allowing normal navigation.

4. Alternative approach — same result, fewer round trips

Instead of Next.js calling FastAPI and then setting the cookie in two separate steps, you can have FastAPI return a short-lived signed JWT directly, and Next.js server action just validates and stores it:

GitHub → redirect to Next.js /api/auth/callback?code=xxx
  → Next.js server action calls FastAPI /auth/github/exchange with the code
  → FastAPI exchanges code for GitHub token, fetches user info, creates/finds user, returns signed JWT
  → Next.js sets JWT as HttpOnly cookie
  → Subsequent requests: Next.js middleware decodes JWT (no DB call needed for basic auth check)

This reduces the number of calls between Next.js and FastAPI on subsequent requests since the JWT is self-contained.

5. Deployment consideration

When FastAPI and Next.js are on different domains (e.g., api.example.com and app.example.com), cross-origin cookies get tricky. You either need:

• Both on the same parent domain with domain=.example.com on the cookie
• Or Next.js acts as a BFF (Backend for Frontend) proxy, so the browser only ever talks to the Next.js domain

The BFF pattern is simpler for cookie management since there's no cross-origin involved.

Great article overall — this is a pattern more people should adopt instead of defaulting to NextAuth for everything.