Getting Started with FusionAuth: A Beginner's Guide

Do you care about authentication, authorization and user management?

Sure, you know your application needs it, but do you really want to spend time building undifferentiated functionality like social login, multi-factor authentication, or password reset? By using FusionAuth for authentication, authorization and user management, you get these benefits:

• pre-built authentication workflows and integrations accelerate application delivery
• secure storage of user credentials and profile data, wherever you want (you host or we host)
• new functionality and bugfixes from the security experts on the FusionAuth team, available to your users when you upgrade
• the same experience and application whether you develop locally, use FusionAuth in your CI/CD system, or run it in prod
• fine grained control of the version of FusionAuth you use; upgrades happen on your schedule, not ours

The sections in this guide are as follows:

• FusionAuth Overview
• Prerequisites for following this guide
• Launch FusionAuth to get your FusionAuth server up and running
• Delegate Authentication where you will work with the FusionAuth UI to delegate authentication for your application.
• Add Functionality to add magic link authentication flow to your application.
• Cleaning Up
• Summing Up

Ready? Great! Let’s get started.

Overview of Using FusionAuth

To get started with FusionAuth, you need to do three things:

• Launch FusionAuth
• Delegate authentication to FusionAuth
• Add functionality to your application (optional, but common)

For this guide, you will launch FusionAuth and delegate authentication, and then we will walk through an example where you’ll add Login With a Magic Link functionality to an application, with no code changes required.

Prerequisites

• git
• a web browser
• one of:
  • Docker (if you follow the Docker instructions) or
  • a GitHub account (if you follow the GitPod instructions)
• Docker also requires an installed version of node (this was tested with v20.16.0, but should work with any modern node version).

Launch FusionAuth

FusionAuth is downloadable software; you can run it locally, on your cloud VM, in a container, or on FusionAuth Cloud.

For this guide, you can either:

• Use Docker to install and run FusionAuth and the application in containers on your own server
• Use GitPod to run FusionAuth in the cloud in your GitPod account—no software install required

Click on the arrow next to Docker or GitPod below to see the instructions to get started.

docker -v

Docker version 27.3.1, build ce12230

git clone https://github.com/FusionAuth/fusionauth-example-express-start-here/ && \
cd fusionauth-example-express-start-here

docker compose up -d

GitPod

GitPod Registration

Note that the first time you start a GitPod workspace you will need to answer some demographic questions, but after that it will run without interruption.

Click on the GitPod button below to start up your environment. It will take a few minutes to bring up the servers, so please be patient until the login page loads into the environment.

The GitPod environment will spin up Docker containers with a FusionAuth instance, any dependencies, a terminal and an editor.

Here you are using a bootstrapping feature of FusionAuth called Kickstart. When FusionAuth comes up for the first time, it will look at the kickstart/kickstart.json file and configure FusionAuth to your specified state.

After the servers start up, you will be presented with a login screen in the GitPod 'Simple Browser', as well other parts of the GitPod environment.

FusionAuth will be initially configured with these settings:

• Your example username is richard@example.com and the password is password.
• Your admin username is admin@example.com and the password is password.
• The base URL of FusionAuth is based on your GitPod environment.

Summing Up

To verify that your system is set up, paste the below code into your GitPod terminal. When prompted, log in using the admin credentials (admin@example.com with the password password). You will see the FusionAuth admin UI.

tip

When you first copy and paste something in the GitPod environment, you may be presented with a popup asking for permission. Look out for that, and accept it to be able to paste commands into the environment.

startadmin

Congratulations! You've got your own FusionAuth instance running in the GitPod cloud.

What Did You Just Do?

You launched a FusionAuth instance with either Docker or GitPod. It was prepopulated with application data. There are two users configured, one with admin access and one with access to the sample application.

Delegate Authentication

What we will cover in this section:

• Find the Application Configuration in the FusionAuth Admin UI
• Review the Application Configuration to check the redirect URL and other settings
• Log out of the Admin UI
• View Application Delegation Code Excerpts to explore how the Node.js application interacts with FusionAuth
• Start Up and Log In to the Application to fire up the Start Here application in your environment

Once you have FusionAuth up and running, you need to set up your application or applications to delegate to FusionAuth.

For this guide, there’s an example Start Here App application which is already set up for you, which has been written to use FusionAuth for authentication. This application is maintained by Start Here, a leading provider of services to convert bills to coins and vice versa.

Below is a diagram showing the delegation process. Click on View Delegation Diagram to view.

