@identityprovider/servicestack

A lightweight wrapper for @identityprovider/client that seamlessly integrates with ServiceStack via its JsonServiceClient.

This SDK is designed to simplify OpenID Connect (OIDC) authentication and token management for applications that already use ServiceStack. It provides a unified client with built-in support for:

✨ Features

• Authorization Code Flow with PKCE
• silentAuthorize() via invisible iframe (prompt=none)
• Secure logout with postLogoutRedirectUri and idTokenHint
• Session-scoped PKCE values stored in sessionStorage
• Configurable PKCE cleanup delay (handles React double-render issues)
• Optional integration with your backend to manage HttpOnly cookie-based tokens
• Full ID token validation
• Seamless drop-in for JsonServiceClient-based apps

🚀 Installation

1npm install @identityprovider/servicestack

You must also install its peer dependencies:

1npm install @identityprovider/client @servicestack/client

🧱 Usage

1import { ServiceStackClient } from "@identityprovider/servicestack";
2
3const client = new ServiceStackClient(
4    "https://my-app.com",                 // Your app's API base URL
5    "https://identity.mycompany.com",     // Your IdP's base URL
6    "my-client-id",                       // OIDC client_id
7    5000                                  // Optional: PKCE cleanup delay (ms)
8);
9
10// Start login
11await client.authorize({
12    redirectUri: "https://my-app.com/callback",
13    scope: "openid profile email"
14});
15
16// Silent login if user is already authenticated
17const code = await client.silentAuthorize({
18    scope: "openid profile email"
19});
20
21// Exchange the code for tokens
22const tokens = await client.token({
23    code,
24    redirectUri: "https://my-app.com/callback"
25});
26
27// Log out the user
28client.logout({
29    postLogoutRedirectUri: "https://my-app.com/logout"
30});

🔄 PKCE Session Storage

PKCE state, nonce, and code_verifier values are stored in sessionStorage and automatically cleared after a successful token exchange, using a delay (default: 5 seconds) to support React’s double-rendering behavior.

You can customize this delay by passing a fourth argument to the constructor:

1const client = new ServiceStackClient(apiUrl, idpUrl, clientId, 7000); // 7 seconds

🔐 HttpOnly Token Flow

If you’re managing tokens via secure HttpOnly cookies (recommended), pass a tokenExchangeHandler to the .token() method:

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

🛠️ ServiceStack-Specific Features

Because this client extends JsonServiceClient, you can use ServiceStack features like:

1client.enableAutoRefreshToken = true;
2
3client.onAuthenticationRequired = async () => {
4    await client.authorize({ redirectUri: "https://my-app.com/callback" });
5};
6
7client.bearerToken = tokens.accessToken; // If you manage tokens manually
8client.refreshTokenUri = "/api/refresh"; // If you use custom refresh endpoint

🧪 Typed Error Handling

This client surfaces all errors from @identityprovider/client, including:

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

Handle them with instanceof:

1try {
2  await client.token();
3} catch (e) {
4  if (e instanceof TokenExchangeError) {
5    console.error("Token error:", e.message);
6  }
7}

🛡️ Security Best Practices

• Always use state and nonce (handled automatically)
• Prefer HttpOnly cookie storage over in-memory access tokens
• Use SameSite=Lax or Strict for session cookies
• Avoid storing tokens in localStorage or sharing across tabs

📦 License

MIT