Invite Workflow Using the Auth0 Organizations Invitation Feature

In this lab, you'll help the team at "Identiflix" - a fictitious B2C application built to connect eager students with identity experts - to build a new feature designed to fuel their growth. The new feature is a highly requested invitation capability, and you'll be leveraging the Invite workflow provided by Auth0 Organizations to reduce the amount of time and effort required to implement. As part of this work you'll learn a number of other things, including:

• How to configure your Application definition in Auth0.
• How to setup a single Auth0 Organization for B2C Invite use case scenarios.
• How to Brand the invite email so your users are confident it's from a genuine source, and
• How to integrate your B2C application with Auth0, including
  • How to trigger an Invite, as well as
  • How to handle the response when the user clicks on the Magic Link

What is Invite Workflow?

In SaaS applications, the notion of membership is not an uncommon one: membership often represents invited users for whom application access is authorized. Of course, users will need to authenticate in order to establish a context for membership, but once authenticated, if they’re on the membership list, then they’re typically allowed in 😎

Establishing a membership list, however, can often be a challenge in the world of Identity and Access Management (IAM), particularly where multiple Identity Providers - that's to say, services which authenticate a user’s identity; also known as IdPs - are used. Simply adding someone to a membership list isn’t always feasible, especially if you need to know that the person who’s being added is allowed to be there and also what they “look like” in terms of their user profile.

One solution to this problem is to use what is typically known in Auth0 as the Invite or Invitation workflow that's associated with the Auth0 Organizations feature. Using some aspect of a user’s identity (typically their email address) an invite is sent containing some sort of “magic link”. The user would be “invited” to click on the link and start the process of initial Signup/Login … becoming a bone-fide member once successfully completed.

Of course, it's important your users are confident that such an invite is from a genuine source, so leveraging Auth0's Email Template Customization capabilities is crucial for providing the brand awareness that delivers user security and peace of mind!

Lab Setup

If you've already participated in one of our other identiflix lab sessions then you will have configured your environment and downloaded the code from the GitHub repo.

If this is your first identiflix lab then you can find the instructions to download and setup the application here 😁

Update your Application in Auth0

In addition to the Auth0 Application configuration described above, you'll also need to set the Application Login URI (see here for more details). This is the URI - typically a URL - that will be used to determine where to redirect the user when Auth0 needs the application to do something as part of the login process. In this case, Auth0 will use the value you configure during creation of the "magic link" that's sent as part of the invite. Let's go ahead and configure this for your Application definition in Auth0 now:

1. From the left hand menu on the Auth0 Dashboard choose Applications, and then from the displayed list select the identiflix Lab application - or whatever name you've chosen - picking the Settings tab view.
2. Assuming you're running locally, specify the Application Login URI similar to the following:

https://identiflixdev.com:3000/api/auth/login

3. Add a corresponding entry to the Allowed Callback URLs, not forgetting to comma seperate the values:

https://identiflixdev.com:3000/api/auth/callback

4. And finally add something similar as a corresponding entry to the Allowed Logout URLs (again, not forgetting to comma seperate):

https://identiflixdev.com:3000/

5. Then Save Changes once you're done

Create an alias for localhost

As mentioned above, for security reasons Auth0 will only allow you to configure the Application Login URI using an HTTPS scheme on something other than localhost. In order to simulate this locally, the best way is to update your computer’s hosts file to augment the usual DNS lookup. First edit the hosts file specific to your environment:

Then add the following to your hosts file and save:

127.0.0.1 identiflixdev.com

Configure your Auth0 Application to Use Organizations

The Auth0 Organizations feature is typically a conerstone when it comes to integrating with a B2B SaaS application, but in this case we're also going to leverage it - along with it's associated Invite workflow - in our B2C application.

With Organizations, you can define how users log in, and also define Universal Login branding on a per-Organization basis. For our B2C use case we're going to create a single Organization, enable a Database connection for login - supporting UserID/Password and Passkey authentication - and we're going to do this via the Auth0 Dashboard (though use of the Auth0 Management API is also supported for automated provisioning scenarios).

Let's start by defining what type of users will be supported in the Auth0 Application from an authentication perspective. When using Organization you have the option to select one of three possible choices on a per-application basis:

• Individuals: the typical choice for a B2C application.
• Business Users: the typical choice for B2B applications. With this selection, all Users must log in using an organization, which must either be provided when the application redirect users to the /authorize endpoint or where the interactive organization picker is used to determine how a user should login.
• Both: which gives the flexibility to support login with or without the organizational context, and supports membership via invite workflow in either a B2B or B2C scenario.

Both is the option we're going to use, however before we do, we're going to need to disable some of the grants that were automatically enabled when the identiflix Next.js application was created, in order to enable the dialog.