Let’s look at that configuration, check out some code, and then start the application up so you can log in.

Find The Application Configuration In The FusionAuth Admin UI

In the previous step, you logged in to the system as an admin user. Now you are going to find the application configuration.

• Go back to that browser screen, which should be showing the admin UI dashboard, a rainbow of sections showing information about the server.
• Navigate to Applications in the left-hand sidebar. You may need to use the hamburger icon at the top left of the screen to see all options.
• Choose Edit from the Actions dropdown in the Start Here App application line.

Review The Application Configuration

Let’s look at the configured Start Here App to check out the application settings.

The Redirect URL

After the user signs in using FusionAuth, they need to get back to your application. You configure each FusionAuth application configuration with redirect URLs to send the user back to.

In the application configuration you are looking at, you can review the pre-configured authorized redirect URLs.

Other Settings

You can also see other useful information, such as the Client Id, which tells FusionAuth which application configuration to use.

There are many other settings, but they are not important for this guide, so you can leave them all alone.

Log Out Of The Admin UI

Both the admin UI and the Start Here App are applications in FusionAuth. Users can have access to none, one or both.

In this tutorial, the admin@example.com user can access the admin UI and the richard@example.com can access the Start Here App. Later you’ll log in to the Start Here App, so now you need to log out of the admin UI.

Click the Logout button in the admin UI to log out from the admin user account. This is usually found at the top of the left hand navigation (you may need to click the hamburger menu to see it) but can sometimes be found at the top right corner of your window.

Application Delegation Code Excerpts

To understand how the Node.JS application delegates to FusionAuth, take a quick look at some of the Node.JS application code from the GitHub repository. You can either open it up in an editor or follow along here. If you are following the GitPod path, you can click the filename in the file browser in the left hand panel to see the file in your main window.

Requesting The User Authenticate

To send the user over to FusionAuth initially, you must craft a URL that includes the Client Id from the configuration you reviewed above, as well as other parameters needed to offer a secure authentication experience. After the URL is created, you can forward the user there any time they need to log in. Here’s the code that does that.

  res.redirect(302, `${fusionAuthURL}/oauth2/authorize?client_id=${clientId}&`+
    `scope=profile%20email%20openid&`+
    `response_type=code&`+
    `redirect_uri=${fusionAuthRedirectURL}/oauth-redirect&`+
    `state=${userSessionCookie?.stateValue}&`+
    `code_challenge=${userSessionCookie?.challenge}&`+
    `code_challenge_method=S256`)

Once the user authenticates, the redirect URL is retrieved by the browser with some additional parameters.

Finishing The User Authentication At The Redirect URL

The code running at the redirect URL needs to finish the authentication. It sends parameters from the login event to FusionAuth to do so. These include:

• the one-time use authorization code, which is tied to the authentication event (the authCode variable)
• a parameter to let FusionAuth know which application the authentication is for (the clientId variable)
• other parameters

FusionAuth examines the request parameters and, if they all are correct, sends a token to the Node.JS application. When the app receives these, the user is authenticated. The application can then let the user access data or functionality.

Here’s the code that completes the authentication.

    const accessToken = (await client.exchangeOAuthCodeForAccessTokenUsingPKCE(authCode,
      clientId,
      clientSecret,
      `${fusionAuthRedirectURL}/oauth-redirect`,
      userSessionCookie.verifier)).response;

    if (!accessToken.access_token) {
      console.error('Failed to get Access Token')
      return;
    }
    res.cookie(userToken, accessToken, { httpOnly: true })

Storing The Token

Once you have the token, what should the app do? One great option is to store it as a Secure, HTTPOnly cookie that the browser can then send back to other services. The above code does this using the res.cookie function.

Accessing Protected Pages

The application has certain pages that are protected, such as an account details page. The account page display code checks the user’s identity. The browser is redirected to the home page if there is no valid token. This code is below:

app.get("/account", async (req, res) => {
  const userTokenCookie = req.cookies[userToken];
  if (!await validateUser(userTokenCookie)) {
    res.redirect(302, '/');
  } else {
    res.sendFile(path.join(__dirname, '../templates/account.html'));
  }
});

You can check out how all the code and templates fit together by looking at code in the app directory.

Start Up And Log In To The Application

This section of the Delegate Authentication instructions is hands-on. You will start up the application and log in using a specific user.

http://localhost:9011/admin

startadmin

In your shell, type the following to start up the application:

cd app && npm install && npm run dev

This will start a server up. Next, navigate to the application. Click on the arrow next to Docker or GitPod to see the instructions.

