@identityprovider/client

A lightweight and framework-agnostic TypeScript client for interacting with an OpenID Connect (OIDC) Identity Provider using Authorization Code Flow with PKCE.

✨ Features

• Full PKCE-based authorization
• authorize() + silentAuthorize() for login flows
• Handles state, nonce, codeVerifier generation, storage, & validation
• Uses sessionStorage for short-term, tab-isolated security artifacts
• Token exchange with direct IdP call or custom local API (ideal for secure HttpOnly cookies)
• Configurable PKCE cleanup delay for React/SPAs
• Robust error handling with custom error types
• Framework-agnostic: works with React, Vue, Svelte, plain JavaScript

---

🚀 Installation

1npm install @identityprovider/client

🧱 Usage

1. Instantiate the client

1import { IdentityProviderClient } from "@identityprovider/client";
2
3// cleanupDelayMs (optional): default is 5000 ms (5 seconds)
4const client = new IdentityProviderClient(
5    "https://idp.example.com",     // Base URL of the Identity Provider
6    "your-client-id",              // OIDC client_id
7    5000                           // Optional: PKCE cleanup delay in milliseconds
8);

2. Start the authorization flow

1await client.authorize({
2  redirectUri: "https://your-app.com/callback",
3  scope: "openid profile email"
4});

This will redirect the user to the Identity Provider's login screen.

3. Handle the callback and exchange tokens

✅ In-memory/localStorage token handling:

1const response = await client.token({ 
2    code,
3    redirectUri: "https://your-app.com/callback"
4});
5// response.accessToken, response.idToken, etc.

You do not need to pass any options.

🔐 Secure HttpOnly cookie-based flow (recommended):

1await client.token({
2  code,
3  redirectUri: "https://your-app.com/callback",
4  tokenExchangeHandler: async (request) => {
5    const res = await fetch("/api/connect/token", {
6      method: "POST",
7      body: JSON.stringify(request),
8      headers: {
9        "Content-Type": "application/json"
10      },
11      credentials: "include" // important!
12    });
13
14    if (!res.ok) {
15      throw new Error("Token exchange failed");
16    }
17
18    return await res.json();
19  }
20});

Your backend should then:

1. Call the Identity Provider's /connect/token
2. Set secure HttpOnly cookies (access and refresh tokens)

🔄 Silent Authorization

You can use the silentAuthorize method to refresh tokens without user interaction. This is useful for maintaining a session without prompting the user.

1const code = await client.silentAuthorize({ scope: "openid profile email" });

This will:

• Loads an invisible iframe
• Performs a prompt=none flow
• Resolves with an authorization code if still authenticated
• Throws SilentAuthorizationError if not

🚪 Logout

Use the logout() method to log out the user by redirecting them to the Identity Provider’s logout endpoint.

1client.logout({ postLogoutRedirectUri: "https://your-app.com/logout" });

⚙️ Advanced Options

cleanupDelayMs (constructor)

Controls how long to retain PKCE-related values (state, nonce, code_verifier) in sessionStorage after a successful token exchange.

1new IdentityProviderClient("https://idp", "clientId", 7000); // Keep values for 7s

Recommended: at least 3–5 seconds for React dev mode double renders.

❌ Typed Error Handling

All client errors extend Error and can be caught using instanceof:

• StateMismatchError
• CodeVerifierMissingError
• NonceMissingError
• IdTokenMissingError
• TokenExchangeError
• SilentAuthorizationError

Example:

1try {
2  await client.token();
3} catch (err) {
4  if (err instanceof StateMismatchError) {
5    alert("State does not match — possible CSRF!");
6  }
7}

🛡️ Security Best Practices

• Always validate state and nonce (the client does this for you)
• Prefer using HttpOnly cookies via your own API
• Set SameSite=Strict or Lax on cookies where appropriate
• Avoid persisting tokens in localStorage

📦 License

MIT