Franklin ID Auth Component

React component library for easily integrating Franklin/Genoox authentication (using Auth0) into your application.

Installation

1npm install @genoox/franklin-id # or yarn add franklin-id, or bun install franklin-id
2# Make sure you have react and react-dom installed as well
3npm install react react-dom

Replace franklin-id with the actual published package name (e.g., @your-org/franklin-id) if you used a different name.

Prerequisites

Before using this component, ensure you have:

1. Configured an Auth0 Application: Set up an application in your Auth0 dashboard (likely a Single Page Application type).
2. Configured an Auth0 API: Set up an API in Auth0 that your application will interact with (e.g., https://genoox.eu.auth0.com/api/v2/).
3. Registered Callback URL: You need a backend endpoint (like the provided Supabase function) that handles the OAuth code exchange. Add the URL of this endpoint (e.g., https://<your-project-ref>.supabase.co/functions/v1/auth-callback) to the "Allowed Callback URLs" in your Auth0 Application settings.
4. Obtained Credentials: Note down your Auth0 Domain, Client ID, and the API Audience identifier.

Usage

Import the FranklinAuth component and provide the necessary configuration props.

1import React, { useState, useEffect } from 'react';
2import { FranklinAuth } from 'franklin-id'; // Use your package name
3
4// Configuration - Ideally load sensitive values from environment variables
5const AUTH0_DOMAIN = process.env.REACT_APP_AUTH0_DOMAIN || 'your-auth0-domain.auth0.com';
6const AUTH0_CLIENT_ID = process.env.REACT_APP_AUTH0_CLIENT_ID || 'your_auth0_client_id';
7const AUTH0_CALLBACK_URL = process.env.REACT_APP_AUTH0_CALLBACK_URL || 'https://<your-project-ref>.supabase.co/functions/v1/auth-callback'; // Your backend callback handler
8const API_AUDIENCE = process.env.REACT_APP_API_AUDIENCE || 'https://your-api-audience.com/';
9
10function App() {
11  const [isAuthenticated, setIsAuthenticated] = useState(false);
12  const [userProfile, setUserProfile] = useState<any>(null); // Store decoded ID token claims
13  const [accessToken, setAccessToken] = useState<string | null>(null);
14  const [authError, setAuthError] = useState<any>(null);
15
16  // Function to parse ID token (basic example, use a library like jwt-decode for robustness)
17  const parseJwt = (token: string) => {
18    try {
19      return JSON.parse(atob(token.split('.')[1]));
20    } catch (e) {
21      return null;
22    }
23  };
24
25  const handleLoginSuccess = (tokens: { idToken: string, accessToken: string }) => {
26    console.log("Authentication successful!");
27    setIsAuthenticated(true);
28    setAccessToken(tokens.accessToken); // Store access token in state (or context/memory)
29    setUserProfile(parseJwt(tokens.idToken)); // Decode ID token for user info
30    setAuthError(null);
31
32    // **IMPORTANT**: Avoid storing the Access Token in localStorage due to security risks (XSS).
33    // Store it in memory (React state, Context API, Redux, Zustand, etc.)
34    // You might store the ID token or a session flag in localStorage/sessionStorage if needed
35    // to check login status across page refreshes, but fetch a new Access Token when required.
36
37    // Example API Call:
38    // fetch('https://your.api.com/data', {
39    //   headers: { Authorization: `Bearer ${tokens.accessToken}` }
40    // })
41    // .then(...)
42  };
43
44  const handleLoginFailure = (error: any) => {
45    console.error("Authentication failed:", error);
46    setIsAuthenticated(false);
47    setAccessToken(null);
48    setUserProfile(null);
49    setAuthError(error);
50  };
51
52  const handleLogout = () => {
53    // Basic logout: clear local state
54    setIsAuthenticated(false);
55    setAccessToken(null);
56    setUserProfile(null);
57    setAuthError(null);
58    // TODO: Add redirect to Auth0 logout endpoint if needed for full session termination
59    // const logoutUrl = `https://${AUTH0_DOMAIN}/v2/logout?client_id=${AUTH0_CLIENT_ID}&returnTo=${window.location.origin}`;
60    // window.location.href = logoutUrl;
61  };
62
63  return (
64    <div>
65      <h1>My Application</h1>
66      {!isAuthenticated ? (
67        <div>
68          <p>Please log in.</p>
69          {/* Render the FranklinAuth component directly */} 
70          <FranklinAuth
71            auth0Domain={AUTH0_DOMAIN}
72            clientId={AUTH0_CLIENT_ID}
73            redirectUri={AUTH0_CALLBACK_URL} // Your backend callback handler
74            audience={API_AUDIENCE}
75            onAuthSuccess={handleLoginSuccess}
76            onAuthFailure={handleLoginFailure}
77            // scope="openid profile email" // Optionally override default scopes
78            // state="custom_state_value" // Optionally provide custom state
79          />
80          {authError && <p style={{ color: 'red' }}>Error: {authError.error_description || authError.error || 'Login failed'}</p>}
81        </div>
82      ) : (
83        <div>
84          <h2>Welcome, {userProfile?.name || 'User'}!</h2>
85          <img src={userProfile?.picture} alt="Profile" width="50" style={{ borderRadius: '50%' }} />
86          <p>You are logged in.</p>
87          <button onClick={handleLogout}>Logout</button>
88          {/* Add components that need the access token here */}
89          {/* Example: <UserProfileEditor accessToken={accessToken} /> */}
90        </div>
91      )}
92    </div>
93  );
94}
95
96export default App;

Component Props

Prop	Type	Required	Description
auth0Domain	string	Yes	Your Auth0 tenant domain (e.g., your-tenant.auth0.com).
clientId	string	Yes	The Client ID of your Auth0 Application.
redirectUri	string	Yes	The URL of your backend callback handler (e.g., Supabase function) that Auth0 should redirect to after login.
audience	string	Yes	The unique identifier (API Audience) of the API you want to get an Access Token for.
onAuthSuccess	(tokens: { idToken: string, accessToken: string }) => void	Yes	Callback function executed on successful authentication. Receives an object containing the idToken and accessToken.
onAuthFailure	(error: any) => void	Yes	Callback function executed on authentication failure. Receives the error object from Auth0.
scope	string	No	Optional. Space-separated list of OAuth scopes to request. Defaults to extensive Franklin/Genoox scopes. Override if needed.
state	string	No	Optional. A random string used for CSRF protection. If provided, your callback handler should verify it. Defaults to a placeholder.

Handling Tokens

• idToken (ID Token):
  • A JSON Web Token (JWT) containing claims about the authenticated user (e.g., name, email, picture).
  • Intended for the client application to understand who the user is.
  • Can be decoded (client-side) to display user profile information.
  • Verify its signature if making critical decisions based on it (usually handled server-side during code exchange).
• accessToken (Access Token):
  • A token (often a JWT, but can be opaque) that proves the user has authorized the application to access specific resources on their behalf (defined by the scope).
  • Intended for the Resource Server (your target API, e.g., https://franklin.genoox.com/api/v2/...).
  • Crucially, include this token in the Authorization: Bearer <accessToken> header when making requests to your protected API.
  • Security: Do NOT store Access Tokens in localStorage or sessionStorage as they are vulnerable to XSS attacks. Store them in application memory (React state, Context, etc.) and fetch new ones when needed (e.g., on page load if the user has a valid session indicated by an ID token or cookie).

Development

(Optional: Add details here if you want contributors to know how to build/test the library locally)

1# Clone the repo
2git clone ...
3cd franklin-id
4
5# Install dependencies
6bun install # or npm install / yarn install
7
8# Run the local dev server (if App.tsx is set up for testing)
9bun run dev # or npm run dev / yarn dev
10
11# Build the library
12bun run build # or npm run build / yarn build