Skip to content

Latest commit

 

History

History
183 lines (138 loc) · 8.42 KB

README.md

File metadata and controls

183 lines (138 loc) · 8.42 KB
Raw

@axa-fr/oidc-client

Continuous Integration Quality Gate Reliability Security Code Coverage Twitter

Sample React Oicd

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:

@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:

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 :

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:

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

Schema Authorization Code Grant with pcke flow on the using service worker
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

Contribute