Quickstart

This guide walks through adding OIDC authentication to your app using any spec-compliant OIDC provider (like Autentico, Auth0, or Keycloak).

1. Install your framework adapter

   npm install oidc-js-react  # or oidc-js-vue, oidc-js-svelte, oidc-js-angular, etc.

2. Add authentication

   You’ll need an issuer URL, client ID, and redirect URI from your OIDC provider.

   React

   import { AuthProvider, RequireAuth, useAuth } from "oidc-js-react";
   
   const config = {
     issuer: "https://auth.example.com",
     clientId: "my-app",
     redirectUri: "http://localhost:5173/callback",
     scopes: ["openid", "profile", "email", "offline_access"],
   };
   
   function App() {
     return (
       <AuthProvider config={config}>
         <RequireAuth fallback={<p>Loading...</p>}>
           <Dashboard />
         </RequireAuth>
       </AuthProvider>
     );
   }
   
   function Dashboard() {
     const { user, actions } = useAuth();
     return (
       <div>
         <p>Welcome, {user?.profile?.name}!</p>
         <button onClick={() => actions.logout()}>Log out</button>
       </div>
     );
   }

   Vue

   // main.ts — register the plugin
   import { oidcPlugin } from "oidc-js-vue";
   
   app.use(oidcPlugin, {
     config: {
       issuer: "https://auth.example.com",
       clientId: "my-app",
       redirectUri: "http://localhost:5173/callback",
       scopes: ["openid", "profile", "email", "offline_access"],
     },
   });

   <!-- Dashboard.vue — protect and access auth state -->
   <script setup lang="ts">
   import { RequireAuth, useAuth } from "oidc-js-vue";
   const { user, actions } = useAuth();
   </script>
   
   <template>
     <RequireAuth>
       <template #fallback><p>Loading...</p></template>
       <p>Welcome, {{ user?.profile?.name }}!</p>
       <button @click="actions.logout()">Log out</button>
     </RequireAuth>
   </template>

   Svelte

   <!-- App.svelte -->
   <script lang="ts">
     import { AuthProvider, RequireAuth } from "oidc-js-svelte";
   
     const config = {
       issuer: "https://auth.example.com",
       clientId: "my-app",
       redirectUri: "http://localhost:5173/callback",
       scopes: ["openid", "profile", "email", "offline_access"],
     };
   </script>
   
   <AuthProvider {config}>
     {#snippet children()}
       <RequireAuth>
         {#snippet children()}
           <Dashboard />
         {/snippet}
         {#snippet fallback()}
           <p>Loading...</p>
         {/snippet}
       </RequireAuth>
     {/snippet}
   </AuthProvider>

   <!-- Dashboard.svelte — access auth state -->
   <script lang="ts">
     import { getAuthContext } from "oidc-js-svelte";
     const auth = getAuthContext();
   </script>
   
   <p>Welcome, {auth.user?.profile?.name}!</p>
   <button onclick={() => auth.actions.logout()}>Log out</button>

   Angular

   // app.config.ts — provide auth and protect routes
   import { provideAuth, authGuard } from "oidc-js-angular";
   
   export const appConfig = {
     providers: [
       provideRouter([
         {
           path: "dashboard",
           component: DashboardComponent,
           canActivate: [authGuard],
         },
       ]),
       provideAuth({
         config: {
           issuer: "https://auth.example.com",
           clientId: "my-app",
           redirectUri: "http://localhost:5173/callback",
           scopes: ["openid", "profile", "email", "offline_access"],
         },
       }),
     ],
   };

   // dashboard.component.ts — access auth state
   import { Component, inject } from "@angular/core";
   import { AuthService } from "oidc-js-angular";
   
   @Component({
     selector: "app-dashboard",
     template: `
       <p>Welcome, {{ auth.user()?.profile?.name }}!</p>
       <button (click)="auth.logout()">Log out</button>
     `,
   })
   export class DashboardComponent {
     readonly auth = inject(AuthService);
   }

   Solid

   import { AuthProvider, RequireAuth, useAuth } from "oidc-js-solid";
   
   const config = {
     issuer: "https://auth.example.com",
     clientId: "my-app",
     redirectUri: "http://localhost:5173/callback",
     scopes: ["openid", "profile", "email", "offline_access"],
   };
   
   function App() {
     return (
       <AuthProvider config={config}>
         <RequireAuth fallback={<p>Loading...</p>}>
           <Dashboard />
         </RequireAuth>
       </AuthProvider>
     );
   }
   
   function Dashboard() {
     const auth = useAuth();
     return (
       <div>
         <p>Welcome, {auth.user?.profile?.name}!</p>
         <button onClick={() => auth.actions.logout()}>Log out</button>
       </div>
     );
   }

   Preact

   import { AuthProvider, RequireAuth, useAuth } from "oidc-js-preact";
   
   const config = {
     issuer: "https://auth.example.com",
     clientId: "my-app",
     redirectUri: "http://localhost:5173/callback",
     scopes: ["openid", "profile", "email", "offline_access"],
   };
   
   function App() {
     return (
       <AuthProvider config={config}>
         <RequireAuth fallback={<p>Loading...</p>}>
           <Dashboard />
         </RequireAuth>
       </AuthProvider>
     );
   }
   
   function Dashboard() {
     const { user, actions } = useAuth();
     return (
       <div>
         <p>Welcome, {user?.profile?.name}!</p>
         <button onClick={() => actions.logout()}>Log out</button>
       </div>
     );
   }

   Lit

   import { LitElement, html } from "lit";
   import { customElement } from "lit/decorators.js";
   import { AuthController, RequireAuthController } from "oidc-js-lit";
   
   @customElement("app-root")
   export class AppRoot extends LitElement {
     auth = new AuthController(this, {
       config: {
         issuer: "https://auth.example.com",
         clientId: "my-app",
         redirectUri: "http://localhost:5173/callback",
         scopes: ["openid", "profile", "email", "offline_access"],
       },
     });
     guard = new RequireAuthController(this, { auth: this.auth });
   
     render() {
       if (!this.guard.authorized) return html`<p>Loading...</p>`;
       const { user } = this.auth;
       return html`
         <p>Welcome, ${user?.profile?.name}!</p>
         <button @click=${() => this.auth.logout()}>Log out</button>
       `;
     }
   }

   Kasper

   <template>
     <auth-provider @:config="config">
       <require-auth>
         <p>Welcome, {{auth.user.value?.profile?.name}}!</p>
         <button @on:click="auth.actions.logout()">Log out</button>
       </require-auth>
     </auth-provider>
   </template>
   
   <script>
   import { Component } from "kasper-js";
   import { useAuth } from "oidc-js-kasper";
   
   export class App extends Component {
     config = {
       issuer: "https://auth.example.com",
       clientId: "my-app",
       redirectUri: "http://localhost:5173/callback",
       scopes: ["openid", "profile", "email", "offline_access"],
     };
     auth = useAuth();
   }
   </script>

Tip

Include offline_access in your scopes to receive a refresh token. Without it, the user’s session ends when the access token expires.

Note

The redirectUri doesn’t require a dedicated route. The auth provider detects the code and state query parameters on any page and completes the token exchange automatically. You can point it at your app’s root or a specific /callback path — either works.

What happens under the hood

1. The auth provider fetches the OIDC discovery document from {issuer}/.well-known/openid-configuration
2. When login is triggered, it generates PKCE parameters, saves auth state to sessionStorage, and redirects to the IdP’s authorization endpoint
3. After the user authenticates, the IdP redirects back with an authorization code
4. The provider detects the code in the URL, exchanges it for tokens, fetches the user profile, and cleans up the URL
5. The auth guard (RequireAuth / authGuard) checks token expiry and automatically refreshes expired tokens using the refresh token