1 of 25

v6

Installation

There are known issues with the v6 of oidc-spa. I'm actively working on it.

Before starting be aware that oidc-spa is not suited for Next.js or any other framwork that involves server side rendering.

If you are using Next the closer alternative is to use (with if you are using Keycloak). See .

If you're having issues don't hesitate to !

Let's install in your project:

npm install oidc-spa

yarn add oidc-spa

pnpm add oidc-spa

bun add oidc-spa

Create the oidc-callback. file in your public/ directory:

public/oidc-callback.htm

<!doctype html>
<html>
<body>
    <!-- oidc-spa file. Do not remove, do not edit -->
    <script>
        if (localStorage.getItem("oidc-spa.callback-file-version") !== "2") { alert("Your oidc-callback.htm file is outdated. Please update it. https://docs.oidc-spa.dev/v/v6"); } const authResponse = {}; for (const [key, value] of new URL(location.href).searchParams) { authResponse[key] = value; } const reloadOnRestore = ()=> { const listener = ()=> { if (document.visibilityState === "visible") { document.removeEventListener("visibilitychange", listener); location.reload(); } }; document.addEventListener("visibilitychange", listener); }; const stateJson = localStorage.getItem(`oidc.${authResponse.state}`); if (!stateJson || stateJson === "null") { reloadOnRestore(); const KEY = "oidc-spa.has-navigated-back"; if (sessionStorage.getItem(KEY) === "true") { sessionStorage.removeItem(KEY); history.forward(); } else { sessionStorage.setItem(KEY, "true"); history.back(); } } const { data } = JSON.parse(stateJson); if (data.isSilentSso) { parent.postMessage(authResponse, location.origin); } else { reloadOnRestore(); const redirectUrl = new URL(data.redirectUrl); for (const [key, value] of Object.entries(authResponse)) { redirectUrl.searchParams.set(`oidc-spa.${key}`, value); } location.href = redirectUrl.href; }
    </script>
</body>
</html>

On your OIDC Server, in your client configuration, define Valid Redirect URIs: https://oidc-callback.htm, http://localhost:/oidc-callback.htm. .

Doing without the oidc-callback.htm file

If for some reasons it's not fesable or practical for you to rely on the oidc-callback.htm it's fine, this file is only here for optimisation purposes but the lib works without it.

To let oidc-spa know that you won't be using the oidc-callback.htm file provide those parameter when initializing the adapter:

 export const { ... } = createOidc({
     // ...
-    BASE_URL: import.meta.env.BASE_URL,
+    BASE_URL: undefined
     // Provide the path of your homepage.
     // It's usually "/" but it can be for example "/dashboard"
     // If your app is accessible at https://your-domain.com/dashboard
+    homeUrl: "/"
 });

As Valid Redirec URIs use the home of your app without trailing shlash at the end. Example: https://my-app.com or https//my-app.com/dashboard and http://localhost:5173 or http://localhost:5173/dashboard

Basic Usage

Let's get your App authenticated!

In this section we assume that you have access to an OIDC Server, that you have created and configured an OIDC client for your application and that you have a hold on your issuer uri and client id.

import { createOidc } from "oidc-spa";

const oidc = await createOidc({
    issuerUri: "https://auth.your-domain.net/realms/myrealm",
    clientId: "myclient",
    /**
     * Vite:  `publicUrl: import.meta.env.BASE_URL`
     * CRA:   `publicUrl: process.env.PUBLIC_URL`
     * Other: `publicUrl: "/"` (Usually)
     */
    BASE_URL: import.meta.env.BASE_URL
});

if (!oidc.isUserLoggedIn) {
    // The user is not logged in.

    // We can call login() to redirect the user to the login/register page.
    // This return a promise that never resolve. 
    oidc.login({
         /** 
          * If you are calling login() in the callback of a click event
          * set this to false.  
          */
         doesCurrentHrefRequiresAuth: false
         /** 
          * Optionally, you can add some extra parameter 
          * to be added on the login url.  
          * (Can also be a parameter of createOidc `extraQueryParams: ()=> ({ ui_locales: "fr" })`)
          */
         //extraQueryParams: { kc_idp_hint: "google", ui_locales: "fr" }
         /**
          * You can allso set where to redirect the user after 
          * successful login
          */
          // redirectUrl: "/dashboard"
          
          /**
           * Keycloak: You can also send the users directly to the register page
           * see: https://github.com/keycloakify/oidc-spa/blob/14a3777601c50fa69d1221495d77668e97443119/examples/tanstack-router-file-based/src/components/Header.tsx#L54-L66
           */ 
    });

} else {
    // The user is logged in.

    const {
        // The accessToken is what you'll use as a Bearer token to 
        // authenticate to your APIs
        accessToken,
        decodedIdToken
    } = oidc.getTokens();

    fetch("https://api.your-domain.net/orders", {
        headers: {
            Authorization: `Bearer ${accessToken}`
        }
    })
     .then(response => response.json())
     .then(orders => console.log(orders));

    // To call when the user click on logout.
    // You can also redirect to a custom url with 
    // { redirectTo: "specific url", url: "/bye" }
    oidc.logout({ redirectTo: "home" });

    // If you are wondering why ther's a decodedIdToken and no
    // decodedAccessToken read this: https://docs.oidc-spa.dev/resources/jwt-of-the-access-token
    console.log(`Hello ${decodedIdToken.preferred_username}`);

    // Note that in this example the decodedIdToken is not typed.  
    // What is inside the idToken is defined by the OIDC server you are using.  
    // If you want to specify the type of the decodedIdToken you can do:
    //
    // import { z } from "zod";
    // export const { useOidc } = createUseOidc({
    //    ...
    //    decodedIdTokenSchema: z.object({
    //        sub: z.string(),
    //        preferred_username: z.string(),
    //        // ... other properties
    //    })
    // })

}

