🔌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: 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)
};

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 should consider using 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):

GitHub - InseeFrLab/vite-insee-starter: A template project for SPAsGitHub

The backend (Node TODO App REST API):

GitHub - InseeFrLab/todo-rest-api: Todo app rest API with OIDC and OpenGraphGitHub

PreviousBasic Usage NextAuto Logout