The official Haaremy SSO Authentication SDK provides a comprehensive solution for integrating Haaremy's Single Sign-On system into JavaScript applications. It encapsulates token handling, login/logout flows, BroadcastChannel-based tab synchronization, and offers specific integrations for React and Next.js. Currently at version 2.0.0, this SDK is actively maintained with a focus on security and developer experience. Key differentiators include its 'zero localStorage' approach (tokens are memory-only), proactive token refresh, server-side replay detection for token families, and efficient offline JWT validation using JWKS caching with Ed25519 signatures. It offers distinct entrypoints for vanilla JS/framework-agnostic core logic, React hooks and components, and Next.js middleware/server-side helpers, making it adaptable to various application architectures.
npm install haaremy-authVerified import paths — ran on the pinned version, not inferred.
This quickstart demonstrates how to set up the `HmyAuthProvider` at your application root and use the `useAuth` hook in a child component to manage authentication state, display user information, handle login via `HmyLoginForm`, and perform logout. It showcases both authenticated and unauthenticated states.
Review all import statements. For React components/hooks, change `import { X } from '@haaremy/auth'` to `import { X } from '@haaremy/auth/react'`. For Next.js middleware, ensure `import { createHmyMiddleware } from '@haaremy/auth/next'` is used.Design your application's user experience with this in mind. Ensure your login flow can gracefully handle token expiry or loss on browser close. Leverage the refresh token mechanism for persistent sessions via SSO cookies.
Carefully define `publicPaths` in your `createHmyMiddleware` configuration. Include `/login`, `/register`, API routes that should be public (e.g., `/api/public*`), and any static assets or `_next` paths as needed. Ensure `loginPath` points to your actual login route.
Always call and `await init()` at your application's startup. When using `authFetch`, ensure the authentication state indicates `authenticated` to prevent unauthorized requests. Consider wrapping `authFetch` calls in conditional logic based on the `state` from `useAuth` or `subscribe`.
Verify that your SSO provider is configured to use Ed25519 for JWT signatures. Ensure the `jwks.json` endpoint is publicly accessible and contains the correct public keys matching the SSO's private key.
Change `import { HmyAuthProvider } from '@haaremy/auth'` to `import { HmyAuthProvider } from '@haaremy/auth/react'` (and similarly for other React components/hooks).Ensure you are importing `createHmyMiddleware` from the correct subpath: `import { createHmyMiddleware } from '@haaremy/auth/next'`.Add `import { init } from '@haaremy/auth'` to the top of your file. If using CommonJS, consider migrating to ESM or ensuring your build process correctly transpiles.Before making requests with `authFetch`, ensure your application has completed initialization (`await init()`) and the user state is `authenticated`. You can use `subscribe` or `useAuth` to monitor the authentication state.