1. From the identiflix Lab Application definition (or whatever yours is called) select the Organizations tab view
2. Click on Disable Grants Now to remove the unsupported grants from your application, and when prompted, confirm the operation
3. Now, in the Types of Users section, select Both, and
4. In the Login Flow section that will appear, choose the Prompt for Credentials option
5. Click on Save Changes to continue

Enabling required grants

Whilst the Client Credentials grant is not currently supported for B2B SaaS integration with the Auth0 Organizations feature, once you have all the configuration setup in the Dashboard it can be re-enabled for our B2C use case without adverse effects. Doing so will also provide an easier mechanism for accessing the Auth0 Management API functionality required to send an invite:

1. From your identiflix Lab Application definition, select the Settings tab view
2. Scroll down and expand the Advanced Settings section
3. Select the Grant Types tab and then click to enable the Client Credentials grant
4. Click on Save Changes to continue

Enabling Management API Access

We also going to need to grant our application access to the Auth0 Management API in order to initiate invitation workflow. Whilst the Principal of Least Privilege should be observed - e.g. providing access to functionaility in the Auth0 Management API that the application does not directly require - providing access to send an invite means that, in this case, it is acceptible to trade the overhead of creating a new application by enabling this single scope of operation directly:

1. Click Applications from the left hand menu on the Auth0 Dashboard, and choose APIs
2. Select the Auth0 Management API at the top of the list displayed and then select the Machine To Machine Applications tab.
3. Scroll down until you find the identiflix Lab Application definition, and then click the toggle to authorize
4. Expand the Application definition and in the Filter Permissions type:

organization_invitations

5. Select create:organization_invitations and click Update

Update the Auth0 Authentication Profile

The Authentication Profile is Auth0 - which is accessible via the Authentication option from the left hand menu on the Auth0 Dashboard - gives you access to the configuration for how users will log in to your application. For our B2C invite workflow we're going to choose Identifier First, which is the profile that works in conjunction with the Organizations feature in Auth0:

1. Click Authentication from the left hand menu on the Auth0 Dashboard, and choose Authentication Profile
2. Select Identifier First
3. Click Save

Create an Auth0 Organization

Now let's use the Auth0 Dashboard to create and then configure the Organization we're going to use to support Invite workflow:

1. From the left hand menu in the Auth0 Dashboard select Organizations
2. On the page that's displayed click Create Organization
3. Under Basic Info enter something similar to the following for the Name

identiflix_lab

4. Display Name provides a friendly name, which can contain regular typing characters (such as a space). You could specify something such as identiflix Lab though this is entirely optional
5. Click Add Organization

Enabling a Connection

We need to tell Auth0 what Connection definition(s) will be enabled for the Organization. This effecitvely tells Auth0 via which IdPs - which Identity Providers - our invited user will authenticate. For the purpose of this lab we're going to enabled the default out-of-box Username-Password-Authentication connection, so:

1. Click Enable Connections
2. Select the Username-Password-Authentication Connection from the list
3. Click Enable Connection

Defining Connection Membership

At this point you'll be presented with a number of options and you can leave these set to their default values. This page primarily deals with Membership and how a member is registered to an Organization. In our case, we only want those folks who have been invited to be added to our members list, and so the default options prevent anyone from joining who is not invited! Click on Back to identiflix_lab (or whatever you named your Organization) to continue.

Branding

From the Overview tab you can change aspects of the Auth0 Universal Login branding associated with the Organization. In a B2B SaaS scenario you would typically leverage this to provide per-subscriber branding of the vaious Auth0 dialogs associayed with Universal Login. In this scenario, you could use this to provide specific branding on the signup experience for invited members. We'll leave this for now, but you can always experiement further at your leisure.

Branding the Auth0 User Invitation Email template

Branding is also an important aspect from a trust perspective - especially when it comes to someone clicking on a link in an email. Auth0 provides a number of options for Email Template Customization and you specifically use the User Invitation email template to apply any customizations you require. We won't go into any further detail as part of this lab, but you can always experiement further at your leisure.

Integrate support for Auth0 Organization Invite

Now let's turn our attention to the code and modify it to add invite workflow

Add additional modules

First we'll update the installed modules to include the auth0 library. This includes the ManagementClient via which we will access the Auth0 Management API, and installing this now will likely prevent your editor from complaining about missing modules/types. Change into the project directory and from the command line run the following npm command:

npm install auth0

Modify app/actions.ts

We'll start by modifying the app/actions.ts file which contains the sendInvite function, which will enable us to send an invitation to an email address of our choice. Open the file in you editior of choice and then add the following lines:

