OIDC Client
Add OpenID Connect (OIDC) sign-in to browser applications using the OAuth 2.0
Authorization Code flow with PKCE. Use the framework-independent client directly,
or the React components and hooks.
Choose a package
Most applications install only one of the first two packages. The service worker
is included as a dependency; it does not replace the browser client.
Features include automatic token renewal, named configurations for multiple
providers or scopes, optional service-worker token isolation, and support for
DPoP and
Pushed Authorization Requests (PAR)
when supported by your authorization server.
Getting started
-
Register a public browser client with your OIDC provider. Enable the
Authorization Code flow with PKCE and register your exact callback and
post-logout URLs. Do not put a client secret in browser code.
-
Install the package for your application:
# Framework-independent applications
npm install @axa-fr/oidc-client
# React applications — choose this instead
npm install @axa-fr/react-oidc
-
Follow the vanilla JavaScript quick start
or the React quick start.
Set your provider's authority, client_id, redirect_uri, and scope.
-
Choose whether to use the service worker. Its setup requires serving
OidcServiceWorker.js and configuring OidcTrustedDomains.js; installing the
npm package alone is not sufficient.
Your provider must allow requests from your application origin to the endpoints
the browser calls, including the token endpoint. Request offline_access only
when your provider and client registration support refresh tokens.
How it works
The client creates a PKCE challenge, redirects the browser to the provider, and
exchanges the returned authorization code for tokens. In service-worker mode,
the worker intercepts the token exchange and authenticated API requests:
sequenceDiagram
actor User
participant App as Browser application
participant Worker as OIDC service worker
participant Provider as OIDC provider
participant API as Trusted API
User->>App: Select sign in
App->>Provider: Authorization request with PKCE challenge
Provider->>User: Authenticate and request consent
Provider-->>App: Redirect to callback with authorization code
App->>Worker: Exchange code with PKCE verifier
Worker->>Provider: Token request
Provider-->>Worker: Tokens
Worker-->>App: Token metadata and secured placeholders
App->>Worker: Request to a configured trusted API
Worker->>API: Request with access token
API-->>App: API response
With the default token-hiding settings, the real access and refresh tokens stay
in the worker; the application receives placeholders instead. Without the worker,
the client manages tokens in browser storage and the authenticated fetch wrapper
adds the access token to API requests.
Observe renewal checks through subscribeEvents in the core client or onEvent
in React. The token synchronization events guide
explains their payloads and timing: an _end event can also report session loss
or deferred renewal, and does not guarantee that tokens were refreshed.
Security and deployment
- Service-worker isolation is not an XSS or CSRF prevention mechanism. Malicious
code running in the application can still make requests on the user's behalf.
Apply a restrictive Content Security Policy and normal input/output protections.
- Use HTTPS in production. Service workers require a secure context; localhost
is suitable for development.
- Restrict
OidcTrustedDomains.js to the provider endpoints and API URLs that
should receive tokens. Review these 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.
- Decide explicitly whether to permit fallback to browser storage or require the
worker with
service_worker_only: true. Browser storage is accessible to
same-origin JavaScript.
- Configure your host to serve the application at callback URLs. If you enable
silent sign-in, use a separate silent callback URL and account for browser
restrictions on third-party cookies.
- Protect APIs on the server: a client-side route guard is not an authorization
boundary.
See the FAQ for deployment and security considerations.
Run the demos
Try the hosted React demo or
vanilla JavaScript demo.
These are learning environments, not production security templates.
To run locally, use a Node.js version supported by the root
package.json and its pinned pnpm version. From the repository
root:
corepack enable
pnpm install --frozen-lockfile
pnpm build
Then choose one command, also from the repository root:
For Vite, open the URL printed in the terminal (normally http://localhost:5173;
another port is used if it is busy). The Next.js demo uses http://localhost:3001.
Register the actual origin and callback URLs with your provider before testing
sign-in. The demos use an external provider whose availability and registrations
are outside this repository's control.
FAQ
Start with the FAQ for common integration questions, then consult the
package guides for configuration and error handling. To report a problem, open an
issue with a minimal reproduction,
browser and package versions, and sanitized configuration. Never include tokens
or credentials.
Migrations
Contribute
Read the contribution guide and
code of conduct. The workspace contains the client, React
bindings, service worker, and demo applications.
Dependency updates must include the affected workspace manifests and
pnpm-lock.yaml. Keep Vitest and @vitest/coverage-v8 on matching versions.
MSW remains on version 2 because Vitest's mocker requires that major version.
GitHub Actions installs Node.js before pnpm. The Node setup steps disable
automatic package-manager caching (package-manager-cache: false) so they do
not try to invoke pnpm before it is installed.
pnpm lint-fix
pnpm lint
pnpm test:ci
pnpm build
