Forem: FusionAuth

I Just Want Authentication To Work

FusionAuth — Wed, 22 Nov 2023 23:32:35 +0000

Originally posted by Alex Patterson @ FusionAuth.io

Authentication is the process of verifying the identity of a user or entity. It is a fundamental security measure that is used in a wide variety of applications, including web applications, mobile apps, and APIs. The thing is, as a developer with over 20 years of experience, I just don't care about figuring it out! I just want it to work!!

There are many different ways to implement authentication, but the most common approach is to use a username and password. Yep, just like back in 1960 when The Everly Brothers had one of the top songs out there, this method is still most popular today. Just as the Everly Brothers' time at the top of the charts has passed, so has the time for passwords. I don't want to hear about them anymore!

A more modern approach is to use a single sign-on (SSO) solution. SSO solutions allow users to log in to multiple applications using a single set of credentials. This can be convenient for users, as they do not have to remember multiple usernames and passwords. This method came about around the same time Eminem hit the billboard top 100 for the first time. SSO often has the problem of including the first login requirement of using a username and password to this day. Even Eminem made some changes and remains relevant!

My point is that authentication is an important security measure, but it can also be complex to implement. This is why we have been hanging on to these old methods for so long! When you are creating a new application (unless it is an authentication application), the last thing you care about is user login. There are many different authentication methods to choose from, and each method has its own advantages and disadvantages. Additionally, authentication needs to be implemented in a secure way to prevent attackers from gaining unauthorized access to applications.
But, again, all I care about is that my data is secure when creating the next Napster so everyone can share their 1990s music with me again!

The benefits of using an authentication service

There are many benefits to using an authentication service. Authentication services can help you:

Save time and money: Implementing and maintaining authentication can be time-consuming and expensive. authentication services can save you the hassle of having to implement and maintain your authentication system. s
Improve security: authentication services can help you to improve the security of your applications by using best practices and the latest security technologies keeping up to date with the latest security patches.
Reduce the risk of compliance violations: authentication services can help you meet compliance requirements by providing features such as two-factor authentication and user provisioning.

The last thing that I want is a call on Saturday night that someone hacked the password database that we built in-house two years ago and didn't maintain securely!

Choosing an authentication service

When choosing an authentication service, there are a few factors to consider:

Features: Consider the features that are important to you, such as two-factor authentication, user provisioning, and support for different authentication methods.
Pricing: authentication services can vary in price. Compare the pricing of different services to find the best deal for your needs.
Ease of use: Consider how easy the authentication service is to use. You want a service that is easy to set up and manage.
Hosting: Do you need flexibility to host your instance of an authentication Provider or have them host?
Integration support: Often you'll want to use an authentication service as a central user data store. You'll want to make sure you can integrate custom applications, off-the-shelf commercial software, and open-source solutions with it.

For Developers Who Just Want It To Work

If you are a developer who just wants authentication to work without implementing it yourself, there are a few things that you can do to make your life easier:

Use an authentication service. There are many different authentication services available, both free and paid. Authentication services can save you the hassle of having to implement and maintain your authentication system.
Use a framework or library that provides authentication functionality. There are many different frameworks and libraries available that provide authentication functionality. Using a framework or library can save you the time and effort of having to implement authentication yourself. If you are ready to get started check out our FusionAuth Quickstarts.
Consider that when Better Napster, wait I mean your app, starts to grow, you will want an authentication provider that can handle different devices and form factors such as mobile, desktop, and web clients.
Develop a local instance or self-contained environment that you can host yourself to make development easier.
Look to your favorite framework provider and see what they are using and use an authentication framework built for that.

What You Should Care About

Now that you have authentication figured out you can start to focus on the real requirements of building an application...

Picking the rest of your software components:

Framework - Remix, Next.js, SvelteKit, Pheonix Framework, Laravel, Flask, Angular
Database - PlanetScale, AlloyDB for PostgreSQL, AWS Aurora Serverless, CockroachDB Serverless, EdgeDB, Neon, Supabase, Timescale, Upstash, Grafbase, Turso, Fauna, Ably, Convex, Hasura, liveblocks
Hosting - Vercel, Netlify, Fly.io, Cloudflare
CMS: Contentful, Quintype, Hygraph, Ghost, Strapi, Sanity, Kontent, Optimizely

There are full backend solutions out there like Firebase, Supabase, and Appwrite. However, if you don't like some part of these stacks then it becomes very difficult for you to decouple your application(s). In this video our Founder and CEO talks about Authentication as a Microservice and how to use a JWT in your APIs.

Finally

Okay, now that I got that out of my system I am off to listen to Connor Price and log in to Amazon using my face because it is 2023 people!

Oh yeah and now the actual coding begins!!

If you want authentication to just work start using FusionAuth today for free!

Want to get jump-started using your framework of choice? Check out our Quickstarts.

Authentication Workflows Overview

FusionAuth — Mon, 16 Oct 2023 15:39:32 +0000

The landscape of applications today is broad. Similarly, the methods of authentication used is similarly varied. This section covers some of the login and authentication workflows used by applications today. These examples use FusionAuth as the IdP (identity provider), but any IdP could be used. You can use these articles to help architect and design the authentication system for your application.

Keep in mind that this list is not exhaustive. Most IdPs, including FusionAuth, are capable of other forms of login. Also, there are many login workflows that we do not cover here due to security concerns with those methods.

Also, these articles do not discuss the pros and cons of the different types of applications and which might be best for your needs. They focus entirely on authentication for applications. There are many articles available that cover different application types and why you should choose one over the other (such as the decision to use a native mobile application versus a responsive web application).

Definitions

Native login form - this is a form built directly into the application rather then leveraging an external login form such as an OAuth provider
Application backend - this is the backend of the application, not the IdP (i.e. not FusionAuth)

Traditional web application authentication

Traditional web applications (webapps) use the request and response nature of the HTTP protocol along with the URL address of the browser to provide functionality to users. Many new web applications are still implemented using this method and many existing web applications use this pattern.

These applications load a web page by making a request from the browser to the server based on the URL address. The server responds to these requests with HTML, CSS & JavaScript. These documents are then rendered by the browser.

When the user clicks a link, button or submits a form, the browser makes a new request to the server and changes the URL in the address bar. The server handles the request and returns HTML, CSS & JavaScript that is rendered by the browser again. The browser renders the new documents.

There are only two HTTP methods supported by the browser in this style of application, GET and POST. The HTTP method informs the server what type of action the user took and how to handle the request.

Single-page application authentication

Single-page web applications (SPA sometimes pronounced spa or S-P-A) use a single request and response to download the application. Sometimes the entire application is retrieved on the initial request and other times only part of the application is retrieved. This initial retrieve consists of HTML, CSS and JavaScript that comprise the application.

Once the application is retrieved, it is started by the browser, normally by invoking a JavaScript framework that bootstraps and then begins to render the application. In many cases, the HTML of the application is produced by JavaScript and the browser updates the current document dynamically.

SPAs use JavaScript and call APIs to handle user interactions and input. For example, if a user clicks a link, the SPA might modify the document to render a different page or form. When a user submits a form, the SPA might call an API on the server.

APIs are invoked using the XMLHttpRequest functionality of browser JavaScript. This generally makes calls to REST APIs on the server. When the server responds, the JavaScript running in the browser handles the response and updates the document.

Since the browser is using XMLHttpRequest, it can invoke all of the standard HTTP methods including GET, POST, PUT and DELETE. The HTTP method helps inform the server what type of action the user took and how to handle the request.

It is important to note that while we recommend OAuth for SPAs, it causes the browser to close the SPA and navigate to the OAuth provider. Once the OAuth workflow is complete, the browser retrieves and starts the SPA again. This process might seem somewhat heavy, but the SPA should be cached in the browser making the second startup process much faster.

Native mobile application authentication

Native mobile applications are usually installed via a store and installed on the mobile device (phone, tablet, etc). These applications are started by clicking the icon on the device. The device operating system then starts the application. Once the application is started, it renders its user interface.

Native applications often call APIs to handle user interactions and input. For example, if a user clicks a button or submits a form, the application might call an API on the server. This API might be called via HTTP or some other type of protocol. Often, native applications use various libraries for making API calls simpler.

Some experts recommend that native applications (including mobile apps) use OAuth's authorization code grant. This method works fine with many IdPs, including FusionAuth, but is not listed in this section because it is covered in the SPA and WebApp sections above. The only difference is that at the end of the OAuth workflow, the native application pulls the JWT and refresh tokens from the web-view.

Hacktoberfest 2023 with FusionAuth

FusionAuth — Wed, 04 Oct 2023 00:00:00 +0000

We're excited to announce FusionAuth's participation in this year's Hacktoberfest! Hacktoberfest is a global event that takes place every October, during which developers are encouraged to contribute to open-source projects like FusionAuth. The goal is to foster a vibrant open-source community, celebrate shared knowledge, and make the world of coding more accessible to all. You can find other participating repositories by searching the hacktoberfest topic on github.

Getting Started

The first step is to register for Hacktoberfest. Once you've registered, any PRs submitted to FusionAuth will count towards your participation in the event!

Contributing

If you haven't participated before make sure to read the Hacktoberfest Participation Guide.

To see all of FusionAuth's issues in one place see the full issue search.

This year for the Hacktoberfest we choose to focus on all of our JavaScript repositories. I have added the tag hacktoberfest to each one of the following repositories and even added an issue for simply updating the packages to their latest version.

Angular- The Authorization Code grant using the Angular framework
Consents- Example using advanced registration forms and consents
Deeplinking- Example returning users to the same page they logged in on
Device grant- An example of the Device Authorization grant
Express API- Express api which uses the Cookie Access Token
Family management- Family management and consent creation
FusionAuth SSO- Example of SSO between two different custom applications
Gaming and device grant- Example using the Device Authorization grant to provide authentication to a game.
Gatsby OAuth- An example of using Gatsby with the Authorization Code grant and PKCE
JWT Auth and a Microservices gateway- API gateway and microservices secured using JWT auth
Javascript JWT- JWT creation and decoding examples with javascript
Magic links login- nextjs app which uses magic links for authentication
Microservices gateway- API gateway and microservices
Multi-tenant application- Two nodejs applications in different tenants, living in different domains.
Next.js Single Sign-On- Single sign-on with Next.js and FusionAuth
Node OAuth- Login with the Authorization Code grant
React Native- The Authorization Code grant for a React Native mobile application
React with an Express backend- The Authorization Code grant using the React framework with the FusionAuth React SDK and an Express backend
React with the hosted backend- The Authorization Code grant using the React framework with the FusionAuth React SDK and the hosted backend
Remix auth- Example using FusionAuth to provide auth for a Remix application
Twitter login- Node/express app which uses Twitter for authentication
User actions example- Corresponds to the user actions guide tutorial
Vue.js- The Authorization Code grant using the Vue.js framework

How to set up an anonymous user flow

FusionAuth — Mon, 02 Oct 2023 00:00:00 +0000

For many applications, a user is forced to register for application access. You want to know who the user is so you can provide them with individualized functionality and data.

If your registration process requires an email or mobile phone number, registration allows you to market to your customers. This is great if you are pursuing a Product-led growth or freemium business model. Having contact information allows you to communicate with them directly, allowing you to remind them of the value of your application and driving re-engagement.

But sometimes, you don't want any registration friction, even though you want the user to access customized functionality or save data on your system. Anonymous users can help with this. Such users don't have any credentials or personally identifiable data associated with their accounts. They do exist in your customer identity and access management (CIAM) system and can be treated like any other account in terms of profile data or reporting.

FusionAuth doesn't support this concept using hosted login pages. The hosted login pages abide by the 80/20 rule. They cover 80% of the use cases for customer identity and access management.

When the hosted login pages don't meet your needs, you can use the APIs to build your workflows. You can do this for anonymous users. Here's a guide to implement this custom registration flow.

The rest of this blog post will look at some of the wrinkles of building out this progressive registration process, whether you use FusionAuth or any other system.

Anonymous User Lifecycle

Anonymous users have a more complex life cycle than the typical CIAM user. Here's a typical lifecycle.

A person visits your application. This person is called a visitor or unknown user and is most likely tracked by analytics or web stats logging software.
The visitor may take multiple actions such as viewing pages.
The person takes a certain action in your application that requires the creation of a profile.
An anonymous account is created to capture profile data. This is also known as a stub or shadow account.
The person continues to take additional actions in the application. Some of these may trigger updates to the anonymous profile, others may not.
At some time, the user registers for a conventional account. They may be prompted to do so based on activity, such as access to advanced functionality or an action that impacts the real world. Or they may choose to register.
The person registers and the account converts to a normal user account, including all extant profile data.
The person receives an email or text to set up their account.
The person sets up their credentials, including password and/or additional factors.
The person continues on their merry way, interacting with the application.

The application benefits by having a lower time to value. The user benefits because they have access to functionality or preferences before they register, as well as retaining access to any such data after registration.

As mentioned above, this is an example of progressive registration, with some profile data gathering taking place while the identity is unknown.

Where Anonymous Users Make Sense

