OAuth Integration Library (Client & Server)

This library provides a unified way to integrate OAuth authentication in both React (Client-side) and Express (Server-side) applications. It supports multiple OAuth providers like Google, Facebook, GitHub, etc., and manages tokens, user authentication, and routing seamlessly.

---

Client-Side Integration (React)

1. Install Dependencies

Install the OAuth library:

npm install oauth-wrapper-lib

---

g

2. Setup OAuth Providers

Example setup with Google:

import { GoogleProvider } from "oauth-wrapper-lib/providers";
import OAuthClient from "oauth-wrapper-lib";

const google = new GoogleProvider({
  client_id: "YOUR_GOOGLE_CLIENT_ID",
  handleCallback: () => {}, // Optional callback function
});

const client = new OAuthClient({
  providers: [google],
  successRedirectUrl: "/landing", // Redirect on successful login
});

---

3. Wrap the React App

Wrap your app with the AuthProvider to make authentication accessible.

import { BrowserRouter, Routes, Route } from "react-router-dom";
import AuthProvider, { ProtectedRoute } from "oauth-wrapper-lib/react";
import Login from "./pages/Login";
import Landing from "./pages/Landing";

function App() {
  return (
    <BrowserRouter>
      <AuthProvider client={client}>
        <Routes>
          <Route
            path="/"
            element={
              <ProtectedRoute navigateTo="/landing" allowWhenUnauthenticated>
                <Login />
              </ProtectedRoute>
            }
          />
          <Route
            path="/landing"
            element={
              <ProtectedRoute navigateTo="/">
                <Landing />
              </ProtectedRoute>
            }
          />
        </Routes>
      </AuthProvider>
    </BrowserRouter>
  );
}

---

4. Use the useAuth Hook

Access authentication status, user data, and login/logout functionality.

import { useAuth } from "oauth-wrapper-lib/react";

const Login = () => {
  const { loginFn, isAuthenticated, user, logout } = useAuth();

  return (
    <div>
      <h2>Login Page</h2>
      {!isAuthenticated ? (
        <button onClick={() => loginFn("google")}>Login with Google</button>
      ) : (
        <div>
          <p>Welcome, {user.name}</p>
          <button onClick={logout}>Logout</button>
        </div>
      )}
    </div>
  );
};

---

5. Protect Routes with ProtectedRoute

Control route access based on authentication status.

<ProtectedRoute
  navigateTo="/login"
  allowWhenUnauthenticated={false} // Blocks unauthenticated users
>
  <Dashboard />
</ProtectedRoute>

---

Client-Side Props

AuthProvider Props

Prop	Type	Required	Description
client	OAuthClient	Yes	OAuth client instance.
children	ReactNode	Yes	Components to render.

useAuth Hook

Property	Type	Description
isAuthenticated	boolean	Whether the user is authenticated.
user	any	User data after login.
loading	boolean	Shows authentication loading state.
loginFn	(providerName: string)	Triggers login with a provider.
logout	() => void	Logs out the user.

ProtectedRoute Props

Prop	Type	Required	Default	Description
navigateTo	string	Yes	-	Redirect path if access is denied.
allowWhenUnauthenticated	boolean	No	false	Allows unauthenticated users if true.
children	ReactNode	Yes	-	Components rendered if access is granted.

---

Here’s the updated server-side integration guide with Express, reflecting the changes you mentioned:

---

Server-side integration with Express

Key Features

1. Customizable Routes:

   • The default route for OAuth authorization is /api/auth/[providername]/authorize.
   • This can be customized using the requestHandlerUrl option.

2. Custom JWT Payload:

   • Use the handleCallback method to process user data returned by the OAuth provider and define the payload to embed in the JWT.
   • By default, the raw provider data is embedded in the JWT if handleCallback is not specified.

3. Token Management:

   • Access Tokens: Short-lived tokens embedded in HTTP-only cookies.
   • Refresh Tokens: Allows you to fetch new access tokens when they expire.

4. Routes for Refresh and Logout:

   • /api/auth/refresh: Refresh the access token.
   • /api/auth/logout: Clear access and refresh tokens.

---

1. Install Required Dependencies

Install the required libraries:

npm install express cookie-parser jsonwebtoken dotenv
npm install --save-dev @types/express @types/jsonwebtoken

---

2. Setting Up OAuth in Express

require("dotenv").config();
const express = require("express");
const cookieParser = require("cookie-parser");
const { OAuthClient, GoogleProvider } = require("oauth-wrapper-lib");
const { AuthMiddleware, verifyJWT } = require("oauth-wrapper-lib/express");

