@arascorp/auth
v1.3.0
Published
Reusable OAuth0/2/OIDC utility with inactivity timeout, built on oidc-client-ts, for React and Web Components.
Readme
@arascorp/auth
A modern authentication library for React applications, built on oidc-client-ts with enhanced features for seamless OAuth2/OIDC integration.
Features
- 🔐 OAuth2/OIDC Authentication - Built on oidc-client-ts v2.1.1
- ⚛️ React Integration - Hooks, context, and HOC patterns
- 🛡️ Protected Routes - Automatic authentication and return URL handling
- ⏱️ Inactivity Timeout - Configurable automatic logout
- 🔄 Auto Callback Handling - Automatic OAuth callback processing
- 🧪 TypeScript Support - Full TypeScript definitions
- 🌐 Environment Helper - Cross-bundler environment variable support
Installation
npm install @arascorp/authPeer Dependencies:
react>=19.2.7react-dom>=19.2.7react-router^8.3.0
Upgrading from 1.x (the
react-router-domstack)? See MIGRATION.md — installing this version on an unmigrated project fails with an npmERESOLVEpeer conflict.
On 1.2.0 and tests fail with
Cannot find module '…/@arascorp/auth/dist/auth-service'? That release shipped ESM output without file extensions, which Vitest and plain Node reject. Upgrade to 1.3.0 or later. See Troubleshooting.
Using an AI assistant?
AI.md(ships with this package) is the machine-readable, single-source-of-truth API reference — point your agent atnode_modules/@arascorp/auth/AI.md.
Quick Start
1. Setup AuthProvider
In your main entry file (main.tsx):
import { StrictMode } from "react";
import { createRoot } from "react-dom/client";
import { BrowserRouter } from "react-router";
import { AuthProvider, createAuthConfigFromEnv } from "@arascorp/auth";
import App from "./App";
const authConfig = createAuthConfigFromEnv(import.meta.env); // Vite
// const authConfig = createAuthConfigFromEnv(); // Webpack / CRA
createRoot(document.getElementById("root")!).render(
<StrictMode>
<BrowserRouter>
<AuthProvider config={authConfig}>
<App />
</AuthProvider>
</BrowserRouter>
</StrictMode>
);⚠️ Important: AuthProvider must be inside BrowserRouter as it uses useNavigate().
2. Configure Environment Variables
The following values come from your CIAM application configuration:
# Vite (.env) — minimum required
VITE_ARAS_AUTH_CLIENT_ID=your-client-id # from CIAM config — required, unique per application
# Optional — defaults to https://iam.aras.cloud/auth/.
# Override only when targeting a non-production environment (e.g. staging/dev).
VITE_ARAS_AUTH_AUTHORITY=https://your-ciam-authority.com
# Optional (required for API access)
VITE_ARAS_AUTH_AUDIENCE=https://your-api.com
# Optional
VITE_ARAS_AUTH_TENANT=your-tenant-id # skips tenant selection at login for multi-tenant accountsAdditional optional variables (Vite):
VITE_ARAS_AUTH_REDIRECT_URI=http://localhost:3000/callback # default: origin + /callback
VITE_ARAS_AUTH_SCOPE=openid profile email # default: openid profile email
VITE_ARAS_AUTH_LOGOUT_AFTER_INACTIVITY_MS=900000 # default: 900000 (15 min), 0 to disable
VITE_ARAS_AUTH_POST_LOGOUT_REDIRECT_URI=http://localhost:3000 # default: origin
VITE_ARAS_AUTH_SILENT_REDIRECT_URI=http://localhost:3000/silent-renew # default: origin + /silent-renew
VITE_ARAS_AUTH_TOKEN_ENDPOINT=https://your-ciam-authority.com/oauth/token # default: discovered from authorityTo call a second API with getAccessToken(audience), scope must include
offline_access:
VITE_ARAS_AUTH_SCOPE=openid profile email offline_accessFor Webpack/CRA, use the REACT_APP_ARAS_AUTH_* prefix:
# Webpack/CRA (.env) — minimum required
# Optional — defaults to https://iam.aras.cloud/auth/.
REACT_APP_ARAS_AUTH_AUTHORITY=https://your-ciam-authority.com
REACT_APP_ARAS_AUTH_CLIENT_ID=your-client-id
# Optional (required for API access)
REACT_APP_ARAS_AUTH_AUDIENCE=https://your-api.com
# Optional
REACT_APP_ARAS_AUTH_TENANT=your-tenant-id # skips tenant selection at login for multi-tenant accounts
REACT_APP_ARAS_AUTH_TOKEN_ENDPOINT=https://your-ciam-authority.com/oauth/token # default: discovered from authority
REACT_APP_ARAS_AUTH_SCOPE=openid profile email offline_access # offline_access required for audience token exchangeOr configure manually:
const authConfig = {
authority: "https://your-oidc-provider.com",
client_id: "your-client-id",
redirect_uri: window.location.origin + "/callback",
scope: "openid profile email offline_access", // offline_access enables refresh tokens for silent token renewal
tenant: "your-tenant-id" // Optional: ARAS CIAM tenant
};3. Use Authentication
import { useAuth } from "@arascorp/auth";
function UserProfile() {
const { user, loading, isAuthenticated, signInRedirect, signOutRedirect } = useAuth();
if (loading) return <div>Loading...</div>;
return isAuthenticated ? (
<div>
<h2>Welcome, {user?.profile.name}!</h2>
<button onClick={signOutRedirect}>Sign Out</button>
</div>
) : (
<button onClick={signInRedirect}>Sign In</button>
);
}4. Protect Routes
import { Routes, Route } from "react-router";
import { ProtectedRoute } from "@arascorp/auth";
function AppRoutes() {
return (
<Routes>
<Route path="/" element={<HomePage />} />
<Route
path="/dashboard"
element={
<ProtectedRoute>
<Dashboard />
</ProtectedRoute>
}
/>
</Routes>
);
}Integration Examples
The following complete examples show how to integrate @arascorp/auth into an Edge App for the three most common scenarios.
Prerequisites
Before starting, ensure:
- Your CIAM application is created and configured.
- You have
client_idfrom the CIAM application configuration.
Add to your .env file:
VITE_ARAS_AUTH_CLIENT_ID=your-client-id # required — from CIAM config, unique per application
# The authority URL is pre-configured in the package for the default CIAM environment.
# Override only when targeting a non-production environment.
# VITE_ARAS_AUTH_AUTHORITY=https://your-ciam-authority.com
VITE_ARAS_AUTH_AUDIENCE=https://your-api.com # optional (required for API access)
VITE_ARAS_AUTH_TENANT=your-tenant-id # optional: skips tenant selection at login for multi-tenant accountsExample 1 — Public Application
Use case: the app is fully public, but login/logout functionality is available to users.
// main.tsx
import { StrictMode } from "react";
import { createRoot } from "react-dom/client";
import { BrowserRouter } from "react-router";
import { AuthProvider, createAuthConfigFromEnv, useAuth } from "@arascorp/auth";
const authConfig = createAuthConfigFromEnv(import.meta.env);
function App() {
const { user, isAuthenticated, signInRedirect, signOutRedirect } = useAuth();
return (
<div>
<h1>My App</h1>
{isAuthenticated ? (
<>
<p>Welcome, {user?.profile.name}!</p>
<button onClick={signOutRedirect}>Sign Out</button>
</>
) : (
<button onClick={signInRedirect}>Sign In</button>
)}
</div>
);
}
createRoot(document.getElementById("root")!).render(
<StrictMode>
<BrowserRouter>
<AuthProvider config={authConfig}>
<App />
</AuthProvider>
</BrowserRouter>
</StrictMode>
);Example 2 — Fully Protected Application
Use case: every page requires authentication. Unauthenticated users are automatically redirected to the CIAM login page.
// main.tsx
import { StrictMode } from "react";
import { createRoot } from "react-dom/client";
import { BrowserRouter } from "react-router";
import { AuthProvider, createAuthConfigFromEnv } from "@arascorp/auth";
import App from "./App";
const authConfig = createAuthConfigFromEnv(import.meta.env);
createRoot(document.getElementById("root")!).render(
<StrictMode>
<BrowserRouter>
<AuthProvider config={authConfig}>
<App />
</AuthProvider>
</BrowserRouter>
</StrictMode>
);// App.tsx
import { Routes, Route } from "react-router";
import { ProtectedRoute } from "@arascorp/auth";
import Dashboard from "./Dashboard";
export default function App() {
return (
<Routes>
<Route
path="/*"
element={
<ProtectedRoute>
<Dashboard />
</ProtectedRoute>
}
/>
</Routes>
);
}Example 3 — Partially Protected Application
Use case: the app has both public and protected routes. Only specific routes redirect unauthenticated users to login.
// main.tsx
import { StrictMode } from "react";
import { createRoot } from "react-dom/client";
import { BrowserRouter } from "react-router";
import { AuthProvider, createAuthConfigFromEnv } from "@arascorp/auth";
import App from "./App";
const authConfig = createAuthConfigFromEnv(import.meta.env);
createRoot(document.getElementById("root")!).render(
<StrictMode>
<BrowserRouter>
<AuthProvider config={authConfig}>
<App />
</AuthProvider>
</BrowserRouter>
</StrictMode>
);// App.tsx
import { Route, Routes } from "react-router";
import { ProtectedRoute } from "@arascorp/auth";
import HomePage from "./pages/HomePage";
import Dashboard from "./pages/Dashboard";
export default function App() {
return (
<Routes>
<Route path="/" element={<HomePage />} />
<Route
path="/dashboard"
element={
<ProtectedRoute>
<Dashboard />
</ProtectedRoute>
}
/>
</Routes>
);
}Common Patterns
Authenticated API Calls
Use user.access_token from useAuth() to authorize requests to your backend.
(For an API with a different CIAM audience, see
Calling a Second API below.)
import { useAuth } from "@arascorp/auth";
function Dashboard() {
const { user, isAuthenticated } = useAuth();
async function fetchData() {
if (!isAuthenticated) return;
const response = await fetch("https://api.example.com/data", {
headers: {
Authorization: `Bearer ${user!.access_token}`
}
});
return response.json();
}
return <button onClick={fetchData}>Load Data</button>;
}Calling a Second API (Audience Token Exchange)
When an app talks to two APIs with different CIAM audiences, use
getAccessToken(audience). It exchanges the refresh token for an
audience-scoped token, caches it per audience, and keeps the OIDC session in
sync when CIAM rotates the refresh token.
import { useAuth, isTokenExchangeError } from "@arascorp/auth";
function AgentPanel() {
const { getAccessToken, signInRedirect } = useAuth();
async function runAgent() {
try {
const token = await getAccessToken(import.meta.env.VITE_AGENTS_AUDIENCE);
const response = await fetch("https://agents.example.com/run", {
method: "POST",
headers: { Authorization: `Bearer ${token}` }
});
if (response.status === 401) {
// Bypass the cache once, in case the token was revoked early.
const fresh = await getAccessToken(import.meta.env.VITE_AGENTS_AUDIENCE, { forceRefresh: true });
return fetch("https://agents.example.com/run", {
method: "POST",
headers: { Authorization: `Bearer ${fresh}` }
});
}
return response;
} catch (err) {
if (isTokenExchangeError(err, "invalid_grant")) await signInRedirect();
else throw err;
}
}
return <button onClick={runAgent}>Run</button>;
}Requires offline_access in scope, the Refresh Token grant enabled on the
CIAM application, and the target API listed under Allowed APIs. Calling
getAccessToken() with no argument returns the session token without a network
request. See AI.md for the full prerequisite list, the error reasons, and the
automaticSilentRenew / userStore limitations.
Sign Out
import { useAuth } from "@arascorp/auth";
function LogoutButton() {
const { signOutRedirect } = useAuth();
return <button onClick={signOutRedirect}>Sign Out</button>;
}Production Error Handling
Use callbackErrorHandling="rich" for a styled error UI instead of the default plain text:
<AuthProvider config={authConfig} callbackErrorHandling="rich">
<App />
</AuthProvider>Configuration Options
interface AuthConfig {
authority: string; // OIDC provider URL (required)
client_id: string; // Client ID (required)
redirect_uri?: string; // Callback URL - can be any path (default: window.location.origin + "/callback")
post_logout_redirect_uri?: string; // Default: window.location.origin
scope?: string; // Default: "openid profile email"
response_type?: string; // Default: "code"
audience?: string; // API audience (Auth0, etc.)
tenant?: string; // ARAS CIAM tenant identifier
tokenEndpoint?: string; // Token endpoint for audience exchange (default: discovered from authority)
automaticSilentRenew?: boolean; // Default: false - see AI.md before enabling
logoutAfterInactivityMs?: number; // Default: 900000 (15 min), 0 to disable
}
automaticSilentRenewdefaults tofalse. oidc-client-ts defaults it totrue, but that rotates the refresh token on a timer outside the token exchange queue and causes intermittentinvalid_grant. Tokens still renew automatically — the library drives renewal itself. Enabling it manually is not safe alongsidegetAccessToken(audience).
Callback Route: The library automatically detects your OAuth callback route from redirect_uri. You can use any path - not just /callback. Examples:
redirect_uri: "https://myapp.com/callback"→ handles callbacks on/callbackredirect_uri: "https://myapp.com/auth/return"→ handles callbacks on/auth/returnredirect_uri: "https://myapp.com/oauth/complete"→ handles callbacks on/oauth/complete
Supported Providers
Works with any OIDC-compliant provider:
Auth0
const config = {
authority: "https://your-domain.auth0.com",
client_id: "your-client-id",
audience: "https://your-api.com" // Optional: for API access
};Azure AD B2C
const config = {
authority: "https://yourtenant.b2clogin.com/yourtenant.onmicrosoft.com/B2C_1_signin/v2.0",
client_id: "your-client-id"
};Okta
const config = {
authority: "https://your-org.okta.com/oauth2/default",
client_id: "your-client-id"
};Keycloak
const config = {
authority: "https://your-keycloak.com/auth/realms/your-realm",
client_id: "your-client-id"
};Advanced Patterns
Error Handling
The library provides comprehensive error handling for OAuth callback errors (e.g., access_denied, unauthorized_client, etc.) with built-in loop prevention.
Callback Error Handling Modes
The callbackErrorHandling prop on AuthProvider controls how OAuth callback errors are handled and displayed:
Available modes:
| Mode | UI Display | Use Case |
| --------------- | ------------------- | ------------------------------------------------- |
| "simple" | Plain text | Default - minimal unstyled error (⭐ default) |
| "silent" | None | Manual error handling via useAuth().error |
| "rich" | Styled with buttons | Production-ready error UI |
| "none" | None | ⚠️ Debugging only - disables loop prevention |
| Custom function | Your renderer | Full control over error display |
All modes except "none" prevent infinite redirect loops when all routes are protected.
Example - Simple mode (default):
<AuthProvider config={authConfig}>
<App />
</AuthProvider>
// Shows plain text error on callback route:
// "Authentication Failed
// Access denied. You don't have permission to access this application.
// [Try Again]"Example - Rich mode (recommended for production):
<AuthProvider config={authConfig} callbackErrorHandling="rich">
<App />
</AuthProvider>
// Shows styled error with branded UI and retry/dismiss buttonsExample - Silent mode (manual handling):
<AuthProvider config={authConfig} callbackErrorHandling="silent">
<App />
</AuthProvider>;
function App() {
const { error, clearError, signInRedirect } = useAuth();
return (
<div>
{error && (
<div className="error-banner">
<h3>{error.title}</h3>
<p>{error.message}</p>
{error.canRetry && <button onClick={signInRedirect}>Try Again</button>}
<button onClick={clearError}>Dismiss</button>
</div>
)}
<YourAppContent />
</div>
);
}Example - Custom function:
<AuthProvider
config={authConfig}
callbackErrorHandling={(error, clearError, signInRedirect) => (
<div className="my-custom-error">
<h2>🔒 {error.title}</h2>
<p>{error.message}</p>
{error.canRetry && <button onClick={signInRedirect}>Try Again</button>}
<button onClick={clearError}>Dismiss</button>
</div>
)}
>
<App />
</AuthProvider>Common OAuth errors handled:
access_denied- User denied access or lacks permission (no retry)unauthorized_client- Application not authorizedinvalid_request- Malformed authentication requestinvalid_scope- Invalid or unsupported scopeserver_error- Server-side error occurred (can retry)temporarily_unavailable- Service temporarily down (can retry)interaction_required- User interaction neededlogin_required- Re-authentication requiredconsent_required- User consent neededunsupported_response_type- Response type not supported
Error object structure:
interface AuthErrorInfo {
title: string; // User-friendly title
message: string; // Detailed error message
error: string; // OAuth error code (e.g., "access_denied")
canRetry: boolean; // Whether retry is appropriate
isUserAction?: boolean; // True if user explicitly denied access
}Testing error handling:
Navigate to the callback URL with error parameters:
http://localhost:3000/callback?error=access_denied&error_description=No%20access&state=testHow loop prevention works:
When an OAuth error occurs on the callback route:
AuthProviderdetects the error and displays it (based oncallbackErrorHandlingmode)- Children components (including
ProtectedRoute) are not rendered during error display - User can retry (triggers fresh sign-in) or reload the page (clears error state)
- This prevents infinite redirect loops even when all routes (including
/) are protected
Custom Loading States
import { useAuth } from "@arascorp/auth";
function MyComponent() {
const { user, loading, isAuthenticated, signInRedirect } = useAuth();
if (loading) {
return <CustomLoadingSpinner />;
}
if (!isAuthenticated) {
return (
<div>
<h2>Please Sign In</h2>
<button onClick={signInRedirect}>Sign In</button>
</div>
);
}
return <div>Welcome, {user?.profile.name}!</div>;
}Custom Fallback for ProtectedRoute
const AuthRequired = () => (
<div>
<h2>Authentication Required</h2>
<button onClick={() => signInRedirect()}>Sign In</button>
</div>
);
<ProtectedRoute fallbackComponent={AuthRequired}>
<ProtectedContent />
</ProtectedRoute>;HOC Pattern
import { withAuth, AuthComponentProps } from "@arascorp/auth";
function UserComponent({ user, isAuthenticated, signInRedirect }: AuthComponentProps) {
return isAuthenticated ? (
<div>Welcome, {user?.profile.name}!</div>
) : (
<button onClick={signInRedirect}>Sign In</button>
);
}
// Basic usage
const User = withAuth(UserComponent);
// With route protection
const ProtectedUser = withAuth(UserComponent, { requireAuth: true });
// With custom fallback
const CustomUser = withAuth(UserComponent, {
requireAuth: true,
fallbackComponent: () => <div>Loading...</div>
});Manual Callback Handling
By default, AuthProvider automatically handles OAuth callbacks on the route specified in redirect_uri.
Automatic mode (default):
<AuthProvider config={config} callbackErrorHandling="simple">
{/* Library automatically:
- Detects callback route from redirect_uri
- Processes OAuth response (code or error)
- Handles errors based on callbackErrorHandling
- Navigates to returnUrl or "/"
*/}
<YourApp />
</AuthProvider>Note: The library automatically detects your callback route from the redirect_uri configuration. You can use any path (not just /callback):
const config = {
authority: "https://your-provider.com",
client_id: "your-client-id",
redirect_uri: window.location.origin + "/auth/return" // Custom callback path
// ... other config
};
<AuthProvider config={config}>
{/* Auto-handles callback on /auth/return */}
<YourApp />
</AuthProvider>;Manual Control
For full control over callback processing, set autoHandleCallback={false}:
⚠️ Important: When autoHandleCallback={false}:
- You must create a callback route component
- You must manually call
authService.signinRedirectCallback() - You're responsible for storing/retrieving returnUrl
- You can optionally use library's error handling (see example below)
<AuthProvider config={config} autoHandleCallback={false}>
<Routes>
<Route path="/callback" element={<CallbackHandler />} />
{/* Your other routes */}
</Routes>
</AuthProvider>Manual callback handler with custom error handling:
// CallbackHandler.tsx - Custom error UI
import { useAuth, handleOAuthCallback } from "@arascorp/auth";
import { useEffect, useState } from "react";
import { useNavigate } from "react-router";
function CallbackHandler() {
const { authService } = useAuth();
const navigate = useNavigate();
const [error, setError] = useState<string | null>(null);
useEffect(() => {
handleOAuthCallback(authService, navigate, {
onError: (err) => setError(err.message)
});
}, [authService, navigate]);
if (error) {
return (
<div>
<h2>Authentication Error</h2>
<p>{error}</p>
<button onClick={() => navigate("/")}>Go Home</button>
</div>
);
}
return <div>Processing login...</div>;
}Manual callback handler using library's error UI (recommended):
// CallbackHandler.tsx - Reuse library's error display
import { useAuth, handleOAuthCallback } from "@arascorp/auth";
import { useEffect } from "react";
import { useNavigate } from "react-router";
function CallbackHandler() {
const { authService, setError } = useAuth();
const navigate = useNavigate();
useEffect(() => {
handleOAuthCallback(authService, navigate, { setError });
}, [authService, setError, navigate]);
// Error automatically displayed by AuthProvider based on callbackErrorHandling
return <div>Processing login...</div>;
}Simplest manual callback:
// CallbackHandler.tsx - Minimal implementation
import { useAuth, handleOAuthCallback } from "@arascorp/auth";
import { useEffect } from "react";
import { useNavigate } from "react-router";
function CallbackHandler() {
const { authService } = useAuth();
const navigate = useNavigate();
useEffect(() => {
handleOAuthCallback(authService, navigate).catch(console.error);
}, [authService, navigate]);
return <div>Processing login...</div>;
}Why use manual mode?
- Custom error UI/logic beyond built-in
callbackErrorHandling - Integration with existing error handling systems
- Analytics/logging on callback success/failure
- Custom navigation logic (e.g., based on user roles)
- Non-standard OAuth flows
React Strict Mode
The library is fully compatible with React Strict Mode. OAuth callbacks are processed only once, even with double-mounting, using sessionStorage-based state management.
TypeScript
Full TypeScript support with type definitions:
import { User } from "oidc-client-ts";
import { AuthConfig, AuthContextType, AuthComponentProps } from "@arascorp/auth";
// Typed hook usage
const { user, loading, isAuthenticated }: AuthContextType = useAuth();
// Typed HOC props
interface MyProps extends AuthComponentProps {
customProp: string;
}API Reference
useAuth()
Hook that provides authentication state and methods:
const {
user, // User | null - Current user object
loading, // boolean - Loading state
isAuthenticated, // boolean - Authentication status
error, // AuthErrorInfo | null - OAuth callback error
signInRedirect, // () => Promise<void> - Initiate sign-in
signOutRedirect, // () => Promise<void> - Sign out user
clearError, // () => void - Clear current error
setError, // (error: AuthErrorInfo | null) => void - Set error (for manual mode)
getAccessToken, // (audience?, { forceRefresh? }) => Promise<string> - Session or audience-scoped token
authService // AuthService - Direct service access
} = useAuth();<AuthProvider>
Main provider component:
<AuthProvider
config={authConfig} // Auth configuration (required)
callbackErrorHandling="simple" // Error display mode (default: "simple")
autoHandleCallback={true} // Auto-handle OAuth callbacks (default: true)
>
<App />
</AuthProvider>Props:
config(required) - Authentication configuration objectauthority(required) - OIDC provider URLclient_id(required) - Application client IDredirect_uri- Callback URL (default:window.location.origin + "/callback")scope- OAuth scopes (default:"openid profile email")logoutAfterInactivityMs- Auto-logout timeout in ms (default: 900000 = 15 min)audience- API audience (Auth0, etc.)tenant- Tenant ID (ARAS CIAM)
callbackErrorHandling- How to handle OAuth callback errors (default:"simple")"simple"- Show plain text error"silent"- No UI, access viauseAuth().error"rich"- Styled error with retry/dismiss buttons"none"- No error handling (⚠️ debugging only)- Custom function:
(error: AuthErrorInfo, clearError: () => void, signInRedirect: () => void) => React.ReactNode
autoHandleCallback- Automatically process OAuth callbacks (default:true)
<ProtectedRoute>
Component that requires authentication:
<ProtectedRoute fallbackComponent={CustomComponent}>
<YourProtectedContent />
</ProtectedRoute>withAuth()
HOC for injecting auth props:
withAuth(Component, {
requireAuth?: boolean, // Auto-redirect if not authenticated
fallbackComponent?: React.FC // Custom loading/fallback component
});createAuthConfigFromEnv()
Creates config from environment variables:
const config = createAuthConfigFromEnv({
// Optional overrides
scope: "openid profile email custom"
});Manual Callback Utilities
Helper functions for manual callback handling (when autoHandleCallback={false}):
import {
hasOAuthParams,
isOAuthCallback,
isCallbackRoute,
getCallbackPath,
saveReturnUrl,
getReturnUrl,
clearReturnUrl,
navigateToReturnUrl
} from "@arascorp/auth";
// Check if URL has OAuth params (code/error + state)
hasOAuthParams(location.search); // true/false
// Check if current page is OAuth callback
isOAuthCallback(); // true/false
// Check if pathname matches callback route
isCallbackRoute(location.pathname, config.redirect_uri);
// Extract callback path from redirect_uri
getCallbackPath("https://example.com/auth/callback"); // "/auth/callback"
// Save URL to return to after authentication
saveReturnUrl("/dashboard");
saveReturnUrl(); // Saves current location
// Get saved return URL and clear it from storage
const url = getReturnUrl(); // Returns saved URL or "/"
const url = getReturnUrl("/home"); // Custom fallback
// Clear saved return URL without retrieving it
clearReturnUrl();
// Navigate to saved return URL using React Router (recommended)
navigateToReturnUrl(navigate); // Navigates to saved URL or "/"
navigateToReturnUrl(navigate, { replace: true }); // With navigation options
// Complete callback handler - handles everything in one call
handleOAuthCallback(authService, navigate); // Throws on error
handleOAuthCallback(authService, navigate, { setError }); // Use library error display (recommended)
handleOAuthCallback(authService, navigate, {
onError: (err) => setCustomError(err.message), // Custom error handling
callbackRoute: "/auth/callback", // Stay here on error
navigationOptions: { replace: true } // Success navigation options
});Error Types
interface AuthErrorInfo {
title: string; // User-friendly error title
message: string; // Detailed error message
error: string; // OAuth error code
canRetry: boolean; // Whether user can retry
isUserAction?: boolean; // If user explicitly denied access
}Audience token exchange failures reject with an Error named
TokenExchangeError, carrying structured detail instead of authErrorInfo:
interface TokenExchangeErrorDetails {
reason: TokenExchangeErrorReason; // Branch on this
audience?: string;
status?: number; // HTTP status, when the request completed
oauthError?: string; // `error` from the OAuth error body
oauthErrorDescription?: string; // Truncated and credential-scrubbed
indeterminate?: boolean; // Unknown whether the refresh token rotated
requiresReauth?: boolean; // User must sign in again
}Use the isTokenExchangeError(err, reason?) guard to branch, and
getTokenExchangeErrorInfo(err) to convert one into an AuthErrorInfo for
setError(). See AI.md for the full table of reasons and their fixes.
Important Notes
autoHandleCallback and callbackErrorHandling
callbackErrorHandlingonly works whenautoHandleCallback={true}(default)- When
autoHandleCallback={false}, you must handle errors manually in your callback component - See Manual Callback Handling for complete examples
Browser Support
- Modern browsers with ES2018+ support
- React 17+, 18+, 19+
- React Router DOM v6+, v7+
Troubleshooting
"Oops! redirect_uri" or Invalid Redirect URI Error
This error occurs when the redirect_uri in your application config doesn't match the allowed callback URLs configured in your OIDC provider (CIAM, Auth0, etc.).
Common causes:
Exact mismatch - URIs must match exactly, including:
- Protocol (
http://vshttps://) - Domain/port (
localhost:3000vslocalhost:5173) - Path (
/callbackvs/auth/callback) - Trailing slashes (
/callbackvs/callback/)
- Protocol (
Case sensitivity - Some providers are case-sensitive (
/Callbackvs/callback)Missing configuration - Redirect URI not added to provider's allowed list
How to fix:
- Check your app configuration:
// Make sure redirect_uri exactly matches what's configured in CIAM
const authConfig = {
authority: "https://your-provider.com",
client_id: "your-client-id",
redirect_uri: "https://myapp.com/callback" // ← Must match EXACTLY
// ...
};Check your OIDC provider settings:
- ARAS CIAM: Go to your application settings → Allowed Callback URLs
- Auth0: Dashboard → Applications → Your App → Settings → Allowed Callback URLs
- Azure AD: App registrations → Authentication → Redirect URIs
- Okta: Applications → Your App → General Settings → Login redirect URIs
Verify exact match:
# Your app config:
redirect_uri: "https://myapp.com/callback"
# CIAM allowed URLs must include:
https://myapp.com/callback ✅ Correct
https://myapp.com/callback/ ❌ Wrong (trailing slash)
https://myapp.com/auth ❌ Wrong (different path)
http://myapp.com/callback ❌ Wrong (http vs https)- For local development, add both:
http://localhost:3000/callback
http://localhost:5173/callback (if using Vite)- Common pitfall - Environment variables:
# Make sure your .env matches production config
VITE_ARAS_AUTH_REDIRECT_URI=https://myapp.com/callback
# Not:
VITE_ARAS_AUTH_REDIRECT_URI=https://myapp.com/callback/ ❌Testing locally:
- Use exact domain from environment variables
- Check browser console for the actual redirect_uri being used
- Verify provider's configuration includes your local URL
Vitest or Node: Cannot find module '…/@arascorp/auth/dist/auth-service'
Error: Cannot find module '…/node_modules/@arascorp/auth/dist/auth-service'
imported from …/node_modules/@arascorp/auth/dist/index.jsAffects: exactly version 1.2.0, when the package is loaded by Node's ESM resolver — Vitest with the default configuration, server-side rendering, or scripts. vite build and the dev server are not affected because bundlers probe file extensions.
Cause: 1.2.0 moved the published dist/ from CommonJS to ESM (required by react-router@8, which is ESM-only) but its internal relative imports lacked the .js extension. Node's ESM loader does not infer extensions.
Fix: upgrade to 1.3.0 or later, where every internal import names its file and the build verifies the output loads under Node before publishing.
npm install @arascorp/auth@latestIf you cannot upgrade yet, let Vite transform the package instead of Node loading it:
// vitest.config.ts
export default defineConfig({
test: {
server: { deps: { inline: ["@arascorp/auth"] } }
}
});Or stay on 1.1.0, which is CommonJS and unaffected (note it peers on react-router-dom, see MIGRATION.md).
License
MIT
Support
For issues and questions visit our community portal