There are two broad scenarios where anonymous users make sense.

First, if you want to serve personalized content or recommendations to a user who has yet to identify themself.

You might do this to increase the usefulness of your site. For example, for an e-commerce site, you might allow the user to "favorite" items they are interested in. You could then surface related items, or items that other similar users found interesting. Another example might be an online game. Users might want to tweak how their character looks without bothering to register, and such tweaking might drive more gameplay.

Second, if you want a user to have provided information or preferences available after registration.

You might do this if you want to allow users to experience application functionality without the friction of signing up. For instance, a diagramming application might allow anonymous users to create diagrams. Users would welcome having their saved diagrams available after they have registered. In the above e-commerce example, the favorited items should be available for perusal (and purchase!) after user registration.

Anonymous accounts can be helpful across a wide variety of business domains, including:

E-commerce sites with a shopping cart
B2B applications where users can create software artifacts
games
high value research applications, such as real estate search sites
news and content sites where personalization can drive engagement

However, anonymous accounts aren't always a good option. They don't make sense:

for applications where anonymous users don't make sense, such as an email or banking application
if the profile data of the anonymous user is not valuable to the application or the user
for applications where you must be able to contact all users
if the profile data is highly sensitive, such as medical information

Implementation Subtleties

There are some implementation concerns you should consider when building a system with anonymous users.

Marking Accounts as Anonymous

Make sure you have some way to identify anonymous users as such. In FusionAuth, you might use the user.data field. Below is a screenshot of an anonymous user in the admin UI.

Marking users in this way allows you to run analytics to understand user behavior. It also lets you remove inactive anonymous accounts.

The string DNUXUS8WIUXRGHQSNALTECZGD8IYZ7LN0X09RTTX2G9WMVFWJ6CF3T7HMCJWV3SF is a random username, since FusionAuth requires all users to have either a username or an email address.

Storing The Anonymous User's Identity

After you create an anonymous profile, you need to associate the person with that profile. With a web application, you can set a persistent cookie to maintain this association. The value of the cookie is typically a synthetic user Id, which does not identify the user outside of your system. A UUID is a good choice.

You can store the Id in the following ways inside the cookie:

A plaintext value is easiest, but a malicious client can tweak the user Id to explore different users' saved data.
A signed token, such as a JWT. Checking the signature on every request costs some computational power, but avoids malicious actors probing other user Ids.
An encrypted, URL safe value. This is typically overkill for an opaque user Id, but if your user Id might leak information, such as the size of your user base because it is an integer value, then encryption might work.

This cookie can be stored as an HTTPOnly, Secure cookie since only your server-side code will be examining it. Each time the cookie is presented, the server-side code can decode it, and then update the anonymous account profile if needed.

Here's an example of code that sets a JWT with a user Id, using the FusionAuth JWT Vend API.

    # create a JWT, good for a year
    jwt_ttl=60*60*24*365
    jwt={
      'claims': {
        'userId': user_id
      },
      'keyId': env.get("SIGNING_KEY_ID"),
      'timeToLiveInSeconds': jwt_ttl
    }
    response = client.vend_jwt(jwt).success_response
    token=response['token']
    resp = make_response(render_template("video.html"))

    # set the cookie
    resp.set_cookie(ANON_JWT_COOKIE_NAME, token, max_age=jwt_ttl, httponly=True, samesite="Lax")

Because you are storing information on the device, if a person accesses your site from a different browser or device, you have no way of reconciling them. This is also true if the user removes the cookie or the cookie expires. These are limitations of cookies, so there's no way around it.

Converting Accounts

When you convert an account, you associate the user Id stored in the cookie and a real-world user identifier such as an email address or a mobile phone number. Update the anonymous account with this information, which means it is no longer anonymous. Then send a "set up your password" request or other method of setting up credentials.

Here's an example of code that does this:

  # if they have a cookie, look up the user and convert them and send a password reset
    if request.method == 'POST':
      user_id = get_anon_user_id_from_cookie()
      if user_id is None:
        print("couldn't find user")
        message["message"] = "Couldn't find your user id."
        return render_template("register.html", message=message)

      # correct the email address using patch if the email doesn't already exist
      email_param = request.form["email"]

      user = client.retrieve_user_by_email(email_param).success_response
      message["message"] = "Please check your email to set your password."

      # if we already have the user in our system, fail silently. depending on your use case, you may want to sent the forgot password email, or display an error message
      if user is None:
        patch_data = {
          'user': {
            'email': email_param
          }
        }
        patch_response = client.patch_user(user_id, patch_data).success_response

        forgot_password_data = {
          'loginId': email_param,
          'state': { 'anon_user': 'true' }
        }
        trigger_email_response = client.forgot_password(forgot_password_data)

Verifying Accounts

When converting an account from an anonymous account to a regular one, make sure you verify the user's ownership of the email address (or phone number) they provide. If you instead let someone provide an email address and password on the conversion page, anyone with device access would control the resulting profile.

While that may be acceptable when an unknown user registers, where there is no anonymous user data, avoid letting someone "take over" an anonymous profile.

One easy way to verify ownership is to send the password reset email or text after the user provides an email address or mobile phone number. At that point, you know they "own" it.

Then you can update the associated profile to remove anonymous account indicators. Below you can see the code to do this.

@app.route("/webhook", methods=['POST'])
def webhook():
  # look up the user by id. If they are not an anonymous user return 204 directly, otherwise update their anonymous user status to be false and return 204
  # looking for email user login event because email verified is only fired on explicit email verification
  if request.method == 'POST':
    webhookjson = request.json
    event_type = webhookjson['event']['type']
    is_anon_user = webhookjson['event']['user'] and webhookjson['event']['user']['data'] and webhookjson['event']['user']['data']['anonymousUser']
    if event_type == 'user.login.success' and is_anon_user:
      user_id = webhookjson['event']['user']['id']
      patch_data = {
        'user': {
          'username': '',
          'data' : {
            'anonymousUser':False
          }
        }
      }
      patch_response = client.patch_user(user_id, patch_data).success_response

  return '', 204

In FusionAuth, the easiest way to do this is via a webhook, but different systems have different mechanisms. The important point is to leave the profile untouched until ownership is proven.

Culling Accounts

At some point, clear out old anonymous accounts that have never converted to regular user accounts. Do this by querying the update timestamp of each anonymous account. Then, determine which untouched accounts are old enough to delete.

Synchronize this with the lifetime of the cookie containing the user Id. If the cookie is good for a month, you can clear out accounts that have not been updated for 40 days, because the user would never be able to successfully convert their anonymous account after the cookie is gone.

This reaping process can be run periodically by a scheduled job.

Privacy Concerns

Ensure you abide by all rules for jurisdictions where your users live. In particular, make sure you don't collect any personal data unless you have the processes in place to abide by the GDPR.

Personal data is defined as:

any information that relates to an identified or identifiable living individual. Different pieces of information, which collected together can lead to the identification of a particular person, also constitute personal data.

Billing Concerns

While the creation of anonymous accounts is unlikely to impact the system performance of an identity provider, these profiles may impact your bill. If your identity provider charges based on active users, you may be charged for these accounts. Before implementing this flow, make sure you understand what a large number of user accounts does to your pricing.

For example, if you are using FusionAuth to implement this workflow, each anonymous account will be counted as an MAU for the month it is created, but not in subsequent months.

Why Not Just Use JavaScript

You can definitely track anonymous actions with JavaScript, with a tool like Google Analytics. However, at some point, you will need to convert the profile to a server-side account with real credentials, so it may be easier to create it on the server side initially.

In addition, if you want to have a single view of your user base, having all users in one data store will be easier.

Learn More

If you want to learn more about the anonymous user workflow, you can:

Read the anonymous user guide
Run and tweak an example anonymous user application
Read "Unlocking Growth: Why A Low Friction User Signup Process Is Crucial For Your Business"

Get More Value Out of FusionAuth Using the APIs for User Maintenance

FusionAuth — Fri, 01 Sep 2023 00:00:00 +0000

So, you have just set up FusionAuth and are excited to take your new customer identity and access management platform out for a spin. You spend some time setting up your Users, Applications, Tenants, etc. in the robust admin interface provided. Things are looking great. You have integrated your applications and are humming along. Now comes a real test, user maintenance.

Introduction

“A new user with extra pickles, please.”

Customizing the order for your favorite food can make a good meal better. Customizing your end-users' experience with user maintenance can make their experience with your application even better.

For any secure application, user maintenance is a must. As a developer, you can often overlook the time and effort it takes to maintain the user's access and permissions for the shiny new application you created. In an ideal world, you do not want to be the ones to maintain the users. You want to give the task of user maintenance to the power users of the applications by making them application administrators. While those power users may be great at using the application, you don’t necessarily want to make them expert users of the FusionAuth admin interface. Well, we at FusionAuth would think it would be great if everyone was a master with it, but you may not share that same vision.

Imagine you have an application that controls a machine that applies the toppings to a burger. Custom Burger, the popular new burger joint just bought your application. The tech-savvy manager, Sally Power-User, has been given admin rights. Sally just hired Joe Limited-Access to work the night shift. She now needs to add Joe as a user of your application. She needs to ensure Joe can add pickles to a burger order but make sure he does not have access to apply the famous Flaming Carolina Reaper Sauce until he goes through training. Your application will have to support this.

You can harness the full power of FusionAuth in your application, hand off the user maintenance to the power users, and make it seamless for them. The application will need to ensure that Sally Power-User enters the correct information (Validation), guide her through setting up the new Joe Limited-Access user correctly (Workflow), and you want to make the process feel like it is part of your application (Branding). You can accomplish all these through the use of the FusionAuth APIs.

Newer developers should be aware the examples below are written with the assumption that you are familiar with how to make REST calls using the HttpClient in C#, the use of asynchronous calls and Windows Forms applications. In order for the sample application to run you must have a working FusionAuth server. Even if you are not totally familiar with these concepts, you will likely be able to follow the code snippets with general programming knowledge. If you need a refresher on some of these topics, there are some links at the end.

If you are only interested in jumping into the code, it can be found here.

Custom Validation With FusionAuth APIs

“With great power, comes great responsibility!”

One of FusionAuth’s strengths is its flexibility. However, with the flexibility comes some complexity. To create a user in the FusionAuth admin user interface, you only need two pieces of information. You will need to supply either the username or the email in addition to a password. (If you are using multiple tenants, you will need the tenant ID as well.) The FusionAuth admin user interface gives you other optional fields to fill in, however none are required. When using the Create a User API, only the username or email in addition to the password is still required but there are also over 30 additional request parameters available for customization. Creating a custom admin interface around the APIs will not only allow you to choose which of the username or email fields to use, but also what other meta-data is appropriate and required for your application. Below is sample code for creating a user using the FusionAuth API.

Setting Up The User Object

First, you need to create a few objects to hold some values. By constructing the classes and decorating properties with the proper attributes, you can still use the strongly typed objects and standard naming conventions in your C# application while also using the JSON Serializer to easily format the request body when it is time.

using Newtonsoft.Json;

namespace FusionDemoAPI.Helper
{
  public class User
  {
    [JsonProperty(PropertyName = "user")]
    public UserProperties UserProperties;
  }

  public class UserProperties
  {
    [JsonProperty(PropertyName = "firstName")]
    public string FirstName;
    [JsonProperty(PropertyName = "lastName")]
    public string LastName;
    [JsonProperty(PropertyName = "email")]
    public string Email;
    [JsonProperty(PropertyName = "password")]
    public string Password;
  }
}

Taking Input From The User

Next, you need to take the input from the user and assign them to the values in your User object. In this case, you are performing those actions on a click event from the Create User button on a Windows Form. Pictured below is a screen shot of the interface for the sample application.

You can also take this chance to validate any information deemed relevant to your application. The logic in the IsUserValid function can be edited to suit your needs. In this sample application it simply returns true. I know, not very creative, but useful in the demo. You can also validate age, location or anything else you choose. Once the validation is successful, you will then pass the user object to the method that will submit your request to the FusionAuth server. Validating input like this will ensure Sally Power-User enters the correct information for the system every time she adds a new employee.

It is important to note that the FusionAuthClient that has been created for this applications handles the setting of the API Key and location of the FusionAuth server. These settings are stored in the App.settings file for the project.

    private async void btnCreateUser_Click(object sender, EventArgs e)
    {
      //FusionAuthClient is a class that contains the logic to call the FusionAuth APIs
      var faClient = new FusionAuthClient();

      UserProperties userProperties = new UserProperties()
      {
        Email = txtEmail.Text,
        FirstName = txtFirstName.Text,
        LastName = txtLastName.Text,
        Password = txtPassword.Text
        //add additional properties here
      };

      User userToCreate = new User()
      {
        UserProperties = userProperties
      };

      //perform custom validation logic in the IsUserValid method
      if (IsUserValid(userToCreate))
      {
        ReturnValue userCreatedReturnValue = await faClient.CreateUser(userToCreate);
        if (userCreatedReturnValue.success == true)
        {
          LogResults($"User created with ID: {userCreatedReturnValue.result}");
          PopulateComboBox(cmbUsersToDelete, PopulateType.Users);
        }
        else
        {
          LogResults($"User creation failed. {userCreatedReturnValue.result}");
        }
      }
      else
      {
        LogResults($"User data provided is invalid");
      }
    }