This piece of code should give you the necessary information to understand how oidc-spa can be used inside your react components. To go further you can refer to the examples setup to see how to integrate oidc-spa with your routing library:

react-router-dom example setup
@tanstack/react-router example setup

import { createReactOidc } from "oidc-spa/react";

export const { OidcProvider, useOidc, getOidc } = createReactOidc({
    // NOTE: If you don't have the params right away see note below.
    issuerUri: "https://auth.your-domain.net/realms/myrealm",
    clientId: "myclient",
    /**
     * Vite:  `publicUrl: import.meta.env.BASE_URL`
     * CRA:   `publicUrl: process.env.PUBLIC_URL`
     * Other: `publicUrl: "/"` (Usually)
     */
    BASE_URL: import.meta.env.BASE_URL
});

ReactDOM.createRoot(document.getElementById("root")!).render(
    <OidcProvider
        // Optional, it's usually so fast that a fallback is really not required.
        fallback={<>Checking authentication ⌛️</>}
    >
        <App />
    </OidcProvider>
);

function App() {

    const { isUserLoggedIn, login, logout, oidcTokens } = useOidc();

    return (
        isUserLoggedIn ? (
            <>
                {/* 
                Note: The decodedIdToken can be typed and validated with zod See: https://github.com/keycloakify/oidc-spa/blob/fddac99d2b49669a376f9a0b998a8954174d195e/examples/tanstack-router/src/oidc.tsx#L17-L43
                If you are wondering why ther's a decodedIdToken and no
                decodedAccessToken read this: https://docs.oidc-spa.dev/resources/jwt-of-the-access-token
                */}
                <span>Hello {oidcTokens.decodedIdToken.preferred_username}</span>
                <button onClick={() => logout({ redirectTo: "home" })}>
                  Logout
                </button>
            </>
        ) : (
            <button onClick={() => login({ 
                /** 
                 * If you are calling login() in the callback of a button click
                 * (like here) set this to false.  
                 */
                doesCurrentHrefRequiresAuth: false
                /** 
                 * Optionally, you can add some extra parameter 
                 * to be added on the login url.
                 * (Can also be a parameter of createReactOidc `extraQueryParams: ()=> ({ ui_locales: "fr" })`)
                 */
                //extraQueryParams: { kc_idp_hint: "google", ui_locales: "fr" }
                /**
                 * You can allso set where to redirect the user after 
                 * successful login
                 */
                // redirectUrl: "/dashboard"
                /**
                 * Keycloak: You can also send the user direcly to the register page
                 * See: https://github.com/keycloakify/oidc-spa/blob/14a3777601c50fa69d1221495d77668e97443119/examples/tanstack-router-file-based/src/components/Header.tsx#L54-L66
                 */
            })} >
              Login
            </button>
        )
    );
}

import { useEffect, useState } from "react";

type Order = {
  id: number;
  name: string;
};

function OrderHistory(){

    const { oidcTokens } = useOidc({ assert: "user logged in" });

    const [orders, setOrders] = useState<Order[] | undefined>(undefined);

    useEffect(
        ()=> {

            fetch("https://api.your-domain.net/orders", {
                headers: {
                    Authorization: `Bearer ${oidcTokens.accessToken}`
                }
            })
            .then(response => response.json())
            .then(orders => setOrders(orders));

        },
        []
    );

    if(orders === undefined){
        return <>Loading orders ⌛️</>
    }

    return (
        <ul>
            {orders.map(order => (
                <li key={order.id}>{order.name}</li>
            ))}
        </ul>
    );

}

If you get your OIDC parameters from an API you can passes an assync function that returns the oidc parameters. This function gets called when <OidcProvider /> is first mounted or when getOidc() is first called.

export const { 
  OidcProvide, 
  useOidc, 
  getOidc 
} = createReactOidc(async ()=> {

    const { 
        issuerUri, 
        clientId 
    } = await axios.get("/oidc-params").then(r => r.data);

    return {
        issuerUri,
        clientId,
        publicUrl: import.meta.env.BASE_URL
    };
    
});

Web API

The primary usecase for a library like oidc-spa is to use it to authenticate a REST, tRPC, or Websocket API.

Let's see a very basic REST API example:

Initialize oidc-spa and expose the oidc instance as a promise:

src/oidc.ts

import { createOidc } from "oidc-spa";

export const prOidc = createOidc({/* ... */});

Create a REST API Client that adds the OIDC Access Token as Autorization header to every HTTP request:

src/api.ts

import axios from "axios";
import { prOidc } from "oidc";

type Api = {
    getTodos: () => Promise<{ id: number; title: string; }[]>;
    addTodo: (todo: { title: string; }) => Promise<void>;
};

const axiosInstance = axios.create({ baseURL: import.meta.env.API_URL });

axiosInstance.interceptors.request.use(async config => {

    const oidc= await prOidc;

    if( !oidc.isUserLoggedIn ){
        throw new Error("We made a logic error: If the user isn't logged in we shouldn't be making request to an API endpoint that requires authentication");
    }
    
    config.headers.Authorization = `Bearer ${oidc.getTokens().accessToken}`;

    return config;

});

