This repository contains example usage of the FusionAuth React SDK. It provides an example React client that uses the SDK, and an example Express server that is used to complete the OAuth token exchange.
If you'd rather use a hosted backend, with no need to use the Express server, please visit our React sample application with the hosted backend repo.
This example repo consists of two parts:
client
contains the React client application code which utilizes the FusionAuth React SDKserver
contains an Express server app which is used to securely perform the token exchange
The React client shows example usage of the SDK and integrates with React Router v6.
- Yarn: This will be needed for pulling down the various dependencies.
- NodeJS: This will be used in order to run the node server.
- FusionAuth: This is the auth server. Install in one of two ways:
- Docker: The quickest way to stand up FusionAuth.
- Install FusionAuth Manually.
You can do this one of two ways, using Docker and Kickstart or manually by logging into the FusionAuth administrative user interface.
If you run FusionAuth from a Docker container, in the root of this project directory (next to this README) are two files a Docker compose file and an environment variables configuration file. Assuming you have Docker installed on your machine, a docker-compose up
will bring FusionAuth up on your machine.
The FusionAuth configuration files also make use of a unique feature of FusionAuth, called Kickstart: when FusionAuth comes up for the first time, it will look at the Kickstart file and mimic API calls to configure FusionAuth for use. It will perform all the necessary setup to make this demo work correctly, but if you are curious as to what the setup would look like by hand, the "FusionAuth configuration (by hand)" section of this README describes it in detail.
For now, get FusionAuth in Docker up and running (via docker-compose up
) if it is not already running; to see, click here to verify it is up and running.
NOTE: If you ever want to reset the FusionAuth system, delete the volumes created by docker-compose by executing
docker-compose down -v
. FusionAuth will only apply the Kickstart settings when it is first run (e.g., it has no data configured for it yet).
If you are using Docker:
- Your client Id is:
e9fdb985-9173-4e01-9d73-ac2d60d1dc8e
- Your client secret is:
super-secret-secret-that-should-be-regenerated-for-production
- Your example username is
richard@example.com
and your password ispassword
. - Your admin username is
admin@example.com
and your password ispassword
. - Your fusionAuthBaseUrl is 'http://localhost:9011/'
You can log into the FusionAuth admin UI and look around if you want, but with Docker/Kickstart you don't need to.
You're all done with FusionAuth setup. Skip ahead to the Express Server Setup section.
Log into the FusionAuth admin UI.
Go to the Applications section.
- Create an Application using the green button.
- Give it a name
- On the OAuth tab:
- Make sure the authorization code grant is enabled
- Add the following to the authorized redirect URLs for your application:
http://localhost:3000
andhttp://localhost:9000/app/callback
- Add the following to the authorized request origins URLs for your application:
http://localhost:9000
- Add the following to the logout URL:
http://localhost:3000
- Click save.
- Edit the application again.
- Record the client Id and secret, you'll use that below.
-
On the registration tab, ensure self service registration is enabled.
-
Save the application again.
Go to the Users section.
- Create a user if needed.
Go to the Themes section, under Customization.
- Duplicate the FusionAuth theme.
- Provide a name, such as 'React theme'.
- Copy the contents of the file at
kickstart/css/styles.css
into thestyles
theme field. - Save the theme.
Go to the Tenants section.
- Edit the default tenant
- On the General tab, update the tenant theme to be your new theme; 'React theme' if you used that name.
- Save the tenant.
Go to the Settings -> System -> CORS
- Set enable cors true.
- Set allowed credentials true.
- Set allowed methods GET POST OPTIONS.
- Set allowed origins http://localhost:3000
FusionAuth is all set up. Proceed to the Express Server Setup section.
From the server
directory:
- Update
config.js
if you aren't using docker/kickstart - Run
yarn install
to install dependencies - Run
yarn start
to start the server at http://localhost:9000
From the client
directory:
- Update
src/config.ts
if you aren't using docker/kickstart - Run
yarn install
to install dependencies - Run
yarn start
to start your React app at http://localhost:3000
Visit the React app. You should be able to log in, log out and register a new user.
Three files in particular demonstrate the usage of the SDK. Check out the following:
client/src/FusionAuthProviderWithRedirectHandling.tsx
- custom redirect handling to integrate with React Routerclient/src/pages/LoginPage.tsx
- a simple login page that pulls loading/authentication state out of FusionAuth context viauseFusionAuth()
as well as the out-of-the-box Login and Register buttonsclient/src/pages/AccountPage.tsx
- a simple account page that- wraps page in
RequireAuth
component to protect information from unauthorized users. - pulls user state from the FusionAuth context via
useFusionAuth()
to display information about the authenticated user
- wraps page in
The server you configure to use with the React SDK must have a /token-exchange
endpoint to perform the exchange,
a /logout
endpoint to clear tokens, and optionally a /jwt-refresh
endpoint if you wish to use refresh tokens.
You can check out server/routes/token-exchange.js
, server/routes/logout.js
, and server/routes/jwt-refresh.js
to see how these endpoints are
implemented. (Note: the Known Issue of multiple requests made to token-exchange may return 503 responses. These can be ignored.)
At a high level:
token-exchange.js
calls out to the FusionAuth OAuth Token endpoint to get an access token and refresh token, which are both stored in secure cookiesjwt-refresh.js
calls out to the FusionAuth JWT Refresh endpoint to exchange the refresh token for a new access tokenlogout.js
clears the access token and refresh tokens
See the SDK Server Code Requirements for more detail.