Creating The User

Because you decorated your User objects correctly using the JSONProperty attribute, you can use the JSON Serializer to serialize the object with the JsonConvert.SerializeObject method. You also need to encode it properly before you submit it. Once that is complete, you can submit the request to the FusionAuth server. You will do so here using the async pattern so as to not hold up the processing for a request that may take some time or give the application an unresponsive feel. Once you receive the return values, you can interrogate them and act accordingly.

    public async Task<ReturnValue> CreateUser(User userToCreate)
    {
      //returns HttpClient with correct setting for instance
      HttpClient httpClient = GetClient();

      //initialize the return value 
      ReturnValue returnVal = new ReturnValue()
      {
        success = false
      };

      try
      {
        //set the endpoint for creating a user
        string apiURL = $"/api/user";

        var payload = JsonConvert.SerializeObject(userToCreate);
        var content = new StringContent(payload, Encoding.UTF8, "application/json");

        HttpResponseMessage response = await httpClient.PostAsync($"{FUSIONAUTH_HOST}{apiURL}", content);

        if (response.IsSuccessStatusCode)
        {

          string responseBody = await response.Content.ReadAsStringAsync();
          JObject result = JObject.Parse(responseBody);
          returnVal.success = true;
          //assign the newly created user id to the result
          returnVal.result = result["user"]["id"].ToString();
        }

      }
      catch (Exception ex)
      {
        Console.WriteLine($"There was an error in the request {ex.Message}");
        returnVal.result = ex.Message;
      }

      return returnVal;
    }

User Workflow With FusionAuth APIs

“Amateurs do it till they get it right. Professionals do it until they can not get it wrong.”

You may have originally set up the users manually in the FusionAuth admin user interface and that is fine to get started. However, the more steps and requirements you have for creating a user, the more likely something will be missed. There can be several steps required to set up a user correctly such as making sure they belong to the correct group(s). While you may be infallible as a developer and get it right every time, wink wink, most likely your users will not.

You can use the FusionAuth APIs to ensure the user is added to the correct group or groups so their permissions will be set properly. After the user is created, you can take this opportunity to automatically assign the user to a specific group or present an admin interface to the administrator that will guide them in selecting the proper group(s). For example, you can ensure Sally Power-User cannot add Joe Limited-Access to the Flaming Carolina Reaper Sauce Appliers on the day she creates him as a user because you know he has not had time to go through the training.

Setting Up The Group Object

Once again, you will need to create a few objects to help us organize your groups. The Add Users to a Group API call you are using requires a collection of groups that each contain an array of user information. In this case, you will only be using the user Id for the new GroupUser information.

using Newtonsoft.Json;
using System.Collections.Generic;

namespace FusionDemoAPI.Helper
{
  public class Group
  {
    public string ID;
    public List<GroupUser> Users;
  }

  public class GroupUser
  {
    [JsonProperty(PropertyName = "userId")]
    public string UserID;
  }
}

Taking Input From The User

As with creating the user, you need to take the input from the application and assign the values to your Group objects. Again, the IsGroupValid function simply returns true for the sample application but you can also validate any data you want before actually adding the user to the group. After you are satisfied the user should be added, you can submit the information to the method that will submit your request to the FusionAuth server.

    private async void btnAddUserToGroup_Click(object sender, EventArgs e)
    {
      //FusionAuthClient is a class that contains the logic to call  the FusionAuth APIs
      var faClient = new FusionAuthClient();
      //Get the selected values from the dropdowns
      var userIdToAdd = (string)cmbUsersToAddToGroup.SelectedValue;
      var groupIdToAdd = (string)cmbGroups.SelectedValue;

      if (userIdToAdd != null && groupIdToAdd != null)
      {
        List<GroupUser> users = new List<GroupUser>()
                {
                    new GroupUser()
                    {
                        UserID = userIdToAdd
                    }
                };

        Group group = new Group();
        group.ID = groupIdToAdd;
        group.Users = users;

        List<Group> groups = new List<Group>();
        groups.Add(group);

        //perform custom validation logic here
        if (IsGroupValid(group))
        {
          ReturnValue addUserToGroupReturnValue = await faClient.AddUserToGroup(groups);
          if (addUserToGroupReturnValue.success == true)
          {
            LogResults($"User {(string)cmbUsersToAddToGroup.Text} has been added to the group: {(string)cmbGroups.Text}");
          }
          else
          {
            LogResults($"Adding the user to the group has failed. {addUserToGroupReturnValue.result}");
          }
        }
        else
        {
          LogResults($"User and/or group data provided is invalid");
        }
      }
      else
      {
        LogResults($"No group or user selected.  Populate Users and Groups.");
      }
    }

Adding The User To The Group

Because the JSON format expected in the request body is not readily serializable given the Group objects you have created, you will have to perform a little wizardry to manipulate the Group objects. While this does not have to do with FusionAuth specifically, the code has been abstracted in the FormatGroupUserJSON function and can be found here if you are interested. Once the API call has returned, you can retrieve whichever values you see as relevant and pass it back in the result object.

    public async Task<ReturnValue> AddUserToGroup(List<Group> groups)
    {
      //returns HttpClient with correct setting for instance
      HttpClient httpClient = GetClient();

      //initialize the return value 
      ReturnValue returnVal = new ReturnValue()
      {
        success = false
      };

      try
      {
        //set the endpoint for creating a user
        string apiURL = $"/api/group/member";

        var payload = FormatGroupUserJSON(groups);
        var content = new StringContent(payload, Encoding.UTF8, "application/json");

        HttpResponseMessage response = await httpClient.PostAsync($"{FUSIONAUTH_HOST}{apiURL}", content);

        if (response.IsSuccessStatusCode)
        {

          string responseBody = await response.Content.ReadAsStringAsync();
          JObject result = JObject.Parse(responseBody);
          returnVal.success = true;
          returnVal.result = $"Member ID for added user: {result["members"].First().First()[0]["id"]}";
        }
        else
        {
          returnVal.result = $"Adding user to the group failed.\nPayload\n{payload}\n{response}";
        }

      }
      catch (Exception ex)
      {
        Console.WriteLine($"There was an error in the request {ex.Message}");
        returnVal.result = ex.Message;
      }


      return returnVal;
    }

Branding Your User Management With FusionAuth

“Design is the silent ambassador of your brand.”

One of the best parts about using the APIs to allow application admins to manage their own users is they never have to leave your application. Users are accustomed to things such as Single Page Applications or at least applications that have a consistent look and feel. Depending on the use case, a user may feel uncomfortable switching to the FusionAuth admin interface to manage users. While FusionAuth has a well designed and functional admin interface, the look and feel will likely be different than your application. By using the APIs you can still use all of your own style sheets and design principles.

You may ask yourself, “If I create an admin end for user management in my application, shouldn’t I just create the authentication and authorization framework as well?” The answer to that question is a resounding “No!” The security, power and flexibility FusionAuth gives you has taken years to build. You should focus on providing the unique business value your application provides versus reinventing the authentication wheel. The best part is that you can leverage our investment by creating a simple customer identity and access management interface around the security and power of FusionAuth. You get the best of both worlds.

You don’t even have to tell your users you are using FusionAuth. It’s okay, we don’t mind. We want to make you look good, help you secure your users, and let you focus on building the features your users want.

Conclusion

It is important to note that as an alternative, FusionAuth does allow the creation of custom forms in the admin user interface. This solution is only available for paid plans, may not support the workflow you are trying to accomplish and would not work if you did not want to give users access to the FusionAuth admin interface.

These are a few examples of how to use the FusionAuth APIs to get more value out of FusionAuth. Please take some time to explore the FusionAuth API documentation and get some more ideas of ways to use them to better serve your development. For instance, you have used the APIs to create a user, but you can use similar APIs to delete users or remove their application access. For example, you can monitor an external application and remove the user from FusionAuth on a given event.
By integrating the FusionAuth APIs not only can you automate the validation process, setup users, and make it all look like your own, but you can add almost any ability within FusionAuth to your application.

Next steps

If you enjoyed this article, please check out some of the other links and resources about FusionAuth.

FusionAuth APIs

FusionAuth Server Setup

5-Minute Setup Guide

Sample Application Source

FusionAuth API Demo

General

From ALB to Caddy - Our Wandering Path to Supporting Thousands of Domain Names

FusionAuth — Thu, 24 Aug 2023 00:00:00 +0000

In the world of cloud services, offering 'unlimited' often feels like a stretch. But we've done just that. We recently unveiled support for unlimited custom domains in FusionAuth Cloud. This marked a significant milestone in our journey and changed the game for our customers. Dive in as we unpack the architectural wizardry behind this transformative feature.

When customers use our FusionAuth Cloud managed hosting service, they can configure one or more custom domain names for their authentication server.

For example, a hosted deployment located at piedpiper.fusionauth.io could also be accessed at auth.piedpiper.com or id.piedpiper.com. This allows customers to keep their users on the same domain and maintain their branding throughout authentication flows.

For most companies, one or two custom domains is sufficient. However some business models have thousands of domain names, representing different applications or customers. In an ideal world, the same authentication source would serve all of these domain names..

FusionAuth supports multiple tenants and applications, so this shouldn't be a problem, right?

Right?

Correct! This is not an issue for FusionAuth as a product!

But things get a bit more complicated inside of FusionAuth Cloud, our managed hosting option, which runs on Amazon Web Services (AWS).

How It Works Today

Let's take a look at the architecture of FusionAuth Cloud, which includes both FusionAuth the product and surrounding infrastructure, called a deployment.

Internet traffic flowing into FusionAuth Cloud first arrives via a Global Accelerator and is then forwarded to an Application Load Balancer (ALB) for routing. The ALB is responsible for handling the TLS handshake, the routing of traffic to customer deployments, as well as performing distributed denial of service (DDoS) protection and web application firewall (WAF) filtering. This ALB must be configured with a TLS certificate and a routing rule for each of our customer's domains.

However, AWS imposes limitations on:

The number of Subject Alternative Names (hostnames) per certificate
The number of certificates associated with an ALB
The number of hostname routing rules associated with an ALB

This makes it impossible to use a single ALB to handle the traffic for all of our FusionAuth Cloud customers in a given region. In order to work around these limitations, we have provisioned additional ALBs and Global Accelerators. This also meant we imposed a limit on customers: they may only have four custom domains per deployment.

What's This Unlimited Domains Stuff Anyway?

Unlimited Domains is a new feature of FusionAuth Cloud that utilizes a modern edge infrastructure, providing dynamic TLS certificate provisioning and has no limits on the number of custom domains for a given deployment¹. It is currently an option available to select use cases for customers using High-Availability FusionAuth Cloud deployments.

¹ Nothing is truly infinite, but we have your use-case covered!

Coming Up With An Alternative

Conceptually, the problem we were looking at is simple: We need to replicate the functionality of AWS's ALB, but without the limitations. Effectively, this should be implemented as a reverse-proxy that:

Is highly-available across multiple AWS Availability Zones (AZs)
Is horizontally scalable and can handle load as we grow
Can support dynamic management of TLS certificates without downtime
Has no limits on the number of hostnames it can route

We decided to use AWS's Elastic Container Service (ECS) as our foundation, since it is fully managed and can automatically scale instances across AZs.

For the reverse proxy, either HAProxy or nginx worked, but we needed to determine how we could reconfigure them at runtime to automatically provision certificates as customers added domain names. We spent some time researching their respective APIs to see how they would fit into the FusionAuth Cloud management infrastructure.

During this research we stumbled upon Caddy, a software project that seemed to fit perfectly with our needs:

It natively supports ACME, the certificate provisioning protocol used by LetsEncrypt.
It is happy running in a container.
It has an API for dynamic configuration.

Since Caddy was a new kid on the block, it required a more thorough investigation than the battle-tested incumbents.

We set up a simulation environment to run it through its paces. Specifically, we wanted to ensure that when it was loaded up with 100k certificates, each with a unique hostname, it was able to perform TLS termination and route requests with throughput comparable to an ALB.

We found that with minimal resources allocated to the container, there was no increase in request processing time as the number of installed certificates grew. We felt confident enough in Caddy to move forward with integrating it into a test environment which mirrored our production infrastructure.

Building It Out

To avoid disruptions to our existing cloud deployments, we decided to build the new infrastructure in parallel with the existing systems.

The new design consisted of:

A multi-AZ ECS cluster of Caddy instances running on Fargate. This cluster would manage certificates, terminate TLS, and forward requests back to each customer deployment.
An EFS volume for Caddy to store certificates. Sometimes you just need a filesystem.
A Network Load Balancer (NLB) to distribute traffic across the Caddy instances.
A Global Accelerator to forward all edge traffic to the NLB.
An internal service which authorizes Caddy to provision certificates for only the domains that we explicitly allow.
Additional internal DNS records to map custom domain names to their respective deployments.

