@identigo/browser
v0.3.0
Published
Identigo SDK for browser apps: OIDC with PAR, PKCE and DPoP (non-extractable keys), in-memory tokens, plus Angular, React, Vue and axios integrations.
Maintainers
Readme
@identigo/browser
Sign users in to your single-page app with Identigo in a few lines, using the most secure way a browser app can hold a session today.
// Angular
providers: [
provideIdentigo({ issuer, clientId, apiUrls: ["https://api.example.com"] }),
provideHttpClient(withInterceptors([identigoInterceptor])),
];// React
<IdentigoProvider client={identigo}>
<App />
</IdentigoProvider>;
const { user, login, logout } = useIdentigo();That's the whole integration. Your HttpClient, axios or fetch calls to your API carry the user's
token automatically, and the rest of this page is detail.
Contents
- Why it's secure
- Install
- Register your app
- Quick start: Angular · React · Next.js · Vue · axios · Svelte · Plain JavaScript
- Calling your APIs
- Step-up: a passkey before sensitive actions
- Configuration
- API reference
- Local development
- Upgrading from 0.1
Why it's secure
You get all of this without configuring any of it:
| Protection | What it means for you |
| ---------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Sender-constrained tokens (DPoP, RFC 9449) | Every API request carries a fresh signature from a key that lives only in this browser. A token stolen from a log, a proxy or memory is useless anywhere else. |
| A key nobody can copy | That key is created as a non-extractable WebCrypto key. Even script running on your page can use it but can never read it out. |
| Tokens in memory only | Access tokens never touch localStorage, sessionStorage or cookies. The refresh token that is kept is bound to the key above and rotates on every use. |
| Tokens only go to your APIs | The interceptors and fetch() attach tokens only to the apiUrls you list. Requests to anything else — a CDN, an analytics endpoint — never see them. |
| No secrets in the URL (PAR + PKCE) | Sign-in requests are pushed to Identigo server-to-server first; the address bar only ever shows a one-time reference. PKCE protects the code that comes back. |
| Forgery and mix-up checks | state, nonce and the issuer (RFC 9207) are verified on every sign-in. |
| Stronger sign-in on demand (RFC 9470) | When your API needs a passkey or a recent sign-in, the SDK handles it — see Step-up. |
This is the FAPI 2.0 security profile adapted to a browser app. Identigo's server enforces the same rules, so a misconfigured client fails closed rather than quietly downgrading.
Install
npm install @identigo/browserOne package for every framework: import from @identigo/browser/angular, /react, /vue or
/axios, or from @identigo/browser itself for anything else. You only bundle what you import.
Needs a current browser (WebCrypto and IndexedDB).
Using an AI coding agent?
The package ships an Agent Skill at
node_modules/@identigo/browser/skills/identigo-browser/ with the setup steps, a reference per
framework and the security rules agents must follow. Point your agent at its SKILL.md, or copy the
folder into your agent's skills directory (for Claude Code, .claude/skills/).
Register your app
In the Identigo console, create an app of type Single-page app with:
| Setting | Value |
| ------------------------- | ---------------------------------- |
| Redirect URIs | https://app.example.com/callback |
| Post-logout redirect URIs | https://app.example.com/ |
| Allowed origins | https://app.example.com |
Copy its client ID (app_…). Those are the SDK's defaults (/callback and /), so you don't
have to configure them, and you don't need to build a /callback page either.
Your API verifies the tokens with @identigo/node.
Angular
1. Configure — app.config.ts:
import { provideHttpClient, withInterceptors } from "@angular/common/http";
import { provideRouter } from "@angular/router";
import { identigoInterceptor, provideIdentigo } from "@identigo/browser/angular";
export const appConfig: ApplicationConfig = {
providers: [
provideIdentigo({
issuer: "https://auth.example.com/oidc",
clientId: "app_1a2b3c4d5e6f7g8h",
apiUrls: ["https://api.example.com"],
}),
provideHttpClient(withInterceptors([identigoInterceptor])),
provideRouter(routes),
],
};2. Protect routes — app.routes.ts:
import { signedIn } from "@identigo/browser/angular";
export const routes: Routes = [
{ path: "", component: HomeComponent },
{ path: "projects", component: ProjectsComponent, canActivate: [signedIn()] },
{ path: "admin", component: AdminComponent, canActivate: [signedIn({ role: "admin" })] },
];3. Use it — the user is a signal; HttpClient needs nothing extra:
import { injectIdentigo } from "@identigo/browser/angular";
@Component({ selector: "app-header", templateUrl: "./header.component.html" })
export class HeaderComponent {
protected readonly auth = injectIdentigo();
}@if (auth.user(); as user) {
<span>{{ user.name }}</span>
@if (auth.hasRole("admin")) { <a routerLink="/admin">Admin</a> }
<button (click)="auth.logout()">Sign out</button>
} @else {
<button (click)="auth.login()">Sign in</button>
}export class ProjectsComponent {
private readonly http = inject(HttpClient);
protected readonly projects = httpResource<Project[]>(() => "https://api.example.com/projects");
remove(id: string) {
return this.http.delete(`https://api.example.com/projects/${id}`);
}
}provideIdentigo() finishes sign-in before the router starts, so the user lands back on the page
they came from.
React
Works with Vite, React Router and TanStack Router. For Next.js see below.
1. Create the client — src/identigo.ts:
import { IdentigoClient } from "@identigo/browser/react";
export const identigo = new IdentigoClient({
issuer: "https://auth.example.com/oidc",
clientId: "app_1a2b3c4d5e6f7g8h",
apiUrls: ["https://api.example.com"],
});2. Wrap your app — src/main.tsx:
import { IdentigoProvider } from "@identigo/browser/react";
import { identigo } from "./identigo";
createRoot(document.getElementById("root")!).render(
<IdentigoProvider client={identigo} fallback={<Spinner />}>
<App />
</IdentigoProvider>,
);3. Use it:
import { Protect, SignedIn, SignedOut, useIdentigo } from "@identigo/browser/react";
function Header() {
const { user, login, logout } = useIdentigo();
return (
<header>
<SignedIn>
Hello {user?.name} <button onClick={() => logout()}>Sign out</button>
</SignedIn>
<SignedOut>
<button onClick={() => login()}>Sign in</button>
</SignedOut>
</header>
);
}
// Signed-out users are sent to sign in, then come back here.
<Route
path="/admin"
element={
<Protect role="admin" fallback={<p>Admins only.</p>}>
<Admin />
</Protect>
}
/>;Calling your API — with fetch, or axios via attachIdentigo:
const { fetch } = useIdentigo();
const { data } = useQuery({
queryKey: ["projects"],
queryFn: () => fetch("https://api.example.com/projects").then((res) => res.json()),
});Next.js
The same React integration. The provider is a client component; pass blocking={false} so pages
rendered on the server stay visible, and let Next's router do the post-sign-in redirect:
// app/providers.tsx
"use client";
import { useRouter } from "next/navigation";
import { IdentigoClient, IdentigoProvider } from "@identigo/browser/react";
export const identigo = new IdentigoClient({
issuer: process.env.NEXT_PUBLIC_IDENTIGO_ISSUER!,
clientId: process.env.NEXT_PUBLIC_IDENTIGO_CLIENT_ID!,
apiUrls: [process.env.NEXT_PUBLIC_API_URL!],
});
export function Providers({ children }: { children: React.ReactNode }) {
const router = useRouter();
return (
<IdentigoProvider client={identigo} blocking={false} onRedirect={(path) => router.replace(path)}>
{children}
</IdentigoProvider>
);
}// app/layout.tsx — wrap {children} in <Providers>
// app/callback/page.tsx — Next needs the route to exist; it only shows while sign-in finishes
export default function Callback() {
return <p>Signing you in…</p>;
}Use useIdentigo(), <SignedIn> and <Protect> in client components. Tokens live in the browser,
so server components can't see the user. If you need signed-in pages rendered on the server, use a
backend-for-frontend instead (see Security notes).
Vue
// src/main.ts
import { createApp } from "vue";
import { createIdentigo, identigoGuard } from "@identigo/browser/vue";
export const identigo = createIdentigo({
issuer: "https://auth.example.com/oidc",
clientId: "app_1a2b3c4d5e6f7g8h",
apiUrls: ["https://api.example.com"],
});
router.beforeEach(identigoGuard(identigo));
createApp(App).use(identigo).use(router).mount("#app");// src/router.ts — mark the routes that need a signed-in user
const routes = [
{ path: "/", component: Home },
{ path: "/projects", component: Projects, meta: { auth: true } },
{ path: "/admin", component: Admin, meta: { auth: { role: "admin" } } },
];<script setup lang="ts">
import { useIdentigo } from "@identigo/browser/vue";
const { user, isSignedIn, login, logout } = useIdentigo();
</script>
<template>
<span v-if="isSignedIn"> {{ user?.name }} <button @click="logout()">Sign out</button> </span>
<button v-else @click="login()">Sign in</button>
</template>The guard finishes sign-in on the first navigation and takes the user back to the page they came from.
axios
import axios from "axios";
import { attachIdentigo } from "@identigo/browser/axios";
import { identigo } from "./identigo"; // your IdentigoClient
export const api = axios.create({ baseURL: "https://api.example.com" });
attachIdentigo(api, identigo);
await api.get("/projects"); // signed automaticallyWorks the same with React, Vue, Svelte or no framework at all.
Svelte
// src/lib/identigo.svelte.ts
import { IdentigoClient } from "@identigo/browser";
export const identigo = new IdentigoClient({
issuer: "https://auth.example.com/oidc",
clientId: "app_1a2b3c4d5e6f7g8h",
apiUrls: ["https://api.example.com"],
});
export const auth = $state({ user: identigo.user });
identigo.onChange((user) => (auth.user = user));// src/routes/+layout.ts (SvelteKit — the SDK runs in the browser only)
import { redirect } from "@sveltejs/kit";
import { identigo } from "$lib/identigo.svelte";
export const ssr = false;
export async function load() {
const returnTo = await identigo.ready().catch(() => undefined);
if (returnTo) redirect(307, returnTo);
}<script lang="ts">
import { auth, identigo } from "$lib/identigo.svelte";
</script>
{#if auth.user}
{auth.user.name} <button onclick={() => identigo.logout()}>Sign out</button>
{:else}
<button onclick={() => identigo.login()}>Sign in</button>
{/if}Plain JavaScript
import { IdentigoClient } from "@identigo/browser";
const identigo = new IdentigoClient({
issuer: "https://auth.example.com/oidc",
clientId: "app_1a2b3c4d5e6f7g8h",
apiUrls: ["https://api.example.com"],
});
const returnTo = await identigo.ready(); // finishes sign-in, or restores the session
if (returnTo) history.replaceState(null, "", returnTo);
identigo.onChange((user) => render(user));
render(identigo.user);
loginButton.onclick = () => identigo.login();
logoutButton.onclick = () => identigo.logout();
const res = await identigo.fetch("https://api.example.com/projects");Calling your APIs
List every API that should receive the user's token in apiUrls — an origin
(https://api.example.com) or a path on one (https://example.com/api). Leave it out and only your
app's own origin is allowed.
- Interceptors (Angular, axios) sign matching requests and leave everything else alone.
identigo.fetch()signs the request, or throws if the URL isn't inapiUrls, so a typo can't leak a token.- Any other HTTP client:
await identigo.getAuthHeaders(method, url)returns{ Authorization, DPoP }for that one request (ornull), andidentigo.handleApiResponse(url, response)afterwards handles nonce retries and step-up.
Each request gets its own signature, bound to its method and URL, so don't cache the headers.
CORS. If your API is on another origin, it must allow the Authorization and DPoP request
headers and expose WWW-Authenticate and DPoP-Nonce. See
@identigo/node.
Step-up: a passkey before sensitive actions
Some actions deserve more proof than "signed in at some point", such as paying out money, deleting an account or changing an email address. Your API declares what it needs:
// your API, with @identigo/node
app.post("/payouts", requireStepUp({ level: "passkey" }), handler); // signed in with a passkey
app.delete("/account", requireStepUp({ maxAge: 300 }), handler); // signed in within 5 minutes| Level | Means |
| ----------- | ------------------------------------------------------------------- |
| "mfa" | Signed in with two factors, such as a password and a one-time code. |
| "passkey" | Signed in with a passkey or security key, which can't be phished. |
| maxAge: N | Signed in (or confirmed it's them) within the last N seconds. |
In the browser you write nothing. When a request falls short, the SDK sends the user to Identigo to confirm, for example with their passkey, then brings them back to the same page with a stronger session. They click the button again and it works.
To explain first, for example in a "Confirm it's you" dialog, handle it yourself:
provideIdentigo({
// …
onStepUp: (request) => inject(Dialog).open(ConfirmItsYou, { data: request }),
});
// in the dialog: <button (click)="data.continue()">Continue</button>request.level ("mfa" / "passkey"), request.maxAge and request.reason say what the API
asked for; request.continue() goes to Identigo. In React and Vue, pass onStepUp to
new IdentigoClient({...}). The Angular integration runs it in an injection context, so inject()
works there.
You can also ask up front, before calling the API: login({ level: "passkey" }) or
stepUp({ maxAge: 0 }) for a fresh sign-in. Route guards take a level too:
signedIn({ level: "passkey" }) in Angular, <Protect level="passkey"> in React,
meta: { auth: { level: "passkey" } } in Vue.
Configuration
new IdentigoClient(config), provideIdentigo(config) and createIdentigo(config) all take:
| Option | Default | Description |
| ----------------------- | ------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| issuer | — | Your Identigo issuer, e.g. https://auth.example.com/oidc. |
| clientId | — | Your app's client ID. |
| apiUrls | your app's origin | Where the user's token may be sent. Origins or URL prefixes. |
| redirectUri | <origin>/callback | Must match the registered redirect URI exactly. |
| postLogoutRedirectUri | <origin>/ | Where Identigo sends the user after signing out. Must be registered. |
| onStepUp | redirect to Identigo | Called when an API asks for a stronger or more recent sign-in. See Step-up. |
| scope | openid profile email roles offline_access | OIDC scopes. |
| persist | true | Keep the user signed in across reloads. false keeps everything in memory. |
| store | IndexedDB | Custom KeyValueStore; memoryStore() is exported. |
| resource | your app's API audience | Leave unset; Identigo only issues tokens for your app's own API. |
| allowInsecure | false | Allow an http:// issuer. Local development only. |
API reference
IdentigoClient (from any entry point)
| Member | Description |
| ----------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| ready() / init() | Finishes sign-in or restores the session. Runs once per page load; resolves with the path to return to after sign-in. |
| user | { sub, email?, emailVerified?, name?, picture?, roles, acr?, amr } or null. Same object until sign-in changes. |
| isSignedIn | Whether someone is signed in. |
| onChange(listener) | Called with the user (or null) on sign-in, refresh and sign-out. Returns an unsubscribe function. |
| login(options?) | Redirects to Identigo. Options: returnTo, level, loginHint, prompt, maxAge, acrValues. |
| logout() | Revokes the session, forgets the key and redirects to Identigo's sign-out. |
| stepUp(options?) | Sign in again at level and/or within maxAge seconds, then return to this page. |
| hasRole(role) / hasLevel(level) | UI hints. Your API enforces roles and levels itself. |
| fetch(url, init?) | fetch() for your apiUrls, with token, proof, nonce retry and step-up handling. |
| getAuthHeaders(method, url) | { Authorization, DPoP } for one request to your apiUrls, or null. |
| handleApiResponse(url, response) | After a request: "retry" (send again once), "step-up" (handled) or "ok". |
| isApiUrl(url) | Whether url is in apiUrls. |
| getAccessToken() | The raw access token. Rarely needed: it is useless without a matching proof. |
Framework integrations
| Import | Exports |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| @identigo/browser/angular | provideIdentigo(config), identigoInterceptor, injectIdentigo() (signals user, isSignedIn, plus actions), signedIn({ role?, level?, otherwise? }), IDENTIGO token |
| @identigo/browser/react | <IdentigoProvider client fallback? blocking? onRedirect?>, useIdentigo(), <SignedIn>, <SignedOut>, <Protect role? level? fallback?> |
| @identigo/browser/vue | createIdentigo(config) (plugin), useIdentigo(), identigoGuard(identigo) with meta.auth: true \| { role?, level?, otherwise? } |
| @identigo/browser/axios | attachIdentigo(instance, client) → detach function |
Every entry point re-exports IdentigoClient and the types.
Local development
- Identigo on
http://localhost: addallowInsecure: true. Never ship it. - Your app on
http://localhost:5173: registerhttp://localhost:5173/callback,http://localhost:5173/and the origin on a development app. Identigo acceptshttponly for loopback addresses. - Signed out on every reload? The browser is blocking IndexedDB (some private windows do); the SDK falls back to memory.
Security notes
- What no browser SDK can stop. Script running in your page — an XSS bug, a compromised dependency — can make requests as the user while the page is open. It can't take the key or a usable token elsewhere. Use a strict Content Security Policy and Trusted Types, and keep dependencies audited.
- Prefer a backend-for-frontend for high-value apps. For payments or very sensitive data, a
server-side client (
private_key_jwt+ DPoP) can keep tokens off the browser entirely and give the page anHttpOnlysession cookie. That is Identigo's recommended profile (docs/06-security §5.2); this SDK is the strongest option when the app must be a pure SPA. - Roles in the browser are for display.
hasRole(),<Protect role>and route guards decide what to show; your API must enforce permissions itself.
Upgrading from 0.1
apiUrls: tokens are now only sent to the APIs you list. If you call an API on another origin, add it, orfetch()will throw.- Step-up is automatic: an API's step-up challenge now redirects the user to Identigo. Pass
onStepUpto keep handling it yourself. init()can be called more than once: it runs once per page load.ready()is the same.redirectUriandpostLogoutRedirectUriare optional (defaults above);isAuthenticatedis nowisSignedIn(the old name still works).
Development
Inside the monorepo the package is consumed as TypeScript source (exports → src/*.ts).
npm run build emits ESM + .d.ts to dist/; npm pack / npm publish run prepack, which builds
and points exports at dist/ for the tarball (postpack restores it). Releases are published from CI
only, with npm trusted publishing — see
docs/runbooks/release-sdks.md.
