@Dream.mf Dev Portal

DMF OIDC Package

The @dream.mf/oidc package provides OpenID Connect (OIDC) authentication integration for Dream Packages applications, with React components and hooks for easy implementation.

Installation

npm install @dream.mf/oidc
# or
yarn add @dream.mf/oidc

Core Components

Authentication Provider

DreamMFAuthProvider

The main authentication provider component that wraps your application and manages the OIDC authentication state.

Props
interface DreamMFAuthProviderProps {
  children?: ReactNode;
  automaticSilentRenew?: boolean;
  config: DreamMFAuthConfig;
}

interface DreamMFAuthConfig {
  authority: string;           // OIDC authority URL
  client_id: string;          // Your client ID
  redirect_uri: string;       // Callback URL after login
  scope: string;              // OIDC scopes (e.g., 'openid profile email')
  useFetchInterceptor: boolean; // Enable automatic token injection in fetch calls
  useAxiosInterceptor: boolean; // Enable automatic token injection in axios calls
}
Example
import { DreamMFAuthProvider } from '@dream.mf/oidc';

const config = {
  authority: 'https://auth.example.com',
  client_id: 'your-client-id',
  redirect_uri: 'http://localhost:3000/callback',
  scope: 'openid profile email',
  useFetchInterceptor: true,
  useAxiosInterceptor: false
};

function App() {
  return (
    <DreamMFAuthProvider
      config={config}
      automaticSilentRenew={true}
    >
      <YourApp />
    </DreamMFAuthProvider>
  );
}

Protected Routes

DreamMFAuthGuard

A component that protects routes requiring authentication. It automatically handles redirects to login when needed and manages user profile registration.

Props
interface DreamMFAuthGuardProps {
  children?: ReactNode;
  fallback?: ReactNode;       // Component to show while checking auth status
  stopRedirect?: boolean;     // Prevent automatic redirect to login
}
Example
import { DreamMFAuthGuard } from '@dream.mf/oidc';

function ProtectedPage() {
  return (
    <DreamMFAuthGuard
      fallback={<LoadingSpinner />}
    >
      <YourProtectedComponent />
    </DreamMFAuthGuard>
  );
}

Authentication Hook

useDreamAuth

A custom hook that extends the base OIDC authentication hook with additional functionality for managing auth state and storage.

Interface
interface useDreamAuthApi {
  // Inherited from react-oidc-context
  isAuthenticated: boolean;
  user: OidcUser;
  isLoading: boolean;
  signIn: () => Promise<void>;
  signOut: () => Promise<void>;
  
  // Extended functionality
  handleLogout: (onLogout: Function, clearState: boolean) => Promise<void>;
  clearOidcState: () => void;
  clearLocalStorage: () => void;
  clearSessionStorage: () => void;
}
Example
import { useDreamAuth } from '@dream.mf/oidc';

function AuthenticatedComponent() {
  const auth = useDreamAuth();
  
  const handleLogout = async () => {
    await auth.handleLogout(
      () => {
        console.log('Logged out successfully');
      },
      true // clear auth state after logout
    );
  };
  
  if (auth.isLoading) {
    return <div>Loading...</div>;
  }
  
  if (!auth.isAuthenticated) {
    return <div>Please log in</div>;
  }
  
  return (
    <div>
      <p>Welcome, {auth.user?.profile.name}</p>
      <button onClick={handleLogout}>Logout</button>
    </div>
  );
}

Fetch Interceptor

The package includes automatic token injection for fetch requests when useFetchInterceptor is enabled in the config.

Usage

// Add authentication to specific fetch requests
fetch('https://api.example.com/data', { 
  useAuthentication: true // This will automatically add the bearer token
});

URL Store

The package includes a URL store to manage redirect paths during the authentication flow.

import { DreamMFContextStore } from '@dream.mf/oidc';

// Save the current path before redirect
DreamMFContextStore.originalRequestPath(window.location.pathname);

// Get the saved path after login
const returnPath = DreamMFContextStore.originalRequestPath();

// Clear stored paths
DreamMFContextStore.clear();

Runtime Integration

The package integrates with the Dream.MF runtime to manage user profiles and authentication state:

import { setupRuntime } from '@dream.mf/oidc';

setupRuntime({
  useFetchInterceptor: true,
  useAxiosInterceptor: false
});

Types

DreamMFAuthConfig

interface DreamMFAuthConfig {
  authority: string;
  client_id: string;
  redirect_uri: string;
  scope: string;
  useFetchInterceptor: boolean;
  useAxiosInterceptor: boolean;
  post_logout_redirect_uri: string;
  response_type: string;
  metadataUrl: string;
  userStore: WebStorageStateStore;
}

DreamMFAuthGuardProps

interface DreamMFAuthGuardProps {
  children?: ReactNode;
  fallback?: ReactNode;
  stopRedirect?: boolean;
}

Storage Management

The package includes utilities for managing OIDC-related storage:

const auth = useDreamAuth();

// Clear specific storage
auth.clearLocalStorage();
auth.clearSessionStorage();
auth.clearOidcState();

// Handle logout with cleanup
await auth.handleLogout(
  () => console.log('Logged out'),
  true // clear state
);

Example Usage

import { 
  DreamMFAuthProvider, 
  DreamMFAuthGuard, 
  useDreamAuth 
} from '@dream.mf/oidc';

function App() {
  return (
    <DreamMFAuthProvider
      config={{
        authority: 'https://auth.example.com',
        client_id: 'client-id',
        redirect_uri: 'http://localhost:3000/callback',
        scope: 'openid profile email',
        useFetchInterceptor: true
      }}
    >
      <Router>
        <Route
          path="/protected"
          element={
            <DreamMFAuthGuard>
              <ProtectedComponent />
            </DreamMFAuthGuard>
          }
        />
      </Router>
    </DreamMFAuthProvider>
  );
}