This design was simple, but lacked one important component: a Web Application Firewall (WAF). We use AWS's WAF to protect our customers' deployments against DDoS and bot attacks.

Since WAF can only inspect plaintext traffic and only works with ALBs, we had to insert a new ALB between Caddy and our customer deployments to get this protection. The alternative was running a WAF from a different vendor, which is possible but would balloon the scope of this project.

A Wrinkle With The WAF

A WAF can also get in the way sometimes. Integrations requiring frequent API access occasionally trigger DDoS rules, which means legitimate traffic is blocked. Customers may wish to add certain static IP addresses to an allowlist, guaranteeing unfettered access to their authentication servers.

To implement the allowlist, we need to know the source IP address of the traffic as it enters the Global Accelerator.

Luckily for us, Global Accelerator has an option to preserve the client IP address, so Caddy can pass it through in an X-Fowarded-For header where the WAF can compare it against our allow lists.

Unluckily for us, this option is only available when Global Accelerator is forwarding traffic to either an ALB or directly to EC2 instances. Since using an ALB here would re-introduce the limitations that we're trying to workaround, we were forced to ditch Fargate and use bare EC2 instances as our ECS capacity provider.

Running ECS workloads on EC2 is not difficult, but does require us to build out the automation to deploy, scale and keep the instances up to date. The Global Accelerator's endpoint group must also remain in sync with these instances.

These instances need to do only one thing: run Caddy containers. In order to minimize the attack surface, we did not want them running any services other than Docker. They do not need to run SSHD or most other services which are included in standard Linux distributions, so we searched for the most minimal distribution that would satisfy our basic requirements.

Bottlerocket is one such distribution. It is maintained by AWS, includes only the necessities to run Docker containers and it easily integrates with ECS. After building out our new ECS cluster with Bottlerocket as a base image, we found that our Caddy containers were failing to start with only a cryptic error message pointing to a failed EFS mount.

We verified that all of the IAM roles, security groups and file system policies were correct, but finally came across this issue. Bottlerocket does not support authenticated EFS volumes, and probably never will.

The next best distribution turned out to be Amazon's ECS-optimized AMI. It wasn't as minimal as Bottlerocket, but with some tweaks we were able to lock it down and swap it into our ECS cluster. After this change, everything was working. From dynamic certificate provisioning to load balancing to deployment routing.

At last, we had fully integrated Caddy end-to-end into our infrastructure. Our existing monitoring and alerting systems were easily attached to the new resources and we found no issues during our final testing.

What This Means For FusionAuth Cloud Customers

With this architecture change we can now support unlimited custom domains in FusionAuth Cloud. Whatever your use case -- we can handle it. All plans include a private instance (no shared public cloud) fully managed by FusionAuth, with options for backup, custom availability zones, uptime SLAs, and more to meet your infrastructure requirements.

You can start a free trial of FusionAuth Cloud now or for more complex projects or infrastructure questions, reach out to our identity experts for help.

Introducing Unlimited Custom Domains for FusionAuth Cloud

FusionAuth — Tue, 25 Jul 2023 00:00:00 +0000

Today, we’re announcing Unlimited Custom Domains for FusionAuth Cloud. Custom domains allow you to associate another domain with your FusionAuth Cloud deployment without having to fuss with certificate issuance and renewal – it just works.

Let’s take a look at the changes now and stay tuned for a future blog on how we engineered this feature (hint - it involves Caddy, an open-source project we are proud to support).

What are Custom Domains?

Custom domains let you brand your login experience and have your users see a domain they recognize – yours. Instead of seeing piedpiper.fusionauth.io in your login page’s URL, adding a custom domain allows you to set it as auth.piedpiper.com.

But Wait, Custom Domains Aren’t New

That’s true! Custom domains have been available for FusionAuth Cloud since 2021, but we supported a maximum of 4 custom domains, even on our High Availability hosting plan. Adding more than that required using a proxy layer like CloudFlare, Apache, or CloudFront and extra work for FusionAuth Cloud customers to manage those domains and certificates.

That got us thinking… why limit it to 4? And how could we streamline the process for customers?

So as of today, these changes are now in effect for FusionAuth Cloud:

High Availability Hosting now includes Unlimited Custom Domains.
A streamlined user interface for managing custom domains within the FusionAuth admin portal.

How to Add a Custom Domain

If you are on a supported deployment and want a custom domain name such as auth.piediper.com, it’s now entirely self-service. Log in to your account portal, navigate to Deployments and then select Custom URL(s) under the Action dropdown. Check out the custom domains documentation for details about how to add the domain name and update an existing domain record.

Other customer identity and access management platforms typically only offer one custom domain as standard. If you need more than that, some vendors even make you pay an extra fee per domain. With FusionAuth, it’s just another feature we are adding to support our growing customer base.

FusionAuth Cloud offers different hosting tier selections to give you a choice for your deployment needs. All plans include a private instance (no shared public cloud) fully managed by FusionAuth, with options for backup, custom availability zones, uptime SLAs, and more to meet your infrastructure requirements.

You can start a free trial of FusionAuth Cloud now or for more complex projects or infrastructure questions, reach out to our identity experts for help.

Contenda used FusionAuth instead of rolling their own auth stack and saved "a lot" of time

FusionAuth — Mon, 17 Jul 2023 00:00:00 +0000

Tamás Deme is a FusionAuth community member and engineering lead at Contenda. Grady Salzman is a FusionAuth community member and software engineer at Contenda. They chatted with us over email about how they and their team are using FusionAuth to meet their auth needs.

This interview has been lightly edited for clarity and length.

Dan: Can you tell me a bit about Contenda? What is the company's mission?

Tamás and Grady: Contenda is a content creation tool designed to enable anyone on a team to take any video, such as a conference talk, interview, or demo, and turn it into effective written content. It features an easy-to-use upload, transformation, and customization system, a powerful API to automate content production pipelines, and is built specifically for developer advocates.

Dan: What are some examples of features/functionality that are useful specifically for developer advocates?

Tamás and Grady: Our platform is capable of grabbing and re-formatting code-snippets from videos, and we made sure our editor uses and works well with Markdown, which is generally preferred by the dev advocate community.

Dan: What is the company's mission?

Tamás and Grady: To democratize and increase quality written content creation for users & organizations.

[Auth is] a gigantic headache to do on your own; it's easy to get suffocated in a sea of edge cases.

Dan: Tell me more about democratization. Can't anyone write good content? (Thank you, Tim Berners-Lee!) What am I missing?

Tamás and Grady: We believe that creating technical content should be accessible to everyone, no matter their experience level. What's "good" is not necessarily clear cut, as at minimum it starts a discussion and provides an understanding of everyone's point of view, which can then facilitate learning and correcting any misconceptions.

When we talk about quality we think about how accurately we can represent the original content we process, and make sure we don't make up things the original creator never intended to say.

Dan: Tell me about your work as engineers at Contenda.

Grady: I am the front end engineer, and I am responsible for building out our web app. For this integration, I did anything that wasn't backend. This included implementing the FusionAuth themes and hooking FusionAuth up to our web app.

Tamás: My job as the engineering lead is to drive the architectural, infrastructure and backend efforts at the company, and generally help the other engineers grow as the company grows.

Specifically for this integration process, I've mostly done everything that wasn't the frontend - starting with analyzing and choosing an auth provider, to performing the required database and backend changes, and handling the migration and support now that we've launched.

Dan: How do you use FusionAuth? OAuth? User management? Social sign-on? Something else?

Tamás and Grady: We use FusionAuth for almost all of our user management needs, except maybe for our workspace management. This includes doing authentication for our web app and our API. FusionAuth handles standard email/password sign ups and social sign ups as well.

Dan: For your API, are you using the client credentials grant, or a JWT from the authorization code grant or something else?

Tamás and Grady: Right now we're using the Application Authentication Token feature/API to get JWTs, although we might change that up in the future.

We appreciate that FusionAuth doesn't have any "trap-like" pricing practices that could bite us when we happen to approach an arbitrary number of users.

Dan: From a user management perspective, do you interact with the FusionAuth admin UI or the APIs plus a custom app?

Tamás and Grady: Yes, that's mostly correct. Our own tools for our own backend aren't as sophisticated just yet, but we'll get there.

Dan: What problems did we solve for you?

Tamás: To sum up, all of auth. Unless you're a major player (and sometimes even then), rolling your own auth stack is probably a bad idea, so we've always been planning on looking for a reliable 3rd party provider to handle all this for us. It's a gigantic headache to do on your own; it's easy to get suffocated in a sea of edge cases.

Dan: How were you solving them before FusionAuth?

Tamás and Grady: In the past we've used a very bare bones, API key only sign-up system we put together in under a week.

While it served us getting our first 1000 users, we definitely needed something more robust, secure and user-friendly to get to the next magnitude of users.

Dan: What did you use for the first system? Was it framework based, a library, or something else?

Tamás and Grady: It was a completely custom implementation, just the very basics really.

We could've spent months working on a complex system, and any FusionAuth employee could still say "Look what they need to mimic a fraction of our power" after that.

Dan: Why did you choose FusionAuth over the alternatives?

Tamás and Grady: After we eliminated all the options we had to rule out due to technical limitations, the two main reasons were cost and "friendliness".

While the price itself is one thing, by "friendliness" I mean both support and the pricing strategies down the line. We appreciate that FusionAuth doesn't have any "trap-like" pricing practices that could bite us when we happen to approach an arbitrary number of users.

Dan: What were some of the technical limitations you had that disqualified folks initially?

Tamás and Grady: It was mostly due to them not having react and/or python clients/SDKs.

Dan: I love the term "friendliness". Are there any other software packages you use that feel like they win in that category (other than FusionAuth and Contenda, of course)?

Tamás and Grady: On our frontend, we use Netlify and Pendo, and I think we could put them in this bucket as well. Generally smaller companies tend to care more about their customers, so it's not always the best idea to go with the biggest player out there.

Dan: How much time and money would you say FusionAuth has saved you?

Tamás: While I don't think I can come up with an exact number for either of those, I can confidently say: a lot. We could've spent months working on a complex system, and any FusionAuth employee could still say "Look what they need to mimic a fraction of our power" after that.

[After building our own auth system in under a week] we definitely need something more robust, secure and user-friendly to get to the next magnitude of users.

Dan: How do you run FusionAuth (kubernetes, standalone server, behind a proxy, etc)?

Tamás and Grady: We don't actually; you do!

This was also an important point for us: engineering-hours are always the limiting factor, so if we can find a provider that also handles the infrastructure for us, that's fewer hours we waste on managing something we don't have to.

Dan: Any general feedback/areas to improve?

Tamás: I'd love it if more things were "easy" on the "easy <-> possible" scale. FusionAuth is extremely customizable, which is great, and makes a lot of things possible.

But it'd be nice if the configuration interface would self-document itself more, and make a lot of the typical use-cases easy and simpler to do.

Also, as a fan of strong typing: adding type hints to the python client library would be tremendous.

Dan: Thanks for your feedback!

We love sharing community stories. You can check out Contenda's website if you'd like to learn more about them.

Adding single sign-on to a Next.js app using OIDC

FusionAuth — Wed, 26 Apr 2023 00:00:00 +0000

Single sign-on (SSO) is a session and user authentication technique that permits a user to use one set of login credentials to authenticate with multiple apps. SSO works by establishing trust between a service provider, usually your application, and an identity provider, like FusionAuth.

The trust is established through an out-of-band exchange of cryptographic credentials, such as a client secret or public key infrastructure (PKI) certificate. Once trust has been established between the service provider and the identity provider, SSO authentication can occur when a user wants to authenticate with the service provider. This will typically involve the service provider sending a token to the identity provider containing details about the user seeking authentication. The identity provider can then check if the user is already authenticated and ask them to authenticate if they are not. Once this is done, the identity provider can send a token back to the service provider, signifying that the user has been granted access.

SSO helps reduce password fatigue by requiring users to only remember one password and username for all the applications managed through the SSO feature. This also reduces the number of support tickets created for your IT team when a user inevitably forgets their password. In addition, SSO minimizes the number of times you have to key-in security credentials, limiting exposure to security issues like keystroke probing and exposure. Security is also enhanced by SSO because you can implement additional functionality such as MFA or anomalous behavior detection at the identity provider without adding any complexity to your application.

In this tutorial, you’ll learn how to design and implement SSO using Next.js, a popular React-based framework for JavaScript and FusionAuth as the OIDC provider. Any other OIDC compatible authentication server should work as well.

Implementing SSO in a Next.js web app

As previously stated, in this tutorial, you’ll be shown how to implement SSO in a Next.js web app. The Next.js demo application is integrated with FusionAuth, an authentication and authorization platform, and NextAuth.js, a complete open-source authentication solution, in this article.

Before you begin, you’ll need the following:

A Linux machine. The step-by-step instructions in this article are based on a CentOS Linux machine. If you want to work on a different OS, check out this setup guide for more information.
Docker Engine and Docker Compose.
Node.js.
Experience with Next.js framework and application development.
The Git client tool (optional).