export const api: Api = {
    getTodo: ()=> axiosInstance.get("/todo").then(response => response.data),
    addTodo: todo => axiosInstance.post("/todo", todo).then(response => response.data)
};

Initialize the React adapter of oidc-spa and expose the prOidc object, a promise of the vanilla OIDC API:

src/oidc.ts

import { createReactOidc } from "oidc-spa/react";

export const { 
    OidcProvider, 
    useOidc,
    getOidc
} = createReactOidc(/* ... */);

Create a REST API Client that adds the OIDC Access Token as Autorization header to every HTTP request:

src/api.ts

import axios from "axios";
import { getOidc } from "oidc";

type Api = {
    getTodos: () => Promise<{ id: number; title: string; }[]>;
    addTodo: (todo: { title: string; }) => Promise<void>;
};

const axiosInstance = axios.create({ baseURL: import.meta.env.API_URL });

axiosInstance.interceptors.request.use(async config => {

    const oidc= await getOidc();

    if( !oidc.isUserLoggedIn ){
        throw new Error("We made a logic error: The user should be logged in at this point");
    }
    
    config.headers.Authorization = `Bearer ${oidc.getTokens().accessToken}`;

    return config;

});

export const api: Api = {
    getTodo: ()=> axiosInstance.get("/todo").then(response => response.data),
    addTodo: todo => axiosInstance.post("/todo", todo).then(response => response.data)
};

Using your REST API client in your REACT components:

import { api } from "../api";

type Todo= {
    id: number; 
    title: string;
};

function UserTodos(){

    const [todos, setTodos] = useState<Todo[] | undefined>(undefined);

    useEffect(
        ()=> {
            api.getTodos().then(todos => setTodos(todos));
        },
        []
    );

    if(todos === undefined){
        return <>Loading your todos items ⌛️</>
    }

    return (
        <ul>
            {todos.map(todo => (
                <li key={todo.id}>{todo.title}</li>
            ))}
        </ul>
    );

}

This example is purposefully very basic to minimize noise but in your App you might want to consider using solutions like tRPC (if you have JS backend) and TanStack Query.

Backend

If you're implementing a JavaScript Backend (Node/Deno/webworker) oidc-spa also exposes an utility to help you validate and decode the access token that your client sends in the authorization header. Granted, this is fully optional feel free to use anything else. Let's assume we have a Node.js REST API build with Express or Hono. You can create an oidc file as such:

src/oidc.ts

import { createOidcBackend } from "oidc-spa/backend";
import { z } from "zod";
import { HTTPException } from "hono/http-exception";

export async function createDecodeAccessToken() {

    const oidcIssuerUri = process.env.OIDC_ISSUER

    if (oidcIssuerUri === undefined) {
        throw new Error("OIDC_ISSUER must be defined in the environment variables")
    }

    const { verifyAndDecodeAccessToken } = await createOidcBackend({ 
        issuerUri: oidcIssuerUri,
        decodedAccessTokenSchema: z.object({
            sub: z.string(),
            realm_access: z.object({
                roles: z.array(z.string())
            })
            // Some other info you might want to read from the accessToken, example:
            // preferred_username: z.string()
        })
    });

    function decodeAccessToken(params: { 
        authorizationHeaderValue: string | undefined; 
        requiredRole?: string;
    }) {

        const { authorizationHeaderValue, requiredRole } = params;

        if( authorizationHeaderValue === undefined ){
            throw new HTTPException(401);
        }

        const result = verifyAndDecodeAccessToken({ 
            accessToken: authorizationHeaderValue.replace(/^Bearer /, "") 
        });

        if( !result.isValid ){
            switch( result.errorCase ){
                case "does not respect schema":
                    throw new Error(`The access token does not respect the schema ${result.errorMessage}`);
                case "invalid signature":
                case "expired":
                    throw new HTTPException(401);
            }
        }
        
        const { decodedAccessToken } = result;
        
        if( 
          requiredRole !== undefined &&
          !decodedAccessToken.ream_access.roles.includes(requiredRole)
        ){
            throw new HTTPException(401);
        }

        return decodedAccessToken;

    }

    return { decodeAccessToken };

}

Then you can enforce that some endpoints of your API requires the user to be authenticated, in this example we use Hono:

import { z, createRoute, OpenAPIHono } from "@hono/zod-openapi";
import { serve } from "@hono/node-server"
import { HTTPException } from "hono/http-exception";
import { getUserTodoStore } from "./todo";
import { createDecodeAccessToken } from "./oidc";

(async function main() {

    const { decodeAccessToken } = await createDecodeAccessToken();

    const app = new OpenAPIHono();

 
    {

        const route = createRoute({
            method: 'get',
            path: '/todos',
            responses: {/* ... */}
        });

        app.openapi(route, async c => {

            const decodedAccessToken = decodeAccessToken({
                authorizationHeaderValue: c.req.header("Authorization")
            });

            if (decodedAccessToken === undefined) {
                throw new HTTPException(401);
            }

            const todos = getUserTodoStore(decodedAccessToken.sub).getAll();

            return c.json(todos);

        });

    }

    const port = parseInt(process.env.PORT);

    serve({
        fetch: app.fetch,
        port
    })

    console.log(`\nServer running. OpenAPI documentation available at http://localhost:${port}/doc`)

})();

Comprehensive example

