@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
• 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
• 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"
  },

More documentation :

• @axa-fr/oidc-client

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"
  },

More documentation :

• @axa-fr/react-oidc

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 :

• French : Augmentez la sécurité et la simplicité de votre Système d’Information OpenID Connect
• English : Increase the security and simplicity of your information system with OpenID Connect
• English: youtube react-oidc introduction
• French: youtube react-oidc introduction

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

Contribute

• How to run the solution and to contribute
• Please respect our code of conduct