Installing FusionAuth

If you already have a FusionAuth Cloud instance, you can use that, but for the sake of simplicity, this tutorial will assume you are using a locally hosted instance. There are detailed setup guides in the documentation, but the short version is that once you have Docker and Docker Compose set up and installed correctly, you can run the following command in a new directory to download and execute the necessary files.

curl -o docker-compose.yml https://raw.githubusercontent.com/FusionAuth/fusionauth-containers/master/docker/fusionauth/docker-compose.yml curl -o .env https://raw.githubusercontent.com/FusionAuth/fusionauth-containers/master/docker/fusionauth/.env docker compose up

Starting FusionAuth

Once the FusionAuth service is started, open a browser and access http://localhost:9011/, where you’ll be taken to the “FusionAuth Setup Wizard” , as seen in the image below.

FusionAuth setup wizard.

Fill in the admin user account details, read and accept the License Agreement. When you are ready, click “Submit”.

Learn more about the Setup Wizard here.

After submitting, you’ll be taken to a login screen where you need to fill in the credentials you specified during the setup wizard and sign in to the FusionAuth administrative user interface. Later, you’ll use the same admin account for testing the SSO of the application.

Configure FusionAuth

Now you need to configure FusionAuth by creating an application and registering the user.

This setup allows users in FusionAuth to sign in to the Next.js application automatically once they are authenticated by FusionAuth.

Set up the application

To set up the application, navigate to the FusionAuth admin UI and select “Applications” on the left-hand navigation bar:

Set up the application.

Then click on the “+” button on the top right of the “Applications” page and fill in the “Name” field with a name of your choosing (here, it’s “your_application” ):

Name your application.

You can leave all the other fields empty because FusionAuth will choose a default value for those fields. Go ahead and save the application in order for the Client Id details to be generated.

Access the “Application” page again and click on the “Edit Applications” icon (a little edit/notepad icon):

The list of applications. The edit icon is the blue pencil/notepad.

On the “Edit Application” page, click on the “OAuth” tab at the top. You’ll need to get some information from this page.

The OAuth details tab.

Record the generated “Client Id” and the “Client Secret” in a text file or to the clipboard. You’ll use these below.
Add the value http://localhost:3000/api/auth/callback/fusionauth to the “Authorized redirect URLs” field. This will be used by FusionAuth to redirect the user to your application page once the user is successfully authenticated.
Scroll down and check the “Require registration” checkbox. This ensures that users who haven’t been registered for this application in FusionAuth aren’t able to access it when using the hosted login pages.

After filling in the details, click the “Save” icon.

You aren’t limited to one application, by the way. If you have multiple applications, or even other applications like Zendesk or forum software, set them up here to enable SSO.

Register the user

Next, register the user for the application. Navigate to the “Users” tab and find your user. Click on the black “Manage User” button under the “Action” heading in the list. You’ll end up at the details page:

The user details screen, where you can register them.

Click “Add registration” to register the user in your_application.

Adding the user registration.

If users of this application have unique configuration details, such as a username, timezone, or languages, which are different from the user’s defaults, you could configure them here.

However, for this tutorial, you can click the blue “Save” button and accept the default values.

Kickstart

Instead of manually setting up FusionAuth using the admin UI as you did above, you can use Kickstart. This tool allows you to get going quickly if you have a fresh installation of FusionAuth. Learn more about how to use Kickstart.

Here’s an example Kickstart file which sets up FusionAuth for this tutorial.

Create the Next.js application

You have two options here. You can either clone a working example, or build the app from scratch.

Clone the demo repository

If you want to run an already working application, you can clone the demo project from this GitHub repository using the following command.

git clone git@github.com:FusionAuth/fusionauth-example-nextjs-single-sign-on.git

Since you’ve cloned a working rep, you don’t need to follow the next section. If you’d like to understand more about what was done in the demo application, feel free to read them.

Either way, continue configuring the Environment variables to proceed with this tutorial.

Create your own Next.js application

If you want to create your own application instead of using our demo project, you can create a new Next.js application by running the command below.

npx create-next-app name-of-your-application

If it is your first time creating a Next.js application, you’ll be prompted to install the create-next-app package. Just type y to accept it.

The create-next-app wizard will ask you a few questions on how to set up your application. Answer them like shown.