If you're looking for a comprehensive Backend+Frontend example you can refer to Insee's project

The app is live here:

The frontend (Vite project):

The backend (Node TODO App REST API):

Auto Logout

Automatically logging out your user after a set period of inactivity on your app (they dont move the mouse or press any key on the keyboard for a while)

Configuring auto logout policy

Important to understand: This is a policy that is enforced on the identity server. Not on in the application code!

The auto logout is defined by the lifespan of the refresh token.

For example, if you're using Keycloak and you want an auto disconnect after 5 minutes of inactivity you would set the SSO Session Idle to 5 minutes. See .

If you can't configure your OIDC server you can still enforce auto logout like so:

import { createOidc } from "oidc-spa";

const oidc = await createOidc({
  // ...
  __unsafe_ssoSessionIdleSeconds: 10 * 60 // 10 minutes
  //autoLogoutParams: { redirectTo: "current page" } // Default
  //autoLogoutParams: { redirectTo: "home" }
  //autoLogoutParams: { redirectTo: "specific url", url: "/a-page" }
});

import { createReactOidc } from "oidc-spa/react";

export const {
    OidcProvider,
    useOidc
} = createReactOidc({
    // ...
    __unsafe_ssoSessionIdleSeconds: 10 * 60 // Ten minutes
    //autoLogoutParams: { redirectTo: "current page" } // Default
    //autoLogoutParams: { redirectTo: "home" }
    //autoLogoutParams: { redirectTo: "specific url", url: "/a-page" }
});

Note that this parameter is marked as unsafe because what happens if the user closes the tab? He will be able to return a while back and still be logged in. oidc-spa can't enforce a security policy when it's not running. Only the identity server can.

Displaying a coutdown timer before auto logout

const { unsubscribeFromAutoLogoutCountdown } = oidc.subscribeToAutoLogoutCountdown(
  ({ secondsLeft }) => {
    if( secondsLeft === undefined ){
      console.log("Countdown reset, the user moved");
      return;
    }
    if( secondsLeft > 60 ){
      return;
    }
    console.log(`${secondsLeft} before auto logout`)
  }
);

Auto Login

Enforce authentiaction everywhere on your app

If there is no part of your app that can be browsed without being logged which is typically the case for application like dashboard or administration pannel, you can make oidc-spa automatically redirect users to the login pages when they are not authenticated.

In this mode you don't have to:

Check isUserLoggedIn, it will always be true.
(React) Use useOidc({ assert: "user logged in" }) you know that's the case.

import { createOidc, type OidcInitializationError } from "oidc-spa";

const oidc = await createOidc({
    // ...
    autoLogin: true,
    // Optional, the default value is: location.href (here)
    // postLoginRedirectUrl: "/dashboard"
})
.catch((error: OidcInitializationError) => {
    // Here you need to handle the potential initialization error
    // because in this mode we cannot fallback to the user being
    // not authenticated if we ran into an error.

    if( !error.isAuthServerLikelyDown ){
        // This mean that there is an issue in the configuration
        // of your OIDC server.
        throw error;
    }

    alert("Sorry our authentication server is down, try again later");

    return new Promise<never>(() => {});

});

src/oidc.ts

import { createReactOidc } from "oidc-spa/react";

export const {
    OidcProvider,
    useOidc,
    prOidc
} = createReactOidc({
   // ...
   autoLogin: true,
   // Optional, the default value is: location.href (here)
   // postLoginRedirectUrl: "/dashboard"
});

src/main.tsx

import React from "react";
import ReactDOM from "react-dom/client";
import { OidcProvider } from "oidc";

const router = createRouter({ routeTree });

ReactDOM.createRoot(document.getElementById("root")!).render(
    <React.StrictMode>
        <OidcProvider
            ErrorFallback={({ initializationError }) => (
                <h1 style={{ color: "red" }}>
                    {initializationError.isAuthServerLikelyDown ? (
                        <>Sorry our authentication server is currently down, please try again later</>
                    ) : (
                        // NOTE: Check initializationError.message for debug information.
                        // It's an error on your end no need to show it to the user.
                        <>Unexpected authentication error </>
                    )}
                </h1>
            )}
        >
            <RouterProvider router={router} />
        </OidcProvider>
    </React.StrictMode>
);

Error Management

Gracefully handle authentication issues

What happens if the OIDC server is down, or if your OIDC server isn't properly configured?

By default, , when there is an error with the OIDC initialization your website will load with the user unauthenticated.

This allows the user to at least access parts of the application that do not require authentication. When the user clicks on the login button (triggering the login() function), a browser alert is displayed, indicating that authentication is currently unavailable, and no further action is taken.

You can customize this behavior. An initializationError object is present on the oidc object if an error occurred.

import { createOidc } from "oidc-spa";

const oidc = await createOidc(...);

if( !oidc.isUserLoggedIn ){
    // If the used is logged in we had no initialization error.
    return;
}

if( oidc.initializationError ){

    // This help you discriminate configuration errors
    // and error due to the server being temporarely down.
    console.log(oidc.initializationError.isAuthServerLikelyDown);
    
    const handleLoginClick = ()=> {
    
        if( oidc.initializationError ){
            alert(`Can't login now, try again later ${oidc.initializationError.message}`);
            return;
        }
        
        oidc.login(...);
    
    };
}

import { useOidc } from "oidc";
import { useEffect } from "react";

