@dwn-protocol/one-auth

A React library for OIDC/OAuth authentication. Provides a simple way to add authentication to your React applications with login redirects, callback handling, token management, and user session management.

Installation

npm install @dwn-protocol/one-auth
# or
pnpm add @dwn-protocol/one-auth
# or
yarn add @dwn-protocol/one-auth
# or
bun add @dwn-protocol/one-auth

Dependencies

Peer Dependencies

This library requires the following peer dependencies to be installed in your project:

• react (^18.0.0 or ^19.0.0)
• zustand (^5.0.0)

npm install react zustand
# or
bun add react zustand

Integration Steps

Step 1: Configure Environment Variables

Create a .env file in your project root (or use import.meta.env in Vite):

# Required: OAuth issuer URL
VITE_OAUTH_ISSUER=https://auth.abaxxone.com

# Required: OIDC client ID
VITE_PRIVATE_OIDC_CLIENT_ID=YOUR_CLIENT_ID

# Required: OAuth redirect URI (must match your app's callback route)
# For enterprise connector tenants i.e. Microsoft Entra/AD, Google Enterprise 
# this must be added to your Enterprise redirect/callback list
VITE_OAUTH_REDIRECT_URI=https://your-app.com/callback

# Required: OIDC well-known configuration endpoint
VITE_PRIVATE_OIDC_WELL_KNOWN=https://auth.abaxxone.com/.well-known/openid_configuration

Important Notes:

• Never commit secrets to version control
• The redirect_uri must exactly match the callback URL configured in your OAuth application settings

Step 2: Wrap Your App with the Provider

Wrap your application with AbaxxOneAuthProvider at the root level:

import { AbaxxOneAuthProvider } from '@dwn-protocol/one-auth';

function App() {
  return (
    <AbaxxOneAuthProvider>
      {/* Your app components */}
    </AbaxxOneAuthProvider>
  );
}

Optional: Custom Configuration

You can override environment variables by passing a config prop:

<AbaxxOneAuthProvider
  config={{
    issuer: 'https://custom-auth.example.com',
    clientId: 'custom-client-id',
    redirectUri: 'https://custom-app.com/callback',
  }}
>
  {children}
</AbaxxOneAuthProvider>

Step 3: Create a Login Component

Use the useAbaxxOneAuth hook to access authentication state and actions:

import { useAbaxxOneAuth } from '@dwn-protocol/one-auth';

function LoginButton() {
  const { login, isAuthenticated, user } = useAbaxxOneAuth();

  if (isAuthenticated) {
    return <div>Welcome, {user?.email}!</div>;
  }

  return <button onClick={login}>Log In</button>;
}

Step 4: Handle the OAuth Callback

Create a callback route component to handle the OAuth redirect:

import { useEffect } from 'react';
import { useNavigate } from 'react-router-dom';
import { useAbaxxOneAuthContext, handleOAuthCallback } from '@dwn-protocol/one-auth';

export function Callback() {
  const navigate = useNavigate();
  const { store } = useAbaxxOneAuthContext();

  useEffect(() => {
    handleOAuthCallback(store)
      .then(() => {
        // Redirect to dashboard after successful authentication
        navigate('/dashboard');
      })
      .catch((error) => {
        console.error('Authentication error:', error);
        // Redirect to home on error
        navigate('/');
      });
  }, [store, navigate]);

  return (
    <div>
      <p>Completing authentication...</p>
    </div>
  );
}

Important: Make sure your routing setup includes the callback route:

import { BrowserRouter, Routes, Route } from 'react-router-dom';

function App() {
  return (
    <AbaxxOneAuthProvider>
      <BrowserRouter>
        <Routes>
          <Route path="/callback" element={<Callback />} />
          {/* Other routes */}
        </Routes>
      </BrowserRouter>
    </AbaxxOneAuthProvider>
  );
}

Step 5: Protect Routes

Use the ProtectedRoute component to protect routes that require authentication:

import { ProtectedRoute } from '@dwn-protocol/one-auth';

function App() {
  return (
    <Routes>
      <Route path="/login" element={<LoginPage />} />
      <Route
        path="/dashboard"
        element={
          <ProtectedRoute redirectTo="/login">
            <Dashboard />
          </ProtectedRoute>
        }
      />
    </Routes>
  );
}

API Reference

useAbaxxOneAuth()

Hook to access authentication state and actions.

Returns:

{
  // State
  user: User | null;
  isAuthenticated: boolean;
  isLoading: boolean;
  error: string | null;
  accessToken: string | null;
  
  // Actions
  login: () => void;
  logout: () => void;
  getUser: () => User | null;
  getAccessTokenSilently: () => Promise<string | null>;
  clearError: () => void;
}

Example:

function MyComponent() {
  const {
    user,
    isAuthenticated,
    accessToken,
    login,
    logout,
  } = useAbaxxOneAuth();

  if (!isAuthenticated) {
    return <button onClick={login}>Log In</button>;
  }

  return (
    <div>
      <p>Logged in as {user?.email}</p>
      <button onClick={logout}>Log Out</button>
    </div>
  );
}

ProtectedRoute

Component that protects routes by redirecting unauthenticated users.

Props:

interface ProtectedRouteProps {
  children: React.ReactNode;
  redirectTo?: string;  // Default: '/'
  fallback?: React.ReactNode;  // Custom loading component
}

Example:

<ProtectedRoute redirectTo="/login" fallback={<CustomLoader />}>
  <Dashboard />
</ProtectedRoute>

handleOAuthCallback(store)

Utility function to handle OAuth callback processing.

Parameters:

• store: The auth store from useAbaxxOneAuthContext()

Returns: Promise<void>

Type Definitions

User

interface User {
  email: string;
  did?: string;
  sub?: string;
  [key: string]: any;
}

AuthConfig

interface AuthConfig {
  issuer?: string;
  clientId?: string;
  redirectUri?: string;
  wellKnown?: string;
}

How It Works

1. Login Flow: When login() is called, the user is redirected to the OAuth authorization endpoint with the appropriate OIDC parameters.

2. Callback Handling: After authentication, the user is redirected back to your app's callback URL with an authorization code. The library handles exchanging this code for access tokens.

3. Token Storage: Tokens are stored securely using Zustand's persist middleware, which saves to localStorage.

4. User Info: After successful token exchange, user information is automatically fetched from the userinfo endpoint.

5. Session Management: The library maintains session state and can pass session IDs to subsequent authentication requests.

6. Logout: Logout clears all tokens and session data, and optionally calls the backend logout endpoint.

License

Apache 2.0