✔ Would you like to use TypeScript with this project? … No ✔ Would you like to use ESLint with this project? … Yes ✔ Would you like to use `src/` directory with this project? … Yes ? Would you like to use experimental `app/` directory with this project? … No ✔ What import alias would you like configured? … @/*

Enter the directory for the application you created and start up the application by running these commands.

cd name-of-your-application npm run dev

Browse to localhost:3000. If the installation went successful, you should see the default welcome page from Next.js.

Now that you have the application running, let’s implement the authentication process by using NextAuth.js, a complete open-source solution.

Installing NextAuth.js

We recommend you look at the NextAuth.js Getting Start guide for the most up-to-date instructions.

First, install NextAuth.js.

npm install next-auth

Now, you need to create a file named exactly like [...nextauth].js in src/pages/api/auth.

First, make the directory:

mkdir src/pages/api/auth

Then create a file named [...nextauth].js in that directory.

Next, you’ll configure the built-in support for FusionAuth. Doing so ensures every request to the /api/auth/* path is handled by NextAuth.js.

import NextAuth from "next-auth" import FusionAuthProvider from "next-auth/providers/fusionauth" export const authOptions = { providers: [FusionAuthProvider({ issuer: process.env.FUSIONAUTH_ISSUER, clientId: process.env.FUSIONAUTH_CLIENT_ID, clientSecret: process.env.FUSIONAUTH_CLIENT_SECRET, wellKnown: `${process.env.FUSIONAUTH_URL}/.well-known/openid-configuration/${process.env.FUSIONAUTH_TENANT_ID}`, tenantId: process.env.FUSIONAUTH_TENANT_ID, // Only required if you're using multi-tenancy }),], } export default NextAuth(authOptions)

Exposing session state

To allow components to check whether the current user is logged in, change src/pages/_app.js to have your application rendered inside a <SessionProvider> context, like shown below.

import '@/styles/globals.css' import { SessionProvider } from "next-auth/react" export default function App({ Component, pageProps: {session, ...pageProps}, }) { return ( <SessionProvider session={session}> <Component {...pageProps} /> </SessionProvider> ); }

This will make the useSession() React Hook accessible to your entire application.

Now, create a component that will either render a “Log in” or “Log out” button, depending on the session state, in a src/components/login-button.jsx file.

import { useSession, signIn, signOut } from "next-auth/react" export default function Component() { const { data: session } = useSession() if (session) { return ( <> Status: Logged in as {session.user.email} <br /> <button onClick={() => signOut()}>Log out</button> </> ) } return ( <> Status: Not logged in <br /> <button onClick={() => signIn()}>Log in</button> </> ) }

Then, you change your home component located at src/pages/index.js to include the <LoginButton /> component inside <main>.

import Head from 'next/head' import LoginButton from '@/components/login-button' export default function Home() { return ( <> <Head> <title>Next.js + FusionAuth</title> <meta name="description" content="Sample app to demonstrate implementing authentication in a Next.js application with FusionAuth" /> <meta name="viewport" content="width=device-width, initial-scale=1" /> <link rel="icon" href="/favicon.ico" /> </Head> <main> <LoginButton /> </main> </> ) }

Environment variables

If you cloned the demo repository, you can copy .env.local.dist to .env.local and change the values there. If not, create a .env.local file and fill in the details from your FusionAuth application.

# example: my-website.com FUSIONAUTH_ISSUER=http://localhost:9011 FUSIONAUTH_CLIENT_ID=e9fdb985-9173-4e01-9d73-ac2d60d1dc8e FUSIONAUTH_CLIENT_SECRET=super-secret-secret-that-should-be-regenerated-for-production # Leave blank if you only have the default tenant FUSIONAUTH_TENANT_ID= # example: http://localhost:9011 FUSIONAUTH_URL=http://localhost:9011 # you can run `openssl rand -base64 32` NEXTAUTH_SECRET=random_value_please_change

Testing

Start the HTTP server by running the following command.

npm run dev

Browse to localhost:3000.

The initial nextjs screen.

Click the “Log in” button to be taken to a page with a “Sign in with FusionAuth” button.

The sign-in button screen.

After clicking it, you should be redirected to your FusionAuth login screen.

The FusionAuth sign-in screen.

Enter the correct credentials created when you set up FusionAuth and submit the form. You’ll arrive back at your Next.js application home screen, with your email address displayed and a “Log out” button.

The nextjs application after logging in.

Next steps

What’s next?

You could:

Make FusionAuth look like your nextjs application using themes.
Learn more about OAuth.
Build out a real nextjs application with a protected page.

Happy coding!

Save on your AWS bill with this one simple trick

FusionAuth — Mon, 03 Apr 2023 00:00:00 +0000

With only a few clicks of the mouse, I saved 16% on my company’s AWS bill. Pretty sweet, eh?

This article will show you why that matters, and how I did it.

FusionAuth Cloud lets you outsource operating your authentication service

But first, let me set the scene. FusionAuth is downloadable software and running it is as simple as:

curl -o docker-compose.yml https://raw.githubusercontent.com/FusionAuth/fusionauth-containers/master/docker/fusionauth/docker-compose.yml curl -o .env https://raw.githubusercontent.com/FusionAuth/fusionauth-containers/master/docker/fusionauth/.env docker-compose up

If you have Docker installed, that’s all you have to do to get a FusionAuth instance up and running.

After that, you need to integrate it with your application, typically using a standard OIDC library such as Passport or Spring security. You need to theme it to make it look like your application.

But that’s it.

With these steps, you get a full featured auth server, available on your laptop, for you to build against.

What about production?

docker-compose up is great for development.

But auth is the front door to your application, and should be highly available in production. Some of the considerations when running a FusionAuth production deployment include:

securing the application and servers
backups and restores
upgrades and rollbacks
responding to DDOS attacks
monitoring

FusionAuth Cloud, where the FusionAuth team operates FusionAuth, lets customers let us run FusionAuth for their authentication needs. It takes these tasks off your plate and puts them on that of the FusionAuth team.

Now, there are many customers with the team, compliance needs, and desire to run FusionAuth themselves; we’re happy to support them in doing so with documentation and customer support.

But many users want to offload operational burdens and security concerns. In this aspect, FusionAuth Cloud is similar to a typical software as a service (SaaS) provider.

What’s so special about auth?

But.

An authentication service is not like any old SaaS application. Depending on your integration, it is embedded in your application. This is why Okta consistently has negative churn on the order of 20%. Once you’re committed to an auth provider, it’s a biggish project to shift to another one.

Worse, when your auth system breaks, your users don’t have access to your application. That’s bad.

Because of these two attributes, with an auth provider you have requirements above and beyond those of a typical SaaS tool. FusionAuth Cloud offers the following:

It explicitly lets developers control the upgrade process; no required upgrades. You and your engineering team pick the version of software your application integrates with. You also choose how and when to upgrade. You can thoroughly test your integration when a new version comes out, rather than testing in prod or having new features foisted on you.
Each customer is running on physically isolated single-tenant systems. Each FusionAuth Cloud deployment runs on separate virtual hardware, using Amazon’s best of breed managed services where appropriate.

Isolation in multi-tenant SaaS

Let’s talk about isolation. When you offer a multi-tenant solution, with different customers using your application, there are multiple approaches to isolating their data and available functionality.

Logical isolation is implemented using a tenant_id field on tables (or using proprietary database functionality such as row level security). When a request comes in, the tenant is identified and only that tenant’s data is examined by the application. This is the cheapest and easiest multi-tenant solution to run. You have one set of servers and one primary datastore in production. However, if there are any flaws in the code, everyone’s data may be accessible. You can scale this system, but you can’t scale any individual customer’s application.
Container level isolation relies on containers and other software constructs such as Kubernetes namespaces. With this option, you have one set of servers underlying the containers in a cluster, though you can also outsource running it to a public cloud provider. Each customer gets their own set of containers running the code, as well as a separate database schema or server. This is more expensive, but provides a higher level of isolation.
Server isolation is when you stand up separate virtual or physical machines. The application runs on each system. You can configure network layer protections such as firewalls, which increases the level of isolation. There’s also a lower chance of a noisy neighbor causing customers issues; the servers are separate. However, the operational cost is higher too.

FusionAuth Cloud uses virtual machines and a shared-nothing architecture. Your data is isolated not within a database using foreign keys, but on physically separate machines.

FusionAuth Cloud and EC2

This architecture leads to a lot of VMs, as you might imagine. As FusionAuth Cloud grows, the FusionAuth team is responsible for more and more virtual machines.

Which brings us back to the beginning. During a hackfest, I took a look at reserved instances because I was interested in the cost savings opportunities. Most of FusionAuth’s AWS spend is with EC2 and RDS.

Many of our customers are on month to month plans, and the minimum AWS reserved instance length is one year (unless you are using the reserved instances marketplace, but I’m going to ignore that because it makes things complicated).

Our customers also choose one of 15+ AWS regions in which to deploy their FusionAuth servers. This allows them to pick the region that makes sense for their performance, compliance and data sovereignty needs, while still outsourcing operations to the FusionAuth team. Reserved instances are tied to an AWS region, making it an awkward choice.

While we could have projected a baseline of region usage and VM lifetime and bought reserved instances based on that, this felt like a bigger project than was suitable for a hackfest.

However, after more research, I discovered AWS Compute Savings Plans. There is an EC2 version that “appl[ies] to EC2 instance usage regardless of instance family, size, AZ, Region, OS or tenancy”.

Perfect!

How much can you save?

FusionAuth Cloud adds new customers regularly, and churn happens, especially when someone tries our Starter Plan free trial and determines that FusionAuth isn’t the right fit.

I wanted to avoid automating the purchase of these plans, which felt like over-optimization. I began with a manual solution.

The Savings plan overview has a “Recommendations” tab. You can play with options and arrive at a savings amount. This helps you determine if you have enough spend to make buying a plan worth your time. To begin with, I chose “Compute Savings Plans”, a “1-year” term, and “No upfront” as the purchase commitment. You get a deeper discount for prepayment or a longer commitment.

Here’s a table of the discounts available to us at time of writing. Check out the Savings plans section yourself to see your discount options.

	No Upfront	All Upfront
1 Year	21%	26%
3 Year	45%	49%

I could have saved more money, but going with a year term and no upfront cost gave the right mix of savings and flexibility. A 21% discount on EC2 usage we already know will be running 100% of the time?

Yes please.

Buying the Compute Savings plan

Here’s the screen where I purchased the plan.

With Compute Savings plans, you are buying hours of instances, but paying in dollars per hour. It’s a bit weird, but makes sense when viewed in the bigger picture. After all, it’s an AWS bill, so it can’t be too straightforward.

Here’s an example to make it a bit clearer.

Let’s say you have 20 X1E Extra Large EC2 instances. These bad boys each cost $0.6160 per hour. I don’t know what you’re doing with that much RAM, but whatever.

With this, you have $12.32/hour of spend (20*0.616). To save money, if you know you will run these servers for a year or so, use a Compute Savings plan and buy down a portion of the $12.32. You could buy $5 of that hourly spend for $3.95, for instance.

After you buy the plan, you will be billed for that $3.95 whether you run the instances or don’t. Your total hourly bill is now $11.27, a savings of $1.05 or 8.5% across your entire spend.

The bottom line is that AWS is thrilled when you commit to spending money with them, and is therefore willing to pay you to do it.

Setting up a system

Because of our growth, I wanted to avoid buying a savings plan as a one and done effort. I wanted a system that was lightweight, but would save us money as more customers came on board while preserving flexibility if we wanted to shift directions.

Instead of buying the amount recommended by AWS, I bought 50% of it. In the future, we’ll do it again: purchase half of the recommended Compute Savings plan every few months.

This will allow us to work towards having 100% of our usage covered by a savings plan. But we’ll never get there. Similar to Achilles and the tortoise from Zeno’s paradox (image credit to wikipedia).

After determining that system would work, I documented it so I wouldn’t forget. This also lets others do this task if need be. Then I attached it to a recurring event in my calendar and promptly forgot about it. Every quarter or so, I get a reminder, and log into the AWS console and buy more discounted compute hours.

This approach doesn’t maximize our savings, but it yields a useful amount (approximately 16% of our bill) and offers flexibility if our needs change. All at the cost of approximately 10 minutes every quarter.

I’ve spent more time on this blog post than I have buying Compute Savings Plans over the past year. I’ll be honest, it’s fun to save thousands or tens of thousands of dollars with a single click and essentially zero downside.

That’s the kind of clickops I can get behind.

Downsides of AWS Compute Savings plans

What about that downside? Well, if FusionAuth ever needed to leave AWS, we’d have to plan ahead a year or so or eat the cost of the committed spend. However, migrating off any cloud provider, especially when your system is the front door for millions of your customers’ customers, isn’t a task you undertake on a whim. That downside is acceptable.

We’re also not saving as much as we could. If we signed up for three years instead of one, we’d save more but lose flexibility. If we optimized, researched reserved instances (especially for RDS servers), and automated plan purchases, we could save even more. But we’ve made a conscious decision to focus on growth. Spending too much time optimizing cloud spend doesn’t align with that.

10 minutes a quarter, on the other hand, is pretty easy to find.

Summing up

If you are running significant numbers of EC2 instances, there’s very little risk in investigating and implementing cost savings plans.

Happy saving!

Adding single sign-on to a Laravel app using Socialite and OIDC

FusionAuth — Mon, 13 Mar 2023 00:00:00 +0000

In this tutorial, you’ll learn how to design and implement SSO using Laravel, a popular PHP-based web framework and FusionAuth as the OIDC provider. Any other OIDC compatible authentication server should work as well.

Implementing SSO in a Laravel web app

As previously stated, in this tutorial, you’ll be shown how to implement SSO in a Laravel web app. The Laravel demo application is integrated with FusionAuth, an authentication and authorization platform, and Laravel Socialite, its official solution to authenticate users with OAuth providers.

Before you begin, you’ll need the following:

A Linux machine. The step-by-step instructions in this article are based on a CentOS Linux machine. If you want to work on a different OS, check out this setup guide for more information.
Docker Engine and Docker Compose.
Experience with a Laravel framework and application development.
The Git client tool.

Clone the GitHub repository (optional)

If you don’t want to keep copying and pasting code from this article, you can clone this GitHub repository using the command below. You’d still have to configure the environment variables though.

git clone https://github.com/FusionAuth/fusionauth-example-laravel-single-sign-on

Installing FusionAuth

$ curl -o docker-compose.yml https://raw.githubusercontent.com/FusionAuth/fusionauth-containers/master/docker/fusionauth/docker-compose.yml $ curl -o .env https://raw.githubusercontent.com/FusionAuth/fusionauth-containers/master/docker/fusionauth/.env $ docker compose up

Starting FusionAuth

Once the FusionAuth service is started, open a browser and access http://localhost:9011/, where you’ll be taken to the “FusionAuth Setup Wizard” , as seen in the image below.

FusionAuth setup wizard.

Fill in the admin user account details, read and accept the License Agreement. When you are ready, click “Submit”.

Learn more about the Setup Wizard here.

Configure FusionAuth

Now you need to configure FusionAuth.

First, you’ll configure the application, then register the user for the application.

This setup allows users in FusionAuth to sign in to the Laravel application automatically once they are authenticated by FusionAuth.

Set up the application

To set up the application, navigate to the FusionAuth admin UI and select “Applications” on the left-hand navigation bar:

Set up the application.

Then click on the “+” button on the top right of the “Applications” page and fill in the “Name” field with a name of your choosing (here, it’s “your_application” ):

Name your application.

You can leave all the other fields empty because FusionAuth will choose a default value for those fields. Go ahead and save the application in order for the Client Id details to be generated.

Access the “Application” page again and click on the “Edit Applications” icon (a little edit/notepad icon):

The list of applications. The edit icon is the blue pencil/notepad.

On the “Edit Application” page, click on the “OAuth” tab at the top. You’ll need to get some information from this page.

The OAuth details tab.

Record the generated “Client Id” and the “Client Secret” in a text file or to the clipboard. You’ll use these below.
Add the value http://localhost/auth/callback to the “Authorized redirect URLs” field. This will be used by FusionAuth to redirect the user to your application page once the user is successfully authenticated.
Scroll down and check the “Require registration” checkbox. This ensures that users who haven’t been registered for this application in FusionAuth aren’t able to access it when using the hosted login pages.

After filling in the details, click the “Save” icon.

You aren’t limited to one application, by the way. If you have multiple applications, or even other applications like Zendesk or forum software, set them up here to enable SSO.

Register the user

The user details screen, where you can register them.

Click “Add registration” to register the user in your_application.

Adding the user registration.

If users of this application have unique configuration details, such as a username, timezone, or languages, which are different from the user’s defaults, you could configure them here.

However, for this tutorial, you can click the blue “Save” button and accept the default values.

Kickstart

Here’s an example Kickstart file which sets up FusionAuth for this tutorial.

Installing and configuring Laravel

If you already have a running Laravel application, please skip this step.

There are several ways of installing Laravel, but we recommend using it inside a Docker container via Laravel Sail. To do so, you can execute the command below to automatically download and install every package needed:

$ curl -s https://laravel.build/my-app | bash

You can change the name of your application from my-app from the URL above to anything you like, as long as it only contains alphanumeric characters, dashes and underscores.

After everything is finished, you can enter the application directory and start it via Sail:

$ cd my-app $ ./vendor/bin/sail up -d

The command ./vendor/bin/sail has a lot of built-in tools to handle the containerized application from your host machine and it forwards every unknown argument to docker compose. So, the command above would actually just call docker compose up -d with the necessary context and environment to run it successfully.

To test whether the Laravel application is up and running as expected, open a browser and access http://localhost.

The default Laravel application.

Laravel Socialite

According to its own docs, Laravel Socialite is a “a simple, convenient way to authenticate with OAuth providers”, meaning that is a very straightforward way of calling a remote server in order to authenticate a user. And that is exactly what FusionAuth is all about!

Officially, it ships with support for Facebook, Twitter, LinkedIn, Google, GitHub, GitLab and Bitbucket, but there are several community projects that add other providers, and they are grouped in a project called Socialite Providers.

Thanks to the open-source community, there is this package to use FusionAuth as a provider, which we’ll now use to show you how it’s done!

Installing the FusionAuth provider

The first thing you need to do is add the FusionAuth provider as a dependency to your application.

$ ./vendor/bin/sail composer require socialiteproviders/fusionauth

When running the command above, composer will automatically install the necessary laravel/socialite package

Alter the service provider responsible for listening to events at app/Providers/EventServiceProvider.php to tell Laravel that it should call FusionAuthExtendSocialite class when there is an event for Socialite. To do this, change its $listen property to add the following entry to the array:

protected $listen = [\SocialiteProviders\Manager\SocialiteWasCalled::class => [ \SocialiteProviders\FusionAuth\FusionAuthExtendSocialite::class . '@handle',], ];

If you already have something in the $listen array (like Registered::class => [...]), please keep it and add a new entry to the array

Now, configure your application with the necessary settings to interact with the FusionAuth service, by adding a new entry to the array located at config/services.php:

'fusionauth' => ['client_id' => env('FUSIONAUTH_CLIENT_ID'), 'client_secret' => env('FUSIONAUTH_CLIENT_SECRET'), 'redirect' => env('FUSIONAUTH_REDIRECT_URI'), 'base_url' => env('FUSIONAUTH_BASE_URL'), 'tenant_id' => env('FUSIONAUTH_TENANT_ID'),],

Configuring environment variables

Instead of putting the values directly there, you should use environment variables, which is a good practice from both maintenance and security standpoints, as described in the 12 Factor App methodology and in several others. Being so, alter your .env file to include those entries:

# Paste both client Id and secret for your application FUSIONAUTH_CLIENT_ID=<APP CLIENT ID FROM FUSIONAUTH> FUSIONAUTH_CLIENT_SECRET=<APP CLIENT SECRET FROM FUSIONAUTH> # Specify a tenant Id or leave this blank for the default tenant FUSIONAUTH_TENANT_ID=<ID FOR YOUR TENANT> # Replace http://localhost:9011 with the address where the FusionAuth application is running FUSIONAUTH_BASE_URL=http://localhost:9011 # Replace http://localhost with the address for your PHP application, if necessary # We'll create the route for `/auth/callback` later## FUSIONAUTH_REDIRECT_URI=http://localhost/auth/callback

Creating new fields in the User model

Migrations are the code-based version control for your database. Instead of having to share SQL queries with your coworkers so they can create a table or add a column everytime there is a change in the database, you can write code to programmatically do this when running a command.

In Laravel, to create a new migration you just need to run the artisan make:migration and inform a meaningful name for it. In the next line, we’ll create a migration called add_fusionauth_fields_user_table:

$ ./vendor/bin/sail artisan make:migration add_fusionauth_fields_user_table

Then, go to your database/migrations folder, where you’ll find a file there with the name you created and prefixed by today’s date (e.g 2023_02_03_123000_add_fusionauth_fields_user_table.php).

Edit that file to add three new columns to the users table: fusionauth_id, fusionauth_access_token and fusionauth_refresh_token and allow NULL values in the password column. You’d want to save the access token in your database to make requests to the FusionAuth API or other APIs that accept FusionAuth access tokens on behalf of the user. The refresh token is used to exchange an expired access token with a new one (but you’d still have to implement this yourself, as Socialite still doesn’t do it). This way, users don’t need to log in again to your FusionAuth instance as long as the refresh token is still valid.

If you cloned our GitHub repository, you can just copy the contents from laravel/migration.php.

<?php use Illuminate\Database\Migrations\Migration; use Illuminate\Database\Schema\Blueprint; use Illuminate\Support\Facades\Schema; return new class extends Migration { /*** When running this migration, we want to create three new columns and change the password so it can be NULL * * @return void */ public function up() { Schema::table('users', function (Blueprint $table) { $table->string('fusionauth_id', 36)->unique(); $table->text('fusionauth_access_token'); $table->text('fusionauth_refresh_token')->nullable(); $table->string('password')->nullable()->change(); }); } /** * When rolling back this migration, we want to drop the added columns and revert the password to NOT NULL again * * @return void */ public function down() { Schema::table('users', function (Blueprint $table) { $table->dropColumn('fusionauth_id'); $table->dropColumn('fusionauth_access_token'); $table->dropColumn('fusionauth_refresh_token'); $table->string('password')->nullable(false)->change(); }); } };

