axa-fr oidc-client puts PKCE sign-in and a token worker in one browser library

Three packages, and only one of them is normally installed

The package table at the top of the README is the clearest description of the project, and it explains the architecture better than any prose. There are three published packages. The @axa-fr/oidc-client package is for browser applications using any JavaScript framework, or no framework at all. The @axa-fr/react-oidc package provides React providers, protected components, authentication hooks and authenticated fetch, and the description notes it is compatible with NextJS and similar setups. The third package, @axa-fr/oidc-client-service-worker, is the worker used by both clients to isolate tokens and attach them to trusted requests. The documentation makes the relationship explicit: most applications install only one of the first two packages, the service worker is included as a dependency, and it does not replace the browser client. So the worker ships as a dependency of both clients, but the token isolation itself is optional: enabling it requires serving OidcServiceWorker.js and configuring OidcTrustedDomains.js, which installing the npm package alone does not do.

The flow is Authorization Code with PKCE, and no secret ever reaches the browser

The client creates a PKCE challenge, redirects the browser to the provider, and exchanges the returned authorization code for tokens. The setup instructions say to register a public browser client with your OIDC provider, enable the Authorization Code flow with PKCE, and register the exact callback and post-logout URLs. The instruction that follows is the important one for anyone who has done this before and is tempted to include a client secret: do not put a client secret in browser code. A public client has no secret precisely because the code that runs in a browser cannot keep one, and PKCE replaces the secret's role in binding the token request to the original authorization request. The configuration keys named in the quick start are the ones you set on the provider's side or in the client configuration: the authority, client_id, redirect_uri and scope. The provider must allow requests from your application origin to the endpoints the browser calls, including the token endpoint, and the documentation warns to request offline_access only when the provider and the client registration support refresh tokens.

Installation is one npm command, and the choice of package is the whole decision

The install step is short because the choice of package is the decision that matters:

   # Framework-independent applications
   npm install @axa-fr/oidc-client

   npm install @axa-fr/react-oidc

After that you follow the vanilla JavaScript quick start or the React quick start depending on which package you installed. The package names carry the @axa-fr scope, and the npm badges in the README point at both @axa-fr/oidc-client and @axa-fr/react-oidc, so the two are released in step with each other. The repository is a pnpm workspace with a packages/ directory and an examples/ directory holding a nextjs-demo, an oidc-client-demo and a react-oidc-demo, and the root package.json pins the package manager to [email protected] with node engines of 22.22.2, 24.15.0 or 26 and above. There are also hosted demos for both the React and the vanilla JavaScript clients, described as learning environments rather than production examples.

The service worker mode keeps real tokens out of application code

In service-worker mode, the worker intercepts the token exchange and authenticated API requests, and the sequence diagram in the README lays out the whole flow. The application sends an authorization request with a PKCE challenge, the provider authenticates the user and asks for consent, then redirects to the callback with an authorization code. The application then hands that code to the worker, which performs the token request and returns token metadata and secured placeholders to the application, and when the application later calls a configured trusted API, the worker attaches the access token to that request itself. With the default token-hiding settings, the real access and refresh tokens stay in the worker and the application only ever sees placeholders. Without the worker, the client manages tokens in browser storage and an authenticated fetch wrapper adds the access token to API requests. That fallback exists, and the documentation makes you decide about it explicitly, with service_worker_only: true to require the worker, and a warning that browser storage is accessible to same-origin JavaScript.

Token isolation is not a defence against XSS, and the documentation says so

This is the part of the documentation that deserves to be read before anything else, because the service worker can look like a security boundary and it is not one. The security section states plainly that service-worker isolation is not an XSS or CSRF prevention mechanism, and that malicious code running in the application can still make requests on the user's behalf. The advice that follows is standard but worth repeating in this context: apply a restrictive Content Security Policy and normal input and output protections. The rest of the section is about deployment, and each item is a concrete configuration task. Use HTTPS in production, since service workers require a secure context, with localhost suitable for development. Restrict OidcTrustedDomains.js to the provider endpoints and API URLs that should receive tokens, and review those rules whenever you add an API. Keep OidcServiceWorker.js aligned with the installed library version using the copy command and postinstall instructions in the package guides. Configure the host to serve the application at the callback URLs, and if you enable silent sign-in, use a separate silent callback URL and account for browser restrictions on third-party cookies. And protect the APIs on the server, since a client-side route guard is not an authorization boundary.

Token renewal happens on its own, and the events tell you when it did not

Automatic token renewal is listed among the features, and observing it is done through subscribeEvents in the core client or onEvent in React. What the token synchronization events guide says about those events is the part an integrator should read. An _end event can also report session loss or deferred renewal, and it does not guarantee that tokens were refreshed. That is a useful piece of honesty, because a naive implementation treats the end of a renewal cycle as success. The named configurations feature also matters for real applications, since it lets you hold several provider or scope configurations in one client rather than juggling separate instances, which is the situation in a multi-tenant product or an app that talks to more than one identity provider. The library also supports DPoP, under RFC 9449, and Pushed Authorization Requests where the authorization server supports it, both of which are the modern additions to the browser flow rather than legacy leftovers.

Seven major versions and five migration guides in the repository root

The version history explains the shape of the repository. The root holds MIGRATION_GUIDE_V3_TO_V4.md, MIGRATION_GUIDE_V3_TO_V5.md, MIGRATION_GUIDE_V4_TO_V5.md, MIGRATION_GUIDE_V5_TO_V6.md and MIGRATION_GUIDE_V6_TO_V7.md, five separate documents, and the release tags are v7.29.8 from 2026-10-15, v7.29.7 from 2026-10-13 and v7.29.6 from 2026-09-20. The repository is not archived and the last push was on 2026-10-15, so the library is being worked on at a rate that produces a patch release every few days at times. That cadence is the practical cost of this library: the major version has moved from 3 to 7, and a consumer on an older major is reading a document that describes a different API. The licence is MIT, held in the LICENSE file at the root, and the repository also carries a SECURITY.md for reporting vulnerabilities, a CODE_OF_CONDUCT.md, a FAQ.md with deployment and security considerations, an AGENTS.md and issue and pull request templates. The topics list mentions redux and context-api, so both state management approaches have been used with it.

Where this OIDC client is the wrong choice

Three situations argue against it. The first is a server-side application. The library is explicitly for browser applications, and the instructions are to register a public browser client and never put a client secret in browser code, so a confidential client running the Authorization Code flow on a server needs a different library entirely, one that can hold a secret. The second is an environment that cannot serve a service worker. Service workers require a secure context and a same-origin script, and a deployment that serves the application from a different origin than its assets, or that does not control the callback host, cannot use the token isolation mode that is the point of this library. The third is a team that wants a full identity provider rather than a client. This package handles the browser side of a login and nothing about user management, password policies, federation or session lifecycle on the server, so an application that also owns its user directory needs something else. The realistic alternative for the same job is another browser OIDC library with the same shape, and the practical difference between them comes down to whether the service worker isolation is implemented the way you want and whether the release cadence matches your appetite for upgrading.

Editorial conclusion

Adopt @axa-fr/oidc-client when you are building a browser application that needs OpenID Connect sign-in, want the Authorization Code flow with PKCE, and can serve a service worker and keep the trusted domain list under review. Skip it if your application is not a browser application, or if you need identity code flow with a confidential client, since the instructions are to register a public browser client and never put a client secret in browser code. Verify first that your provider allows requests from your origin to the token endpoint and that it supports refresh tokens before requesting offline_access.

Frequently asked questions

Official sources

1. AxaFrance/oidc-client on GitHub
2. Issues
3. License: MIT
4. README
5. Releases