http://localhost:8080/

starthere

Then, log in to the Node.JS application in the browser:

• Click on the Login button in the upper right hand corner.
• Authenticate using the email richard@example.com and the password password.

You may need to scroll down to see the Submit button.

You’ll then be logged to the application. From there you can view your account details or access other functionality.

What Did You Just Do?

High five! In this section, you:

• looked at FusionAuth configuration
• reviewed Node.JS application code relevant to the integration
• started the application
• logged in to the Start Here App application using FusionAuth

Add Functionality

By delegating authentication to FusionAuth, your application gets access to all kinds of authentication and authorization functionality, such as magic link login, multi-factor authentication (MFA), social sign-on, self-service registration and more. Getting these flows out of the box is a lot of the value of using FusionAuth.

Let’s add one piece of functionality to complete this tutorial. Let’s allow users to log in using magic links, where they get a link emailed to their inbox and can click on it to log in. Offering this login method reduces sign-in friction and user frustration.

Since you left the Node.JS application running, open another terminal window. In GitPod this can be done by clicking the ”+” on the right hand side of the terminal section of the window.

The Email Server

To add a Login With Magic Links button, you usually have to configure an email server and then the email templates that are sent. Never fear, for this guide, we’ve already set up the email server and configured the templates.

The email server is a locally running mock email server, and you can visit the inbox. Click on the arrow next to Docker or GitPod to see the instructions.

http://localhost:1080/

startemail

Enable Magic Links In FusionAuth

Log out of your application and log in to the Admin UI. Click on the arrow next to Docker or GitPod to see the instructions.

http://localhost:9011/admin

startadmin

Navigate to Applications and then edit the Start Here App application using the Actions select box, the same way you did above. Navigate to the Security tab and then scroll to the Passwordless login section. You may need to resize the window or horizontally scroll the tabs to see the Security tab.

Click the Enabled toggle.

Save your configuration change by clicking the blue disk icon.

Next, click the Logout button in the admin UI to log out from the admin user account. You’re going to log back into the Start Here App application with a magic link.

Get A Magic Link And Log In

Visit your application. To get to the application follow the instructions below. Click on the arrow next to Docker or GitPod to see the instructions.

http://localhost:8080/

starthere

Click the Login button.

Scroll down, if needed. You’ll see a Login with a magic link button.

Click on it and enter your user’s email address (richard@example.com) and click Send.

Now you can visit your email inbox and you’ll see your magic link email. Click on the arrow next to Docker or GitPod to see the instructions.

http://localhost:1080/

startemail

You should see something similar to:

Click on the link, and you’ll be logged into your application.

What Did You Just Do?

You enabled Magic Link login for your application without touching a single line of code.

Troubleshooting

If you receive an error message stating Your account has not been registered for this application, follow these steps:

• Log out of the admin UI.
• Log out of the Start Here App.
• Log in to whichever application you are trying to access with the correct user: admin@example.com for the admin UI, richard@example.com for the Start Here App.

Cleaning Up

If you used Docker, clean up by running docker compose down -v in the root directory. You can stop the Node.JS application by hitting Control-C in the terminal window where you are running it.

If you used GitPod, clean up by looking for the orange GitPod command palette button in the bottom left corner of the workspace, clicking on it, and then choosing Stop Workspace.

Summing Up

Congrats! You are all done with this tutorial.

In this tutorial, you’ve done the following:

• Started up your own FusionAuth instance using either Docker or GitPod.
• Examined code and configuration and started an example application.
• Extended the example application to allow login with an emailed link without writing any code.

Let’s talk about next steps.

Quickstarts

Looking for an example in a particular language? Quickstarts walk you through the Launch and Delegate steps, leaving you with a running application in your framework or language of choice, to which you can add functionality. If you have Docker installed and one of over 20 frameworks and languages, check out our quickstarts.

Each quickstart includes a complete runnable application and a shell application you can build out by following the step-by-step integration instructions.

More Functionality

Now that you know a bit about FusionAuth, if you are interested in learning more about the authentication related functionality it enables, there’s more documentation covering:

• how to set up other identity providers, including SAML, OIDC and Facebook
• other passwordless options including and passkeys
• enabling self-service registration to let users sign up for your application
• how to use multi-factor authentication (MFA); note that TOTP MFA is free and included in the Community plan, but all other MFA methods require a paid license
• Sign up for a trial FusionAuth Cloud instance which comes with a free Starter plan to explore MFA and other paid features