You also need to add doctrine/dbal as a dependency, which is a package responsible for changing table and column definitions:

$ ./vendor/bin/sail composer require doctrine/dbal

Run the migration to add those new columns:

$ ./vendor/bin/sail php artisan migrate INFO Running migrations. 2023_02_03_123000_add_fusionauth_fields_user_table ........................... 51ms DONE

Now, you need to change the User model so it can become aware of these new columns. Modify app/Models/User.php and add them to both $fillable and $hidden properties:

/*** The attributes that are mass assignable. * * @var array<int, string> */ protected $fillable = ['name', 'email', 'password', 'fusionauth_id', // Add this column here 'fusionauth_access_token', // Add this column here 'fusionauth_refresh_token', // Add this column here]; /** * The attributes that should be hidden for serialization. * * @var array<int, string> */ protected $hidden = ['password', 'remember_token', 'fusionauth_id', // Add this column here 'fusionauth_access_token', // Add this column here 'fusionauth_refresh_token', // Add this column here];

Adding routes

Now that your Users model and table have more details about the integration, you should define the necessary routes to redirect the user to the FusionAuth login and the page that the user will be redirected to after completing the process and obtaining an access token there. Add them to the routes/web.php file:

If you cloned our GitHub repository, you can just copy the contents from laravel/routes.php.

<?php use App\Models\User; use Illuminate\Support\Facades\Auth; use Laravel\Socialite\Facades\Socialite; /*** Responsible for redirecting the user to the FusionAuth login page */ Route::get('/auth/redirect', function () { return Socialite::driver('fusionauth')->redirect(); })->name('login'); /** * This is the address that we configured in our .env file which the user will be redirected to after completing the * login process */ Route::get('/auth/callback', function () { /** @var \SocialiteProviders\Manager\OAuth2\User $user */ $user = Socialite::driver('fusionauth')->user(); // Let's create a new entry in our users table (or update if it already exists) with some information from the user $user = User::updateOrCreate(['fusionauth_id' => $user->id,], ['name' => $user->name, 'email' => $user->email, 'fusionauth_access_token' => $user->token, 'fusionauth_refresh_token' => $user->refreshToken,]); // Logging the user in Auth::login($user); // Here, you should redirect to your app's authenticated pages (e.g. the user dashboard) return redirect('/'); });

Changing the view

To better see what is going on after logging in, you can change the view for the home page to actually display the name or the current user. You can do this by opening resources/views/welcome.blade.php and adding a new line after “Home”:

// Before: @auth <a href="{{ url('/home') }}" class="font-semibold text-gray-600 hover:text-gray-900 dark:text-gray-400 dark:hover:text-white focus:outline focus:outline-2 focus:rounded-sm focus:outline-red-500">Home</a> @else // ... // After: @auth <a href="{{ url('/home') }}" class="font-semibold text-gray-600 hover:text-gray-900 dark:text-gray-400 dark:hover:text-white focus:outline focus:outline-2 focus:rounded-sm focus:outline-red-500">Home</a> <span class="ml-4 text-gray-600 dark:text-gray-400">Welcome, <span class="font-semibold">{{ Auth::user()->name }}</span></span> @else // ...

Testing

It is finally time to open your application in the browser and test everything! Navigate to http://localhost and click the “Log in” link in the upper right corner of that page to be taken to FusionAuth’s login screen. Provide the credentials for the user you created earlier and submit the form: you should be redirected back to that “Welcome” page but instead of seeing the same “Log in” link, you should now see both “Home” and your name there!

The default Laravel application while being logged in.

Now you have a working Laravel application that has been authenticated by the user created in FusionAuth. On successful sign-in to the integrated OAuth and identity provider, the user is automatically signed in in the Laravel application!

Conclusion

SSO-based authentication eases the process of signing in to applications, and it’s a popular choice for many organizations. In this article, you learned about SSO and authentication platforms like FusionAuth, as well as how you can integrate a Laravel application with FusionAuth to successfully enable SSO-based authentication.

Get your hands dirty by downloading FusionAuth for free and set up SSO for your Laravel app today.

Using and Managing Consents in an Express App

FusionAuth — Mon, 20 Feb 2023 00:00:00 +0000

In this tutorial, we’ll build a basic Node.js and Express web application with advanced user registration and authentication via FusionAuth. We’ll create a custom registration form, along with custom consent options for marketing preferences, and set up self-service options for users to update their profile and consent permissions.

The application itself is very simple: it will let users sign up via FusionAuth, allow them to set their permissions for marketing consent, and allow them to update their profile and consents at any time. With these basics in place, you’ll see how FusionAuth works and how it can extend the application to do whatever you need. You can also skip ahead and view the code, although much of the application is defined in FusionAuth as detailed in this guide.

The profile and custom registration forms described below are part of our paid plans. Please see the pricing page for more information about paid plans. Consents, however, are community plan features.

Prerequisites

We’ll explain nearly everything that we use, but we expect you to have:

Basic Node.js knowledge and a Node.js environment set up.
Preferably basic Express knowledge (or knowledge of a similar web framework or the middleware concept).
Docker and Docker Compose set up as we’ll set up FusionAuth using these.

It’ll also help if you know the basics of OAuth or authentication in general.

Why FusionAuth instead of plain Passport?

Passport is one of the commonly used authentication systems in Express apps. It is very powerful and allows you to hook into social providers, OpenID and OAuth providers, or use a local authentication strategy. This sounds like everything you’ll ever need, but there are still a few missing pieces. For example, you still need to construct your own login page and other account functionality such as changing passwords, forgotten password resets, 2FA, email verification, account protection, and more. Setting up custom web app authentication is always more complicated than it seems.

You would also need to implement functionality to allow users to update their profile information. Part of users’ profile and account data is inevitably consent permissions. Most apps will need to gather users’ consent for activities such as sending marketing updates or sharing users’ data with affiliates and other third parties. This would normally require coding, storing, and maintenance with custom solutions. However, since it is an integral part of user identity, FusionAuth has consent management built in.

The great news is that combining Passport with FusionAuth makes a complete system that takes care of all aspects of authentication and identity. It also means that much of your app’s authentication capability can be configured through FusionAuth rather than writing code and modifying your app. For example, you can easily add registration form fields whenever you need to, without changing code or redeploying your app.

With this setup, authentication, identity, and consent concerns are taken care of entirely by FusionAuth.

The image below shows how this works.

Your application logic and all public information can be handled by Express. Anything sensitive, such as personally identifiable information (PII), passwords, and consent permissions, is handled by FusionAuth.

This allows you to focus your security efforts on the FusionAuth installation. It also means that if you create more applications, they can piggyback on your centralized authentication and you don’t need to re-implement authentication each time. You can also create a multi-tenant configuration, allowing you to easily have logically separate environments for different clients.

Also, any integrations you set up with other providers (for example, Twitter, Google, Apple sign-in) can be done once instead of per application.

Installing and configuring FusionAuth with Docker Compose

There are various ways to install FusionAuth depending on your system, but the easiest way is to use Docker and Docker Compose. Instructions are here. Currently, if you have Docker installed, to install and run FusionAuth you would run the following commands:

curl -o docker-compose.yml https://raw.githubusercontent.com/FusionAuth/fusionauth-containers/master/docker/fusionauth/docker-compose.yml https://raw.githubusercontent.com/FusionAuth/fusionauth-containers/master/docker/fusionauth/docker-compose.override.yml curl -o .env https://raw.githubusercontent.com/FusionAuth/fusionauth-containers/master/docker/fusionauth/.env docker-compose up

Note that this uses a public .env file containing hard-coded database passwords and is not suitable for production use.

Configuring FusionAuth

FusionAuth should now be running and reachable at http://localhost:9011 if you’ve installed it locally. The first time you visit, you’ll be prompted to set up an admin user and password. Once you’ve done this, you’ll be prompted to complete three more set-up steps, as shown below.

We’ll skip step 3 in this tutorial, but sending emails (to verify email addresses and do password resets) is a vital part of FusionAuth running in production, so you’ll want to do that when you go live.

Creating an application

Click “Setup” under “Missing Application” and call your new app “Consents-App”, or another name of your choice. It’ll get a Client Id and Client Secret automatically - save these, as we’ll use them in the code. Later, we’ll set up a Node.js and Express application that will run on http://localhost:3000, so configure the Authorized URLs accordingly. You should add:

http://localhost:3000/auth/callback to the Authorized redirect URLs.
http://localhost:3000/ to the Authorized request origin URL.
http://localhost:3000/ to the Logout URL.

Click the “Save” button at the top right for your changes to take effect.

Setting up a FusionAuth API key

Once the user has logged in via the FusionAuth application, we can retrieve their FusionAuth profile and consent permissions using the FusionAuth Typescript module, provided with an API key.

Navigate to “Settings”, then “API Keys”, and add a key. Add a name for the key and take note of the generated key value.

For extra security, you can restrict the permissions for the key. For our app, we only need to enable the get actions for /api/user/ and /api/user/consent that will let the key get basic user information, as well as any consents. If you leave the key with no explicitly assigned permissions, it will be an all-powerful key that can control all aspects of your FusionAuth app. You should avoid doing this!

Creating the custom consents

For our app, we want users to be able to opt-in, or consent, to different marketing channels:

Physical mail
Email
Phone

We’ll need to get their permission for each of these options. FusionAuth manages all this under the Consents concept. We can create custom consents for our app.

In the left-hand pane, navigate to Settings > Consents. Click the green “+” button to create a new consent. Name the new consent “Email Marketing” and click the “Save” icon.

Repeat this to create two more consents: “Phone Marketing” and “Physical Mail Marketing”.

Creating custom form fields

During user registration for our app, we want users to be able to set their important profile information as well as their consent permissions. For this, we can create custom form fields that we will be able to use in a custom registration form. FusionAuth also has many built-in form fields, which we will also use.

The custom fields we’ll create are:

Physical Address.
Form Input for Physical Mail Marketing Consent.
Form Input for Email Marketing Consent.
Form Input for Phone Marketing Consent.

In the left-hand pane, navigate to Customizations > Form Fields. Click the green “+” button to create a new form field.

First, we’ll add the marketing consent fields, starting with the physical mail marketing consent. Choose “Self Consent” as the field type, and set the “Name” to “Physical Mail Marketing Consent”. Select “Physical Mail Marketing” as the “Consent”. The field setup should look like this:

Click the “Save” button and then repeat this process for the email and phone consents.

We’ll also need to add a custom field to capture the user’s physical address. We’ll create just one field here. In a production app, you might want to break down the address into a few fields, for example, “Address Line 1”, “Address Line 2”, “City”, etc.

Click the green “+” button to create a new field. Name the new field “Physical Mail Address”. For the “Field”, select “Custom user data (user.data.*)”. This will present another input box, starting with “user.data”. Type “physicalmailaddress” in this box.

This adds a custom field to the user’s “data” object. The “data” object can store extra profile information about the user, typically information you’d want to share across all your apps. If the field is app-specific, then you can use the field type “Custom registration data” instead.

The field setup should look like this:

Click “Save”. We have set up all the custom fields we need.

Create the custom registration form

Now that we have the custom fields, we can create a custom registration form with them. Navigate to Customizations > Forms. Click the green “+” to create a new form.

Name the form something like “Consents Registration Form”. Make sure “Registration” is selected as the form’s “Type”. Then click the “Add Step” button. A step in a form is like a page of the form. It helps to break up a form into multiple smaller pages so that users are not overwhelmed by a screen full of inputs.

In the “Step 1” section, click the “Add Field” button. Select “Email” from the “Field” dropdown, and then click “Submit”. Then click “Add Field” again, select “Password” as the “Field”, and click “Submit”. We’ll only capture the user’s email and password in the first step.

Now click the “Add Step” button again. In this step, we’ll capture the user’s alternative contact information. Click “Add Field”, select “Mobile Phone” as the field, and click “Submit”. Repeat for “Physical Mail Address”.

Click the “Add Step” button once more for the final registration step. In this step, we’ll capture the user’s consent permission for each marketing channel. Click “Add Field”, select “Physical Mail Marketing Consent”, and then click “Submit”. Repeat this process for the email and phone marketing consents.

Your final form should look similar to this:

Click “Save”. The custom registration form is complete.

Adding description for the consent inputs.

By default, when adding a consent field type to a form, FusionAuth will render just the id of the consent on the form. This would not be helpful to users. We can customize the rendered text of the consent fields by adding lines to the “messages” template of the theme, linking a display name to each consent.

To prepare, navigate to Settings > Consents. For each of the consents you created, record their Id and Name. We’ll use this in the theme messages.

The default theme in FusionAuth cannot be modified, but we can clone the theme and modify our copy.

Navigate to Customizations > Themes and click the “Duplicate” button next to the default “FusionAuth” theme. Give this new theme a name, perhaps “Consents App Theme”. Click on the “Messages” template and then the “Edit” button next to the default localization. Scroll all the way to the bottom of the template and add a line for each of the consents, like this:

consents['ef1b3adf-4963-4eee-893a-f16d9d97a95d']=I'd like updates via Snail Mail consents['41bc0627-5df3-466a-bac1-a12925580c7f']=I'd like updates via Email consents['e6a4e555-f037-4e77-92fd-d805bdba7c33']=I'd like updates via Phone (text)

Replace the UUID in each consent with the Id you recorded earlier. You can make the descriptions whatever you like. Click “Submit”, and then save the theme.

Now navigate to the application you created earlier. Click “Edit” to open the application editor, and select your new theme from the “Theme” dropdown. Save the application to reflect this change.

Create the profile update form

Once a user has registered for your app, they might want to change their profile information, including the permissions given for each of the consents. FusionAuth provides a default “Account” page out of the box, but we’ll need to create a custom one to account for the consent fields and other custom profile information.

Navigate to Customizations > Forms and click the green “+” button. Set the “Name” of the form to something like “Consents Self Service”. Select “Self-Service User” from the “Type” dropdown.

Instead of “Steps” like the registration form, self-service profile forms have “Sections”, which are functionally the same. We’ll mirror the registration layout here.

Click “Add Section” and add the fields “Email” and “Password” to this section.

Create another section and add the fields “Physical Mail Address” and “Mobile Phone” to it.

Now create the last section and add the consent fields “Phone Marketing Consent”, “Email Marketing Consent”, and “Physical Mail Marketing Consent”.

The form configuration should look similar to this:

Click “Save” to finish creating the form.

Linking the new forms to the application

We’ve created the forms but we still need to link them to the application so that they are used in place of the defaults. We also need to enable registrations on the application.

Navigate to Applications and click on the “Edit” button next to the application created earlier. Click on the “Registration” tab. Under “Self-service registration”, turn on the “Enabled” switch. Select “Advanced” for the “Type”. Select your custom registration form from the “Form” dropdown.

Under the “Form settings” section, select your custom self-service form from the “User Self-service” dropdown.

Click “Save” to apply the updates to your application.

The FusionAuth setup is now complete. We can move on to the Express app.

Setting up Express

To get started, you should:

Scaffold a new Express application.
Install the scaffolded dependencies.
Install Passport and helper libraries, and the FusionAuth Typescript client.
Start the server to ensure everything is installed and working.

Here are the commands to do it:

npx express-generator --view=hbs fusion-consents cd fusion-consents npm install npm install passport passport-oauth2 connect-ensure-login express-session @fusionauth/typescript-client npm start

If all went well, the server should start successfully and you can visit http://localhost:3000.

Building the application

Our application will only have three pages, including the FusionAuth login page.

A home page - a public page showing how many users our app has and inviting users to log in.
The registrations page (redirected to FusionAuth) with options to set their marketing consents.
A logged-in private profile page. This will display the user’s profile and consent permissions retrieved from FusionAuth, and allow them to click through to update their profile information, including consent permissions.

Adding and initializing dependencies

To start, we’ll add the references needed for Passport, the passport-oauth2 strategy, and enabling sessions using Express Sessions. We’ll also add a reference to the FusionAuth typescript client.

Open the app.js file. Below the line var logger = require('morgan'); add the following:

var passport = require("passport"); var OAuth2Strategy = require("passport-oauth2").Strategy; var passOAuth = require("passport-oauth2"); var { FusionAuthClient } = require("@fusionauth/typescript-client"); var session = require("express-session"); const { ensureLoggedIn } = require('connect-ensure-login');

Now we can initialize and add Passport and the session handler to the Express pipeline. Add the following just below the app.use(express.static(path.join(__dirname, 'public'))); line:

app.use(session({ secret: "TOPSECRET" })); app.use(passport.initialize()); app.use(passport.session());

Replace the TOPSECRET value with a long, high entropy, random string of your choice. This secret is used to sign the session information in the cookie. Normally, this is kept secret, as anyone who has access to the secret could construct a session cookie that looks legitimate to the server and gives them access to any account on the server. You can also add an environment variable to store this secret, rather than storing it in the code repo.

We’ll also need to initialize the FusionAuth client with the API key created earlier. This will allow us to retrieve the user profile and consents from FusionAuth after a successful login. Add the following code just below the previous code added:

const fusionClient = new FusionAuthClient( "<YOUR_FUSION_API_KEY>", "https://<YOUR_FUSIONAUTH_URL>" );

Replace the parameter <YOUR_FUSIONAUTH_URL> with the URL your FusionAuth instance is located at (normally http://localhost:9011 for local Docker installs). Replace <YOUR_FUSION_API_KEY> with the API key created earlier.

Now we can initialize the Passport strategy. We’ll be connecting to FusionAuth using OAuth2, so we’ll use the passport-oauth2 strategy. Add the following code directly below the code you’ve just added:

passport.use( new OAuth2Strategy( { authorizationURL: "https://<YOUR_FUSIONAUTH_URL>/oauth2/authorize", tokenURL: "https://<YOUR_FUSIONAUTH_URL>/oauth2/token", clientID: "<YOUR_FUSIONAUTH_APP_CLIENTID>", clientSecret: "<YOUR_FUSIONAUTH_APP_CLIENT_SECRET>", callbackURL: "http://localhost:3000/auth/callback", }, function (accessToken, refreshToken, profile, cb) { // Get the user profile from Fusion: fusionClient .retrieveUserUsingJWT(accessToken) .then((clientResponse) => { return cb(null, clientResponse.response.user); }) .catch((err) => { console.error(err); }); } ) );

Replace the parameter <YOUR_FUSIONAUTH_URL> with the URL your FusionAuth instance is located at. Replace <YOUR_FUSIONAUTH_APP_CLIENTID> and <YOUR_FUSIONAUTH_APP_CLIENT_SECRET> with the values you saved during the FusionAuth application setup earlier.

This snippet of code sets up the OAuth parameters for the Passport strategy. The strategy has a callback, which is invoked when a successful authorization and token call has been completed to FusionAuth. The FusionAuth client has a handy method to retrieve a user by the JWT returned from the authorization process. We can use this to get the user and return it to the Passport strategy callback. This user will then also be passed to our session handler to save, and added to the req parameter in subsequent middleware handlers as req.user. To enable this, add the following code, below the code you just added:

passport.serializeUser(function (user, done) { process.nextTick(function () { done(null, user); }); }); passport.deserializeUser(function (user, done) { process.nextTick(function () { done(null, user); }); });

Adding Express routes

We’ve got the basic framework and authorization code set up. Now we can add some routes. We’ll start with the login route to handle the redirect to FusionAuth.

Add this code under the app.use("/", indexRouter); line:

app.get("/login", passport.authenticate("oauth2"));

Note that we don’t need to add a router or view for the login redirect to FusionAuth to work. Passport will check whether the user needs to be logged in, and if so will send them to FusionAuth for authentication.

After authentication, FusionAuth will redirect to the callback route we provided in the Passport OAuth setup, as well as in the authorized callback route earlier. We can add this route now. Add the following code under the login route:

app.get( "/auth/callback", passport.authenticate("oauth2", { failureRedirect: "/" }), function (req, res) { // Successful authentication, redirect home. res.redirect("/"); } );

On successful authentication or failure, we’ll redirect to the homepage. Let’s update that now to show the login status and provide a link to the user’s profile page. Open the index.js file in the routes folder and update the get route to the following:

router.get('/', function(req, res, next) { res.render('index', { title: 'Express', "authenticated": req.isAuthenticated() }); });

Passport adds a function isAuthenticated() to the req object. Querying this function tells us whether the user is logged in. We add this to the keys and values passed to the index view, so that we can show a different message based on the user’s authentication status.

Now open the index.hbs file in the views folder, and update the code to the following:

<h1>{{title}}</h1> <p>Welcome to {{title}}</p> {{#if authenticated}} <p>You are logged in!</p> <p> You can now visit your <a href="/users/me">profile page</a> </p> {{else}} <p> <a href="/login">Login Here</a> </p> {{/if}}

This will notify the user if they are logged in or not, and point them to the relevant action.

Adding a members-only area

Now that we have the basic login and authentication mechanics set up, we can add a restricted route that is only available to users that are logged in. This route will show the user their profile, and a link to update their information.

In the users.js file in the routes folder, replace the code with the following:

var express = require("express"); var router = express.Router(); var { FusionAuthClient } = require("@fusionauth/typescript-client"); const fusionClient = new FusionAuthClient( "<YOUR_FUSION_API_KEY>", "https://<YOUR_FUSIONAUTH_URL>" ); /* GET users listing. */ router.get("/me", async function (req, res, next) { const user = req.user; // Get the user's consent info: let userConsents = {}; try { const response = await fusionClient.retrieveUserConsents(user.id); userConsents = response.response.userConsents; } catch (err) { console.log(err); } res.render("me", { profile: JSON.stringify(user, null, "\t"), consents: JSON.stringify(userConsents, null, "\t"), }); }); module.exports = router;

This code sets up a FusionAuth client link so that we can read the user’s consent information from the API. It also creates a /users/me route, which is used to retrieve the user’s profile information. In the route, we grab the user object from the req parameter. Recall this was added by Passport earlier in the setup. Then we make a call to the FusionAuth API to retrieve the user’s consent information, passing in the user’s id as the parameter. We stringify the user object and consents and send them to the me handlebars template to render. In a production app, you’d want to display this a bit more nicely and maybe search for the specific fields and consents you want to display. You’d access a user’s consents exactly the same way, through the API, when determining what kind of marketing channel they’d prefer. This would typically be called in a background worker process or serverless function.

We need to create the handlebars template for this route. Create a new file in the “views” folder, called me.hbs. Add the following code to the file:

<h1>{{title}}</h1> <p>Welcome to {{title}}</p> <p> You can update your <a target="_blank" href="<YOUR_FUSIONAUTH_ACCOUNT_LINK>" >profile here</a> </p> <h2>Profile Info</h2> <p> {{profile}} </p> <h2>Consent Permissions</h2> <p> {{consents}} </p>

This is a template that has placeholders for the dump of the raw user information and the user consents.

There is also a link for the user to update their information on FusionAuth, using the custom self-service form created earlier. To update the value for <YOUR_FUSIONAUTH_ACCOUNT_LINK>, navigate to Applications in FusionAuth. Click the “View” button next to your application, and scroll down to the “Account URL” value. Copy the URL and replace <YOUR_FUSIONAUTH_ACCOUNT_LINK> in the code above with it.

Now we need to secure the route to this profile page for users that are authenticated. To help with that, we’ll use the connect-ensure-login middleware we installed earlier. Update the users route in the app.js file from:

app.use('/users', usersRouter);

to:

app.use('/users', ensureLoggedIn('/login'), usersRouter);

The ensureLoggedIn middleware checks if the user is authenticated before proceeding to the router (or following middleware). It redirects to the login page if the user is not logged in.

Testing

We are done with the coding. Type npm start at the console to start up the server. Then navigate to localhost:3000, preferably in a private tab. This ensures that your main admin login to FusionAuth is not a confounding factor while logging in.

You should see the main page looking something like this:

Clicking on “Login Here” should redirect you to your FusionAuth installation.

Clicking the “Create an account” link should render the custom registration form configured earlier. Notice that it has three steps:

Enter all the information and click “Register” at the end of the steps. You should be redirected to your Express app, with a new message on the home page:

Clicking on the “profile page” link should take you to users/me, showing two JSON objects representing your profile on FusionAuth, along with the raw data from the consents API. Notice in each consent that there is a property status. This will be either active or revoked. You can use these values when checking to send information to the user through each channel.

Clicking the “profile page” link will redirect to FusionAuth, where the user can view and update their information and consent permissions via the self-service form created earlier. Once navigated to the FusionAuth-hosted profile page, clicking on the “Edit” pencil icon button in the top right will allow the user to update their profile.

Where to next with Express and FusionAuth?

That’s the basics of our Express and FusionAuth app. The app has a fully featured authentication system, along with user consents, without the hassle and possible risks of implementing all of that code ourselves. The complete code is hosted on GitHub here.

For a production environment, you would need to do a bit more work to lock down FusionAuth. In our example, we used the default password provided with Docker for our database, left debug mode on, and ran FusionAuth locally, co-hosted with our Express application. For a safer setup, you would run FusionAuth on its own infrastructure, physically separate from the Express app, and take more care around production configuration and deployment.

You would also need to add more interesting features to this app for it to be useful. But being able to take care of the authentication, consents, and general security with just a small amount of configuration code leaves a lot more time for your application’s more useful and critical features.

Happy coding!