function LoginButton() {

    const { isUserLoggedIn, login, logout initializationError } = useOidc();

    useEffect(() => {
        if (initializationError) {
            // This help you discriminate configuration errors
            // and error due to the server being temporarely down.
            console.log(initializationError.isAuthServerLikelyDown);
        
            // This is a debug message that tells you what's wrong
            // with your configuration and how to fix it.  
            // (this is not something you want to display to the user)
            console.log(initializationError.message);
        }
    }, []);

    if (isUserLoggedIn) {
        return <button onClick={()=> logout({ redirectTo: "home" })}>Logout</button>;
    }

    return (
        <button onClick={() => {

            if (initializationError) {
                alert("Can't login now, try again later")
                return;
            }

            login({ ... });

        }}>
            Login
        </button>
    );

}

Mock

For certain use cases, you may want a mock adapter to simulate user authentication without involving an actual authentication server.

This approach is useful when building an app where user authentication is a feature but not a requirement. It also proves beneficial for running tests or in Storybook environments.

import { createOidc } from "oidc-spa";
import { createMockOidc } from "oidc-spa/mock";
import { z } from "zod";

const decodedIdTokenSchema = z.object({
    sub: z.string(),
    preferred_username: z.string()
});

const oidc = !import.meta.env.VITE_OIDC_ISSUER
    ? await createMockOidc({
          isUserInitiallyLoggedIn: false,
          // This is only so we know where to redirect when 
          // you call `logout({ redirectTo: "home" })`
          homeUrl: import.meata.env.BASE_URL,
          mockedTokens: {
              decodedIdToken: {
                  sub: "123",
                  preferred_username: "john doe"
              } satisfies z.infer<typeof decodedIdTokenSchema>
          }
      })
    : await createOidc({
          issuerUri: import.meta.env.VITE_OIDC_ISSUER,
          clientId: import.meta.env.VITE_OIDC_CLIENT_ID,
          BASE_URL: import.meta.env.BASE_URL,
          decodedIdTokenSchema
      });

src/oidc.ts

import { createReactOidc } from "oidc-spa/react";
import { createMockReactOidc } from "oidc-spa/mock/react";
import { z } from "zod";

const decodedIdTokenSchema = z.object({
    sub: z.string(),
    preferred_username: z.string()
});

const publicUrl = import.meta.env.BASE_URL;

export const { OidcProvider, useOidc, getOidc } =
    !import.meta.env.VITE_OIDC_ISSUER ?
        createMockReactOidc({
            isUserInitiallyLoggedIn: false,
            // This is only so we know where to redirect when 
            // you call `logout({ redirectTo: "home" })`
            homeUrl: import.meta.env.BASE_URL,
            mockedTokens: {
                decodedIdToken: {
                    sub: "123",
                    preferred_username: "john doe"
                } satisfies z.infer<typeof decodedIdTokenSchema>
            }
        }) :
        createReactOidc({
            issuerUri: import.meta.env.VITE_OIDC_ISSUER,
            clientId: import.meta.env.VITE_OIDC_CLIENT_ID,
            BASE_URL: import.meta.env.BASE_URL,
            decodedIdTokenSchema
        });

User Account Management

In this section we assume you are using Keycloak. If you are using another authentication server you'll have to addapt the queryParameter provided.

When your user is logged in, you can provide a link to redirect to Keycloak so they can manage their account.

There is thee main actions:

UPDATE_PASSWORD: Enables the user to change their password.
UPDATE_PROFILE: Enable the user to edit teir account information such as first name, last name, email, and any additional user profile attribute that you might have configured on your Keycloak server.
delete_account: (In lower case): This enables the user to delete he's account. You must enable it manually on your Keycloak server Admin console. See .

Let's, as an example, how you would implement an update password button:

import { createOidc } from "oidc-spa";

const oidc = await createOidc({ ... });

if( oidc.isUserLoggedIn ){

   // Function to invoke when the user click on your "change my password" button.
   const updatePassword = ()=>
      oidc.goToAuthServer({
         extraQueryParams: { 
             kc_action: "UPDATE_PASSWORD" 
         }
      });
   // NOTE: This is optional, it enables you to display a feedback message
   // when the user is redirected back to your application after completing
   // or canceling the action.
   if( 
      oidc.backFromAuthServer?.extraQueryParams.kc_action === "UPDATE_PASSWORD"
   ){
      switch(oidc.backFromAuthServer.result.kc_action_status){
          case "canceled": 
             alert("You password was not updated");
             break;
          case "success":
             alert("Your password has been updated successfuly");
             break;
      }
   }
}

function ProtectedPage() {
    // Here we can safely assume that the user is logged in.
    const { goToAuthServer, backFromAuthServer } = useOidc({ assert: "user logged in" });

    return (
        <>
            <button
                onClick={() =>
                    goToAuthServer({
                        extraQueryParams: { kc_action: "UPDATE_PASSWORD" }
                    })
                }
            >
                Change password
            </button>
            {/* 
            Optionally you can display a feedback message to the user when they
            are redirected back to the app after completing or canceling the
            action.
            */}
            {backFromAuthServer?.extraQueryParams.kc_action === "UPDATE_PASSWORD" && (
                <p>
                    {(()=>{
                        switch(backFromAuthServer.result.kc_action_status){
                            case "success":
                                return "Password successfully updated";
                            case "cancelled":
                                return "Password unchanged";
                        }
                    })()}
                </p>
            )}
        </>
    );
}

User Session Initialization

