@axa-fr/oidc-client

About
Getting Started
Run The Demos
How It Works
Packages
- @axa-fr/oidc-client
- @axa-fr/react-oidc
- @axa-fr/svelte-oidc : we are looking for contributor
- @axa-fr/vue-oidc : we are looking for contributor
- @axa-fr/angular-oidc : we are looking for contributor
FAQ
Migrations
Contribute

About

@axa-fr/oidc-client the lightest and securest library to manage authentication with OpenID Connect (OIDC) and OAuth2 protocol. It is compatible with all OIDC providers. @axa-fr/oidc-client is a pure javascript library. It works with any JavaScript framework or library. @axa-fr/react-oidc is for React (compatible next.js, etc.), we expect soon to provide one for Vue, Angular and Svelte.

Demos:

Try the react demo at https://black-rock-0dc6b0d03.1.azurestaticapps.net/ (most advanced)
Try the pure javascript demo at https://icy-glacier-004ab4303.2.azurestaticapps.net/

@axa-fr/oidc-client is:

Secure :
- With Demonstrating Proof of Possession (DPoP), your access_token and refresh_token are not usable outside your browser context (big protection)
- With the use of Service Worker, your tokens (refresh_token and/or access_token) are not accessible to the JavaScript client code (if you follow good practices from FAQ section)
- OIDC using client side Code Credential Grant with pkce only
Lightweight : Unpacked Size on npm is 274 kB, Minified 61.1kB, Minified+GZIPPED 16.8kB Pkg stats via Bundlephobia.com
Simple
- refresh_token and access_token are auto refreshed in background
- with the use of the Service Worker, you do not need to inject the access_token in every fetch, you have only to configure OidcTrustedDomains.js file
Multiple Authentication :
- You can authenticate many times to the same provider with different scope (for example you can acquire a new 'payment' scope for a payment)
- You can authenticate to multiple different providers inside the same SPA (single page application) website
Flexible :
- Work with Service Worker (more secure) and without for older browser (less secure).
- You can disable Service Worker if you want (but less secure) and just use SessionStorage or LocalStorage mode.

Works perfectly well with:

Auth0
Duende Identity Server
Identity Server 4
Azure AD
Google
AWS
Keycloak
etc., all OIDC providers

Getting Started

Getting Started with @axa-fr/oidc-client

npm install @axa-fr/oidc-client --save

# To install or update OidcServiceWorker.js file, you can run
node ./node_modules/@axa-fr/oidc-client/bin/copy-service-worker-files.mjs public

# If you have a "public" folder, the 2 files will be created :
# ./public/OidcServiceWorker.js <-- will be updated at each "npm install"
# ./public/OidcTrustedDomains.js <-- won't be updated if already exist

Warning

If you use Service Worker mode, the OidcServiceWorker.js file should always be up to date with the version of the library. You may setup a postinstall script in your package.json file to update it at each npm install. For example :

  "scripts": {
    ...
    "postinstall": "node ./node_modules/@axa-fr/oidc-client/bin/copy-service-worker-files.mjs public"
  },

Getting Started with @axa-fr/react-oidc

npm install @axa-fr/react-oidc --save

# To install or update OidcServiceWorker.js file, you can run
node ./node_modules/@axa-fr/react-oidc/bin/copy-service-worker-files.mjs public

# If you have a "public" folder, the 2 files will be created :
# ./public/OidcServiceWorker.js <-- will be updated at each "npm install"
# ./public/OidcTrustedDomains.js <-- won't be updated if already exist

Warning

If you use Service Worker mode, the OidcServiceWorker.js file should always be up-to-date with the version of the library. You may setup a postinstall script in your package.json file to update it at each npm install. For example :

  "scripts": {
    ...
    "postinstall": "node ./node_modules/@axa-fr/react-oidc/bin/copy-service-worker-files.mjs public"
  },

Run The Demos

git clone https://github.com/AxaFrance/oidc-client.git

cd oidc-client
pnpm install

# oidc client demo
cd examples/oidc-client-demo
pnpm install
pnpm start
# then navigate to http://localhost:5174

# react vite demo
cd examples/react-oidc-demo
pnpm install
pnpm start
# then navigate to http://localhost:4200

# react NextJS demo
cd examples/nextjs-demo
pnpm install
pnpm run dev
# then navigate to http://localhost:3001

How It Works

The service worker catch access_token and refresh_token that will never be accessible to the client.

These components encapsulate the use of "@axa-fr/oidc-client" in order to hide workflow complexity. Internally for "@axa-fr/react-oidc", native History API is used to be router library agnostic.

More information about OIDC :

FAQ

Frequented Asked Question FAQ

Migrations

Migrating from v3 to v4 guide
Migrating from v3 to v5 guide
Migrating from v4 to v5 guide
Migrating from v5 to v6 guide
Migrating from v6 to v7 guide

ozanmanav/oidc-client