FusionAuth React SDK
Overview
This SDK allows you to add login, logout, and registration buttons to your React application. You can do this via pre-built buttons, hooks, or higher-order components.
Your users will be sent to FusionAuth’s themeable hosted login pages and then log in. After that, they are sent back to your React application.
Once authentication succeeds, the following secure, HTTP-only cookies will be set:
app.at
- an OAuth Access Tokenapp.rt
- a Refresh Token used to obtain a newapp.at
. This cookie will only be set if refresh tokens are enabled on your FusionAuth instance.
The access token can be presented to APIs to authorize the request and the refresh token can be used to get a new access token.
Note that this SDK requires you to have a server that performs the OAuth token exchange. See Server Code Requirements for more details.
You can use this library against any version of FusionAuth or any OIDC compliant identity server.
Getting Started
Installation
NPM:
npm install @fusionauth/react-sdk
Yarn:
yarn add @fusionauth/react-sdk
Configuring Provider
To configure the SDK, wrap your app with FusionAuthProvider
:
import React from 'react';
import { createRoot } from 'react-dom/client';
import { FusionAuthProvider } from '@fusionauth/react-sdk';
import App from './App';
const container = document.getElementById('root');
const root = createRoot(container!);
root.render(
<FusionAuthProvider
clientID="" // Your FusionAuth client ID
serverUrl="" // The base URL of your server for the token exchange
redirectUri="" // The URI that the user is directed to after the login/register/logout action
>
<App />
</FusionAuthProvider>
);
Server Code Requirements
Authenticating with FusionAuth requires you to set up a server that will be used to perform the OAuth token exchange. This server must have the following endpoints:
GET /app/login
This endpoint must:
- Generate PKCE code. a. The code verifier should be saved in a secure HTTP-only cookie. b. The code challenge is passed along
- Encode and save
redirect_url
from react app tostate
. - Redirect browser to
/oauth2/authorize
with aredirect_uri
to/app/token-exchange
GET /app/callback
This endpoint must:
Call /oauth2/token to complete the Authorization Code Grant request. The
code
comes from the request query parameter andcode_verifier
should be available in the secure HTTP-only cookie, while the rest of the parameters should be set/configured on the server side.Once the token exchange succeeds, read the
app.at
from the response body and set it as a secure, HTTP-only cookie with the same name.If you wish to support refresh tokens, repeat step 2 for the
app.rt
cookie.Save the expiration time in a readable
app.at_exp
cookie. And save theapp.idt
id token in a readable cookie.Redirect browser back to encoded url saved in
state
.Call /oauth2/userinfo to retrieve the user info object and respond back to the client with this object.
GET /app/register
This endpoint is similar to /login
. It must:
- Generate PKCE code. a. The code verifier should be saved in a secure HTTP-only cookie. b. The code challenge is passed along
- Encode and save
redirect_url
from react app tostate
. - Redirect browser to
/oauth2/register
with aredirect_uri
to/app/callback
GET /app/me
This endpoint must:
- Use
app.at
from cookie and use as the Bearer token to call/oauth2/userinfo
- Return json data
GET /app/logout
This endpoint must:
- Clear the
app.at
andapp.rt
secure, HTTP-only cookies. - Clear the
app.at_exp
andapp.idt
secure cookies. - Redirect to
/oauth2/logout
POST /app/token-refresh
(optional)
This endpoint is necessary if you wish to use refresh tokens. This endpoint must:
Call /oauth2/token to get a new
app.at
andapp.rt
.Update the
app.at
,app.at_exp
,app.idt
, andapp.rt
cookies from the response.
Usage
Pre-built buttons
There are three pre-styled buttons that are configured to perform login/logout/registration. They can be placed anywhere in your app as is.
import {
FusionAuthLoginButton,
FusionAuthLogoutButton,
FusionAuthRegisterButton
} from '@fusionauth/react-sdk';
export const LoginPage = () => (
<>
<h1>Welcome, please log in or register</h1>
<FusionAuthLoginButton />
<FusionAuthRegisterButton />
</>
);
export const AccountPage = () => (
<>
<h1>Hello, user!</h1>
<FusionAuthLogoutButton />
</>
);
Programmatic usage
Alternatively, you may interact with the SDK programmatically using the
useFusionAuth
hook or withFusionAuth
HOC.
useFusionAuth
Use the useFusionAuth
hook with your functional components to get
access to the properties exposed by
FusionAuthContext:
import React from 'react';
import { useFusionAuth } from '@fusionauth/react-sdk';
const App = () => {
const { login, logout, register, isAuthenticated } = useFusionAuth();
return isAuthenticated ? (
<div>
<span>Hello, user!</span>
<button onClick={() => logout()}>Logout</button>
</div>
) : (
<div>
<button onClick={() => login()}>Log in</button>
<button onClick={() => register()}>Register</button>
</div>
);
};
See useFusionAuth for more details.
withFusionAuth
The withFusionAuth
higher-order component can be used to wrap your
components and give them access to a fusionAuth
prop which contains
all the properties exposed by the FusionAuthContext
. This works with
both functional and class components:
Functional Component
import React from 'react';
import { withFusionAuth, WithFusionAuthProps } from '@fusionauth/react-sdk';
const LogoutButton: React.FC<WithFusionAuthProps> = props => {
const { logout } = props.fusionAuth;
return <button onClick={() => logout()}>Logout</button>;
}
export default withFusionAuth(LogoutButton);
Class Component
import React, { Component } from 'react';
import { withFusionAuth, WithFusionAuthProps } from '@fusionauth/react-sdk';
class LogoutButton extends Component<WithFusionAuthProps> {
render() {
const { logout } = this.props.fusionAuth;
return <button onClick={() => logout()}>Logout</button>;
}
}
export default withFusionAuth(LogoutButton);
See withFusionAuth for more details.
State parameter
The login
and register
functions both accept an optional string
parameter called state
. The state that is passed in to the function
call will be passed back to the onRedirectSuccess
handler on your
FusionAuthProvider
. Though you may pass any value you would like for
the state parameter, it is often used to indicate which page the user
was on before redirecting to login or registration, so that the user can
be returned to that location after a successful authentication.
Protecting Content
The RequireAuth
component can be used to protect information from
unauthorized users. It takes an optional prop withRole
that can be
used to ensure the user has a specific role. If an array of roles is
passed, the user must have at least one of the roles to be authorized.
import { RequireAuth, useFusionAuth } from '@fusionauth/react-sdk';
const UserNameDisplay = () => {
const { user } = useFusionAuth();
return (
<RequireAuth>
<p>User: {user.name}</p> // Only displays if user is authenticated
</RequireAuth>
);
};
const AdminPanel = () => (
<RequireAuth withRole="admin">
<button>Delete User</button> // Only displays if user is authenticated and has 'admin' role
</RequireAuth>
);
Known Issues
Token exchange endpoint being called repeatedly
If you see the token exchange endpoint being called multiple times, this
is due to a dev time setting in React 18. When running using
StrictMode
in development mode, React 18 will mount, unmount, and
remount all components in this mode, which results in the network call
running twice.
This will not happen in a production build or if StrictMode
is
disabled.
If you remove the React.StrictMode
tags in index.tsx
of the example
app, the call is only made once.
Example App
See the FusionAuth React SDK Example for functional example of a React client that utilizes the SDK as well as an Express server that performs the token exchange.