In some cases, you might want to perform some operation to initialize the user's session. This could involve calling a special API endpoint or clearing some cached values in the local storage. What you don't want, however, is to run this every time the user refreshes the page. To help you determine if the session should be initialized, you can leverage the isNewBrowserSession property that is available when the user is logged in.

import { createOidc } from "oidc-spa";

const oidc = await createOidc({ /* ... */ });

if (oidc.isUserLoggedIn && oidc.isNewBrowserSession) {
  // This is a new visit of this user.
}

if(oidc.isUserLoggedIn && oidc.isNewBrowserSession && oidc.backFromAuthServer ){
  // This is a new visit AND a new OIDC session has just beeing created.
  // on the OIDC server.
}

src/oidc.ts

import { createReactOidc } from "oidc-spa/react";

export const {
    /* ... */
    getOidc
} = createReactOidc({ /* ... */ });

getOidc().then(oidc => {
  
    if (oidc.isUserLoggedIn && oidc.isNewBrowserSession) {
      // This is a new visit of this user.
    }
    
    if(oidc.isUserLoggedIn && oidc.isNewBrowserSession && oidc.backFromAuthServer ){
      // This is a new visit AND a new OIDC session has just beeing created.
      // on the OIDC server.
    }

});

You can also do this in your React component (although it's maybe not the best approach)

import { useOidc } from "./oidc";
import { useEffect } from "react";

function MyComponent(){

    const { isUserLoggedIn, isNewBrowserSession, backFromAuthServer } = useOidc();
    
    useEffect(()=> {
    
        // Warning! In dev mode, when React Strict Mode is enabled
        // this will be called twice!
        
        if (isUserLoggedIn && isNewBrowserSession) {
          // This is a new visit of this user.
        }
        
        if(isUserLoggedIn && isNewBrowserSession && backFromAuthServer ){
          // This is a new visit AND a new OIDC session has just beeing created.
          // on the OIDC server.
        }
    
    }, []);

Tokens Renewal

You probably don't need to do it. The token refresh is handled automatically for you, however you can manually trigger a token refresh:

import { createOidc } from "oidc-spa";

const oidc = await createOidc({ ... });

if( oidc.isUserLoggedIn ){
   oidc.renewToken(
      // Optionally you can pass extra params that will be added 
      // to the body of the POST request to the openid-connect/token endpoint.
      // { extraTokenParams: { electedCustomer: "customer123" } }
      // This parameter can also be provided as parameter to the createOidc
      // function. See: https://github.com/keycloakify/oidc-spa/blob/59b8db7db0b47c84e8f383a86677e88e884887cb/src/oidc.ts#L153-L163
   );
}

import { useOidc } from "oidc";
import { useEffect } from "react";

function MyComponent(){

  const { renewTokens } = useOidc({ assertUserLoggedIn: true });
  
  useEffect(()=> {
      renewTokens(
        // Optionally you can pass extra params that will be added 
        // to the body of the POST request to the openid-connect/token endpoint.
        // { extraTokenParams: { electedCustomer: "customer123" } }
        // This parameter can also be provided as parameter to the createReactOidc
        // function. See: https://github.com/keycloakify/oidc-spa/blob/59b8db7db0b47c84e8f383a86677e88e884887cb/src/oidc.ts#L153-L163
      );
  }, []);
  
  return <>...</>;

}

You can also track when the token are being refreshed:

import { createOidc } from "oidc-spa";

const oidc = await createOidc({ ... });

if( !oidc.isUserLoggedIn ){
    oidc.subscribeToTokensChange(() => {
        console.log("Tokens change", oidc.getTokens());
    });
}

src/oidc.ts

import { createReactOidc } from "oidc-spa/react";

export const {
    /* ... */
    getOidc
} = createReactOidc({ /* ... */ });

getOidc().then(oidc => {

    if( !oidc.isUserLoggedIn ){
        return;
    }

    oidc.subscribeToTokensChange(() => {
        console.log("Tokens change", oidc.getTokens());
    });

});

Or directly in your component:

import { useOidc } from "./oidc";

export function PotectedPage() {
    const { oidcTokens } = useOidc({ assertUserLoggedIn: true});

    useEffect(()=> {

        console.log("Tokens changed", oidcTokens);

    }, [oidcTokens]);
    
    // ...
}

Example setups

TanStack Router

Vite + TypeScript + React + Tanstack Router

The example setup is live here:

Run it locally with:

git clone https://github.com/keycloakify/oidc-spa
mv oidc-spa/examples/tanstack-router-file-based oidc-spa-tanstack-router
rm -rf oidc-spa
cd oidc-spa-tanstack-router
cp .env.local.sample .env.local
yarn
yarn dev

React Router

The example setup is live here: https://example-react-router.oidc-spa.dev/

Run it locally with:

git clone https://github.com/keycloakify/oidc-spa
mv oidc-spa/examples/react-router oidc-spa-react-router
rm -rf oidc-spa
cd oidc-spa-react-router
cp .env.local.sample .env.local
yarn
yarn dev

Resources

OIDC Server Configuration

Specific guides

We have specific configuration instructions for the following Auth Software:

If you are using another OIDC Provider, no problem keep reading.

Generic Guide

Here are the key takeways for configuring.

Create a OpenID Connect client with Standard Flow AKA Authorization code flow. It's the default setting.
Disable client authentication (public client). We don't want to rely on client secret, it would be instantaneously leaked by your SPA.
In the configuration of the client, you only need a single valid redirect URIs. Let's assume that the home of your page is https://my-app.com you would set https://my-app.com/oidc-callback.htm, if your app is hosted under a sub path like https://my-app.com/dashboard, use https://my-app.com/dashboard/oidc-callback.htm. You may also want to add http://localhost:/oidc-callback.htm for local developement.
Valid post logout redirect: Same as the Valid Redirec URIs
Web Ogigins: http://my-app.com, http://localhost:5173

Keycloak Configuration

Getting the `issuerUri` and `clientId`

Oidc-spa need to two parameter to connect with your Keycloak instance, the issuerUri and the clientId.

const { ... } = createOidc({
    issuerUri: "...",
    clientId: "...",
    // ...
});

`issuerUri`

In Keycloak, the OIDC issuer uri is formatted as such:

https://<KC_DOMAIN><KC_RELATIVE_PATH>/realms/<REALM_NAME>

<KC_DOMAIN>: The domain of your Keycloak server, example: auth.my-company.com.
<KC_RELATIVE_PATH>: The sub path under your which your Keycloak is hosted. By default, in recent version of keycloak it's "" (empty string). On older Keycloak version it used to be "/auth" by default. Check how you Keycloak server is configured. This parrameter is usualy set by an environement variable. Example -e KC_HTTP_RELATIVE_PATH=/auth.
<REALM_NAME>: The name of your realm. Example: myrealm. One important note is that you should always create create a realm for your organization and never use the master realm. To create a realm navigate to https://<DOMAIN><KC_RELATIVE_PATH>/admin/master/console login as an administrator, click on the select at the top left corner of the page, click on "Create a new Realm", give it a name, save.

`clientId`

The client it is usualy something like 'myapp'. Let's see how to create a client suitable for your SPA.

Connect to your Keycloak Admin Console: https://<KC_DOMAIN><KC_RELATIVE_PATH>/admin/master/console
Login as an admin
Using the select input in the top left corner, navigate to your realm.
In the left pannel click on Clients.
Click on Create Client.
Fill in the Client ID, for example myapp, click on next.
Make sure Client authentication is off and that Standard Flow is checked in, click next.
Set two Valid Redirect URIs: https://<APP_DOMAIN><BASE_URL>oidc-callback.htm and http://localhost:<DEV_PORT>/oidc-callback.htm.
1. <APP_DOMAIN>: Examples: https://my-company.com or https://app.my-company.com. Note that in order to avoid issues related to the end of third party cookies it's important that <APP_DOMAIN> and <KC_DOMAIN> be hosted under the same root domain (my-company.com).
2. <BASE_URL>: Examples: "/" or "/dashboard/".
3. <DEV_PORT>: Example: 5173 (Default port of the Vite dev server)
4. If you are not using using the oidc-callbak.htm file, remove the /oidc-callback.htm portion of the urls, there should be no trailing slashes at the end.
Feel free to fill in the other field but they are not required. Click Save, you're done!

Session lifespawn configuration

One important policy you want to define is how often you want your user to have to authenticate again when they visite your site. Note that the parameter that we will configure here do not affect the lifespawn of the access token that remains 5 minuts by default. What we are tweaking here is for how long Keycloak will keep the session active and that is reflected in the livespawn of the reflesh token, this how oidc-spa is able to learn about it.

Let's see the good defaults for the two more common scenario:

Sensitive apps like Banking, Admin pannels ect...

For thoses kind of web applications, you want the user to have to login again each time they visit your app. You also want them to be automatically loged out after .

To enforce this policy you want to:

Disable the "Remeber Me" checkbox when logging in:
- Select your realm
- In the left menu navigate to realm settings
- Go to the Login tab
- Set "Remember Me" to Off
Set the session Idle time:
- In the Realm settings go to the Session Tab
- Set Session idle: 5min
- Session idle MAX: 14 days, if your user is actively using your app for days, there's no reason to desconect them.

You can display a coundown timer before auto logout with:

For thoses kind of app you don't want your user to have to authenticate every other day. Take YouTube for example, each time you reach the site your logged in already, we want this type of behaviour.

To enable it

Enable the possibility for your user to check a "Remeber Me" checkbox when logging in:
- Select your realm
- In the left menu navigate to realm settings
- Go to the Login tab
- Set "Remember Me" to On
Set the session idle: You want the users that haven't checked "Remember Me" to have to re authenticate once every 2 week.
- In the Realm settings go to the Session Tab
- Set Session idle and Session Idle Max to 14 days
Set the session idle Remember Me: You want the users that have explicitely checked "Remeber Me" when logging in to only have to authenticate again once every year.
- In the Session tab of the Realm settings, set Session idle Remeber Me and Session Idle Max Remember me to 356 days.

Enabling user to delete their own account

By default on Keycloak, users are not allowed to delete their accout.

If you try to implement a delete account button, when clicking on it, your users will be granted with an "action non permited" screen.

To enable it:

In the left bar navigate to Autentication -> Required Action -> "Delete Account" Enabled: On
In the left bar navigate to Realm Setting -> User Registration -> Default Roles -> Assign Role -> Filter by client -> select Delete Account and click on assign.

Ory Hydra Configuration

TODO

Dex Configuration

TODO

End of third-party cookies

TL;DR; It's mostly inconsequential.

Google is ending third-party cookies for all Chrome users in 2024 and are already disabled by default in Safari.

Let's see how it might affect you.

First of all, if your identity server and your app shares the same root domain you are not affected.

Example, if you are in the case:

Your app is hosted at www.example.com or dashboard.example.com
Your identity server, for example Keycloak, is hosted at: auth.example.com

You are not affected ✅. Indeed Both www.example.com, dashboard.example.com and auth.example.com shares the same root domain: example.com. On the other end, if you are in the folowing case:

You app is hosted at www.examples.com or dashboard.example.com
Your identity server is hosted at: auth.sowhere-else.com

Let's see how third party cookies phase out will affect you:

You will see a console warning "Third-party cookie will be blocked" in the console in production.
If a user that is authenticated close the tab of your app or close the browser and open your site again a while later. With third party cookies enabled and assuming he's session haven't expired yet he will be automaticall logged in. With third party cookies disabled your website will load in unautenticated mode. If he clicks on the login button this will trigger a full reload and he will be authenticated without having to enter he's credential again.

Conex resources:

Google reCaptcha

reCaptcha is not directly related to oidc-spa since the cookie it sets is on the thegister page (so outside of your app). Anyway, since it's a connex concern:

JWT Of the Access Token

And why it's not supposed to be read on the client side.

You might be surprised or even frustrated by the fact that oidc-spa only provides the decoded id token but not the decoded access token.

Infact the access token is supposed to be opaque for the client application is to be used only as an authentication key such as a Bearer token for an API.

As per the OIDC standard the access token is not even required to be a JWT!

But worry not, everything that you need is probably in the id token, if there is something missing in your id token that is present in your access token there is an explicit policy on your identity server in place that strips this information out. Zod is stripping out all the claims that are not specified in the schema. This might have led you to believe that there is less information in the id token than what actually is.

If, however, you still want to access the informations in the access token you can do it with:

import { decodeJwt } from "oidc-spa/tools/decodeJwt";

const decodedAccessToken = decodeJwt(oidc.getTokens().accessToken);

import { decodeJwt } from "oidc-spa/tools/decodeJwt";

const { oidcTokens } = useOidc();

const decodedAccessToken = decodeJwt(oidcTokens.accessToken);

Discord Server

Feeling a bit lost? Have a question? A feature request? Reach out on Discrord!

Migration Guides

v5 -> v6

Under construction

v4 -> v5

Very little change in the API.

The public/silent-sso.html -> to public/silent-sso.htm ()
Use getOidc() instead or prOidc (React API)

src/oidc.ts

 import { createReactOidc } from "oidc-spa/react";
 
 export const {
     OidcProvider,
     useOidc,
-    prOidc,
+    getOidc
 } = createReactOidc({ });

-prOidc.then(oidc => { /* ... */ });
+getOidc().then(oidc => { /* ... */ });

If you are using the mock with the vanilla API (not React)

 import { createOidc } from "oidc-spa";
 import { createMockOidc } from "oidc-spa/mock";
 import { z } from "zod";

 const decodedIdTokenSchema = z.object({
     sub: z.string(),
     preferred_username: z.string()
 });

 const publicUrl= import.meta.env.BASE_URL;

 const oidc = !import.meta.env.VITE_OIDC_ISSUER
-    ? await createMockOidc({
+    ? await createMockOidc({
           isUserInitiallyLoggedIn: false,
           publicUrl,
           mockedTokens: {
               decodedIdToken: {
                   sub: "123",
                   preferred_username: "john doe"
               } satisfies z.infer<typeof decodedIdTokenSchema>
           }
       })
     : await createOidc({
           issuerUri: import.meta.env.VITE_OIDC_ISSUER,
           clientId: import.meta.env.VITE_OIDC_CLIENT_ID,
           publicUrl
       });

v6

Installation

Basic Usage

Web API

Backend

Comprehensive example

Auto Logout

Configuring auto logout policy

Displaying a coutdown timer before auto logout

Auto Login

Error Management

Mock

User Account Management

User Session Initialization

Tokens Renewal

Example setups

TanStack Router

React Router

Resources

OIDC Server Configuration

Specific guides

Generic Guide

Keycloak Configuration

Getting the issuerUri and clientId

issuerUri

clientId

Session lifespawn configuration

Sensitive apps like Banking, Admin pannels ect...

Non sensitive app like ecomerce boutique or social media app

Enabling user to delete their own account

Ory Hydra Configuration

Dex Configuration

End of third-party cookies

Google reCaptcha

JWT Of the Access Token

Discord Server

Migration Guides

v5 -> v6

v4 -> v5

Sponsors

Error Management

Basic Usage

Tokens Renewal

User Session Initialization

Web API

Backend

Comprehensive example

Installation

User Account Management

Mock

TanStack Router

Auto Logout

Configuring auto logout policy

Displaying a coutdown timer before auto logout

Ory Hydra Configuration

Dex Configuration

Auto Login

v5 -> v6

Keycloak Configuration

Getting the issuerUri and clientId

issuerUri

clientId

Session lifespawn configuration

Sensitive apps like Banking, Admin pannels ect...

Non sensitive app like ecomerce boutique or social media app

Enabling user to delete their own account

React Router

OIDC Server Configuration

Specific guides

Generic Guide

End of third-party cookies

Google reCaptcha

JWT Of the Access Token

Migration Guides

Discord Server

Sponsors

v4 -> v5

Getting the `issuerUri` and `clientId`

`issuerUri`

`clientId`

Getting the `issuerUri` and `clientId`

`issuerUri`

`clientId`