@armco/iam-client

Browser/SPA client for IAM - OIDC/OAuth2 authentication with PKCE.

Installation

npm install @armco/iam-client

Quick Start

Vanilla JavaScript/TypeScript

import { createIAMClient } from '@armco/iam-client';

const iam = createIAMClient({
  issuer: 'http://localhost:5000',
  clientId: 'my-app',
  redirectUri: 'http://localhost:3000/callback',
  scopes: ['openid', 'profile', 'email', 'offline_access'],
});

// Login
document.getElementById('login-btn').onclick = () => iam.login();

// Signup
document.getElementById('signup-btn').onclick = () => iam.signup();

// Handle callback (on /callback page)
const result = await iam.handleCallback();
if (result.success) {
  console.log('Logged in:', result.user);
} else {
  console.error('Login failed:', result.error);
}

// Get current user
const user = iam.getUser();

// Get access token (auto-refreshes if needed)
const token = await iam.getAccessToken();

// Logout
await iam.logout();

React

import { IAMProvider, useAuth } from '@armco/iam-client/react';

// Wrap your app
function App() {
  return (
    <IAMProvider
      issuer="http://localhost:5000"
      clientId="my-app"
      redirectUri="http://localhost:3000/callback"
      onLoginSuccess={(result) => {
        console.log('Logged in:', result.user);
        // Navigate to dashboard
      }}
    >
      <Router>
        <Routes>
          <Route path="/" element={<Home />} />
          <Route path="/callback" element={<Callback />} />
          <Route path="/dashboard" element={<Dashboard />} />
        </Routes>
      </Router>
    </StuffleIAMProvider>
  );
}

// Use the hook
function Home() {
  const { isAuthenticated, isLoading, user, login, signup, logout } = useAuth();

  if (isLoading) return <div>Loading...</div>;

  if (!isAuthenticated) {
    return (
      <div>
        <button onClick={() => login()}>Login</button>
        <button onClick={() => signup()}>Sign Up</button>
      </div>
    );
  }

  return (
    <div>
      <p>Welcome, {user?.name || user?.email}</p>
      <button onClick={() => logout()}>Logout</button>
    </div>
  );
}

// Callback page (auto-handled by provider)
function Callback() {
  const { isLoading, error } = useAuth();
  
  if (isLoading) return <div>Processing login...</div>;
  if (error) return <div>Error: {error.message}</div>;
  
  return <Navigate to="/dashboard" />;
}

Configuration

interface StuffleIAMConfig {
  /** IAM server base URL */
  issuer: string;
  /** OAuth2 client ID */
  clientId: string;
  /** Redirect URI after login */
  redirectUri: string;
  /** Requested scopes (default: openid profile email) */
  scopes?: string[];
  /** Post-logout redirect URI */
  postLogoutRedirectUri?: string;
  /** Enable PKCE (default: true) */
  usePkce?: boolean;
  /** Storage type (default: sessionStorage) */
  storage?: 'localStorage' | 'sessionStorage' | 'memory';
  /** Auto-refresh tokens (default: true) */
  autoRefresh?: boolean;
  /** Seconds before expiry to refresh (default: 60) */
  refreshThreshold?: number;
}

React Hooks

| Hook | Description | |------|-------------| | useAuth() | Full auth context (user, login, logout, etc.) | | useUser() | Current user object | | useIsAuthenticated() | Boolean auth status | | useAccessToken() | Function to get access token | | useHasRole(roles) | Check if user has role(s) |

Protected Routes (HOC)

import { withAuth } from '@armco/iam-client/react';

const ProtectedPage = withAuth(MyComponent, {
  LoadingComponent: () => <div>Loading...</div>,
  UnauthorizedComponent: () => <div>Please login</div>,
  roles: ['admin'], // Optional: require specific roles
});

API Reference

StuffleIAMClient Methods

| Method | Description | |--------|-------------| | login(options?) | Start login flow | | signup(options?) | Start signup flow | | logout(options?) | End session | | handleCallback(url?) | Process OAuth callback | | getUser() | Get current user from ID token | | getAccessToken() | Get access token (refreshes if needed) | | isAuthenticated() | Check if user is logged in | | refreshToken() | Manually refresh tokens | | subscribe(listener) | Subscribe to auth state changes |

Development

cd packages/sdk-js
npm install
npm run build
npm run dev  # Watch mode