const app = express();
app.use(cookieParser());

// Basic health route
app.get("/", (req, res) => res.send("OAuth Integration Working"));

// Google OAuth Provider Configuration
const google = new GoogleProvider({
  client_id: process.env.GOOGLE_CLIENT_ID,
  client_secret: process.env.GOOGLE_CLIENT_SECRET,
  requestHandlerUrl: "/api/google/auth", // Custom route instead of default
});

// OAuth Client Setup
const client = new OAuthClient({
  providers: [google],
  successRedirectUrl: "http://localhost:3000/dashboard", // Redirect after success
  errorRedirectUrl: "http://localhost:3000/error", // Redirect after error
  handleCallback: (providerData) => {
    // Customize the JWT payload
    return {
      userId: providerData.id,
      email: providerData.email,
      name: providerData.name,
    };
  },
});

// Use AuthMiddleware to handle routes automatically
app.use(AuthMiddleware(client));

// Endpoint to get authenticated user data
app.get("/me", verifyJWT, (req, res) => {
  return res.json({ message: "Authenticated User", user: req.user });
});

// Start the Express app
const PORT = process.env.PORT || 3000;
app.listen(PORT, () => {
  console.log(`Server running on http://localhost:${PORT}`);
});

---

3. Key Configuration Options

OAuth Client Configuration

Option	Description
providers	Array of OAuth provider instances (e.g., GoogleProvider, GitHubProvider).
successRedirectUrl	The URL to redirect the user after successful authentication.
errorRedirectUrl	The URL to redirect the user in case of an error.
handleCallback	A function to customize the payload for the JWT token. Defaults to embedding provider data.

GoogleProvider Configuration

Option	Description
client_id	The client ID provided by the OAuth provider.
client_secret	The client secret provided by the OAuth provider.
requestHandlerUrl	Optional custom URL for the OAuth authorization flow. Default: /api/auth/[providername]/authorize

---

4. Default and Customizable Routes

Default Routes

Route	Description
/api/auth/[providername]/authorize	Redirects the user to the OAuth provider for authentication.
/api/auth/[providername]/callback	Handles the callback from the OAuth provider after authentication.
/api/auth/refresh	Refreshes the access token using a valid refresh token.
/api/auth/logout	Clears access and refresh tokens, logging the user out.

Customizing the Routes

If you want to customize the route for authorization, use the requestHandlerUrl option when configuring the provider:

const google = new GoogleProvider({
  client_id: "YOUR_CLIENT_ID",
  client_secret: "YOUR_CLIENT_SECRET",
  requestHandlerUrl: "/api/google/auth", // Custom URL
});

---

5. Token Management

• Access Token: Short-lived tokens sent as HTTP-only cookies.
• Refresh Token: Allows fetching new access tokens when the old one expires.

Refresh Tokens

To refresh the access token, make a POST request to /api/auth/refresh:

POST /api/auth/refresh

The server will validate the refresh token and return a new access token.

Logout

To log out a user and clear the tokens, make a POST request to /api/auth/logout:

POST /api/auth/logout

---

6. Securing Routes with verifyJWT

You can protect specific routes using the verifyJWT middleware provided by the library:

app.get("/protected", verifyJWT, (req, res) => {
  res.json({ message: "Protected Route", user: req.user });
});

---

7. Setting Up Environment Variables

Create a .env file in your project root to store sensitive information:

BASE_URL = http://localhost:3000
JWT_SECRET=your_jwt_secret_key

---

8. Directory Structure

Your directory structure can look like this:

/your-project
  |- .env
  |- server.js (or app.js)
  |- /node_modules
  |- package.json
  |- package-lock.json

---

Summary

Key Features

1. Customizable Routes: Change default routes for flexibility.
2. Custom JWT Payload: Define what data to include in JWT using handleCallback.
3. Built-in Token Management: Access tokens, refresh tokens, and logout flows are handled seamlessly.
4. Secure Routes: Use verifyJWT to protect endpoints requiring authentication.

Important Routes

Route	Description
/api/auth/[providername]/authorize	Redirects the user for OAuth authentication.
/api/auth/refresh	Refreshes access tokens.
/api/auth/logout	Logs out the user.
/me	Protected route returning user details (requires verifyJWT).

---

Conclusion

This project provides a robust and secure OAuth integration using Express on the server-side and React on the client-side. It handles user authentication, JWT token management, and route protection seamlessly. With customizable OAuth flows and token handling, it ensures flexibility for various OAuth providers.