import { getSession } from "@auth0/nextjs-auth0";
import { ManagementClient } from "auth0";

Next scroll down to the sendInvite function and replace everying after the //FIXME: with the following lines of code; this is essentially going to use the installed auth0 library to access the Auth0 Management API used to create and send the invite:

if (
  process.env.AUTH0_MANAGEMENT_API_DOMAIN &&
  process.env.AUTH0_ORGANIZATION_ID &&
  process.env.AUTH0_CLIENT_SECRET &&
  process.env.AUTH0_CLIENT_ID
) {
  // https://auth0.github.io/node-auth0/classes/management.ManagementClient.html
  const managementClient = new ManagementClient({
    domain: process.env.AUTH0_MANAGEMENT_API_DOMAIN,
    clientId: process.env.AUTH0_CLIENT_ID,
    clientSecret: process.env.AUTH0_CLIENT_SECRET,
  });

  try {
    const session = await getSession();

    // https://auth0.github.io/node-auth0/classes/management.OrganizationsManager.html#createInvitation
    await managementClient.organizations.createInvitation(
      {
        id: process.env.AUTH0_ORGANIZATION_ID,
      },
      {
        client_id: process.env.AUTH0_CLIENT_ID,
        invitee: {
          email,
        },
        inviter: {
          name: session?.user["name"] || "",
        },
      },
    );
  } catch (error) {
    console.error("failed to create Invitation", error);
    return {
      success: false,
      message: "Failed to create Invitation.",
    };
  }

  return {
    success: true,
    message: "Invitation sent",
  };
} else {
  return {
    success: false,
    message: "Environment not configured",
  };
}

Modify app/api/auth/[auth0]/route.ts

Now we're going to modify the out-of-box Auth Next.js SDK integration to add the code required to handle the user clicking on the invite link. The modifications enable passing of the parameters contained in the invite link, and involves replacing the code starting export const GET with the block of code detailed below:

export const GET = handleAuth({
  signup: handleLogin({ authorizationParams: { screen_hint: "signup" } }),
  login: handleLogin((request) => {
    if (request.url) {
      const url = new URL(request.url);
      const searchParams = url.searchParams;
      const organization = searchParams.get("organization");
      const invitation = searchParams.get("invitation");

      if (organization && invitation) {
        return {
          authorizationParams: {
            organization,
            invitation,
          },
        };
      }
    }
    return {};
  }),
});

Update the application .env

As mentioned previously, for security reasons Auth0 will only allow you to configure the Application Login URI (the URI used by the Auth0 Organization Invitation workflow) using an HTTPS scheme on something other than localhost. In the Lab Setup section we updated Auth0 configuration to use the identiflixdev.com domain, and also aliased this domain to localhost. Now we need to update the definition(s) in the .env files(s) associated with the application itself in order to reflect those changes:

1. First update the AUTH0_BASE_URL with the following

https://identiflixdev.com:3000

2. Add the following lines to the end of the file, where the value for AUTH0_MANAGEMENT_API_DOMAIN can be found as part of the API Audience associated with the Auth0 Management API, and the value for AUTH0_ORGANIZATION_ID is the Identifier associated with the Auth0 Organization you previously created. Both of these values can be obtained via the Auth0 Dashboard, and some example values have been provided below so that you can see how these need to be configured:

# Domain via which to access the Auth0 Management API
AUTH0_MANAGEMENT_API_DOMAIN = 'dev.us.auth0.com'
# Organization via which to issue invites
AUTH0_ORGANIZATION_ID = 'org_foGCPM38GzPgx6Px'

3. Save your changes

Sending an invitation

From the the project directory, you should now be able to run the application using the following command:

Now perform the following steps:

1. Click Log In; I've configured my tenant to use Google social login so that you can see a distinct difference during the invitation workflow
2. Using the Invite your friends option available on the home page, enter the desired email address and click Send Invite
3. Confirm that you see the message saying the invitation has been sent 🎉

Receiving an invitation

At some point the recipient of the invite will recieve an email, and this will contain the magic link which they'll use to sign up. Clicking on the magic link will redirect the user to Auth0 where they can perform signup, eventually being logged in to the application to enjoy whatever experience you provide 🤗

Recap

In this lab you've learned how to use the Auth0 Organizations - primarily designed for B2B SaaS applications - to implement Invite workflow into your B2C application. As part of that process, you've also learned:

• How to create and configure an Auth0 Organization
• How to configure an Auth0 Application to use Auth0 Organizations
• How to use the Auth0 Management API
• How to brand the user experience

For more great developer hints and tips, don't forget to explore the other available Labs, and also sign up to the Auth0 Zero Index newsletter when you have the chance!

Report an issue

Give us feedback