OAuth Authentication

The Auth wire supports OAuth 2.0 authentication with multiple providers. Users who authenticate via OAuth are automatically created in the database if they do not already exist.

Supported Providers

Provider	Environment Variables
Google	OAUTH_GOOGLE_CLIENT_ID, OAUTH_GOOGLE_CLIENT_SECRET
GitHub	OAUTH_GITHUB_CLIENT_ID, OAUTH_GITHUB_CLIENT_SECRET
Discord	OAUTH_DISCORD_CLIENT_ID, OAUTH_DISCORD_CLIENT_SECRET

Configuration

import { FluxKit } from "@fluxkitdev/core";
import { auth } from "@fluxkitdev/auth";

const app = new FluxKit({
  wires: [
    auth({
      oauth: {
        google: {
          clientId: process.env.OAUTH_GOOGLE_CLIENT_ID,
          clientSecret: process.env.OAUTH_GOOGLE_CLIENT_SECRET,
          callbackUrl: "/auth/google/callback",
          scopes: ["email", "profile"],
        },
        github: {
          clientId: process.env.OAUTH_GITHUB_CLIENT_ID,
          clientSecret: process.env.OAUTH_GITHUB_CLIENT_SECRET,
          callbackUrl: "/auth/github/callback",
          scopes: ["user:email"],
        },
      },
    }),
  ],
  database: { uri: process.env.MONGODB_URI },
});

OAuth Flow

1. Redirect to Provider

Direct the user's browser to the OAuth initiation endpoint:

GET /auth/google

This redirects the user to Google's consent screen.

# In your frontend
window.location.href = "http://localhost:3000/auth/google";

2. Handle Callback

After the user authorizes, the provider redirects back to your callback URL. FluxKit handles the token exchange automatically and redirects to your frontend with a JWT:

GET /auth/google/callback?code=...&state=...

The callback redirects to your frontend with the token:

http://localhost:5173/auth/callback?token=eyJhbGci...

3. Use the Token

Your frontend extracts the token from the URL and stores it:

const params = new URLSearchParams(window.location.search);
const token = params.get("token");
localStorage.setItem("auth_token", token);

Programmatic API

// Get OAuth authorization URL
const url = app.auth.oauth.getAuthUrl("google", {
  state: "random-state-value",
});

// Exchange authorization code for user
const result = await app.auth.oauth.handleCallback("google", {
  code: "authorization-code",
});

console.log(result.user);  // User object
console.log(result.token); // JWT string

Linking OAuth to Existing Accounts

When a user authenticates via OAuth and an account with the same email already exists, FluxKit links the OAuth provider to the existing account rather than creating a duplicate.

// User's OAuth providers are tracked
const user = await app.auth.getUser(userId);
console.log(user.oauthProviders);
// => [{ provider: "google", providerId: "1234567890" }]

Custom OAuth Provider

You can register a custom OAuth 2.0 provider:

auth({
  oauth: {
    custom: {
      name: "my-provider",
      authorizationUrl: "https://provider.com/oauth/authorize",
      tokenUrl: "https://provider.com/oauth/token",
      userInfoUrl: "https://provider.com/api/userinfo",
      clientId: process.env.CUSTOM_CLIENT_ID,
      clientSecret: process.env.CUSTOM_CLIENT_SECRET,
      callbackUrl: "/auth/custom/callback",
      scopes: ["openid", "email"],
      mapUser: (profile) => ({
        email: profile.email,
        name: profile.display_name,
      }),
    },
  },
});

Frontend Redirect Configuration

Set the URL where users are redirected after OAuth:

Variable	Default	Description
OAUTH_SUCCESS_REDIRECT	/auth/callback	Redirect URL on success
OAUTH_FAILURE_REDIRECT	/auth/error	Redirect URL on failure
OAUTH_FRONTEND_URL	http://localhost:5173	Frontend base URL