Enterprise-ready auth that is secure by default, truly multi-tenant, and ungated for small businesses.
"Invotastic for Business" is a multi-tenant demo app that serves other companies as its customers. This repo utilizes a "Backend Server" OAuth2 client type. The backend server technology here is NextJS, and the router type is the App Router. It demonstrates both how to protect API routes as well as getServerSideProps() function.
Disclaimer: Invotastic for Business is not a real-world application and cannot be used to send invoices to real people.
You can start up the Invotastic for Business demo application in a few simple steps.
First thing is first: make sure you sign up for an Wristband account at https://wristband.dev.
After your Wristband account is set up, log in to the Wristband dashboard. Once you land on the home page of the dashboard, click the button labelled "Add Demo App". Make sure you choose the following options:
- Step 1: App Type - B2B
- Step 2: Subject to Authenticate - Humans
- Step 3: Client Framework - NextJS (App Router)
- Step 4: Domain Format - Choosing
Localhostis fastest to setup. You can alternatively chooseVanity Domainif you want a production-like experience on your local machine for tenant-specific vanity domains, but this method will require additional setup.
Upon completing the demo application setup, you will be prompted with values that you should copy into the environment variable configuration for this demo repository, which is located in .env.local. Replace the following values:
APPLICATION_DOMAINDOMAIN_FORMATCLIENT_IDCLIENT_SECRET
Make sure you are in the root directory of this repository.
Now install all dependencies:
npm install
The server will start up on localhost with port 6001.
npm run dev
You can also build and run the production mode:
npm run build
npm start
Alternatively, if you choose to use custom domains for the demo app, then the server will start up on business.invotastic.com with port 6001. You can run the following command:
npm run dev-vanity-domain
You can also build and run the production mode:
npm run build
npm run start-vanity-domain
Now that Invotastic for Business is up and running, you can sign up your first customer on the Invotastic for Business Signup Page at the following location:
http://{application_vanity_domain}/signup, where{application_vanity_domain}should be replaced with the value of the "Application Vanity Domain" value of the Invotastic for Business application (can be found in the Wristband Dashboard by clicking the Application Details side menu of this app).
This signup page is hosted by Wristband. Completing the signup form will provision both a new tenant with the specified tenant domain name and a new user that is assigned to that tenant.
For reference, the home page of this Inovtastic for Business app can be accessed at the following locations:
- Localhost domain format: http://localhost:6001/
- Vanity domain format: http://{tenant_domain}.business.invotastic.com:6001/, where
{tenant_domain}should be replaced with the value of the desired tenant's domain name.
Users of Invotastic for Business can access the Invotastic for Business Application-level Login Page at the following location:
http://{application_vanity_domain}/login, where{application_vanity_domain}should be replaced with the value of the "Application Vanity Domain" value of the Invotastic for Business application (can be found in the Wristband Dashboard by clicking the Application Details side menu of this app).
This login page is hosted by Wristband. Here, the user will be prompted to enter their tenant's domain name for which they want to log in to. Successfully entering the tenant domain name will redirect the user to the tenant-level login page for their specific tenant.
Users also have the option here to execute the Forgot Tenant workflow and entering their email address in order to receive a list of all tenants that they belong to.
If users wish to directly access the Invotastic Tenant-level Login Page without having to go through the application-level login, they can do so at the following locations:
- Localhost domain format: http://localhost:6001/api/auth/login?tenant_domain={tenant_domain}, where
{tenant_domain}should be replaced with the value of the desired tenant's domain name. - Vanity domain format: http://{tenant_domain}.business.invotastic.com:6001/api/auth/login, where
{tenant_domain}should be replaced with the value of the desired tenant's domain name.
This login page is hosted by Wristband. Here, the user will be prompted to enter their credentials in order to login to the application.
The NextJS server is responsible for:
- Storing the client ID and secret.
- Handling the OAuth2 authorization code flow redirections to and from Wristband during user login.
- Creating the application session cookie to be sent back to the browser upon successful login. The application session cookie contains the access and refresh tokens as well as some basic user info.
- Refreshing the access token if the access token is expired.
- Orchestrating all API calls from the React frontend to both Wristband and the Invotastic backend data store.
- Destroying the application session cookie and revoking the refresh token when a user logs out.
API calls made from React to the NextJS server pass along the application session cookie with every request. The NextJS server peforms the following actions on all API route handlers and getServerSideProps() function calls:
- Ensuring the user's authenticated session is still there
- Validating and refreshing the access token (if necessary)
- "Touching" the application session cookie
Warning
The NextJS middleware is the only place where token refreshing occurs.
It is also important to note that Wristband hosts all onboarding workflow pages (signup, login, etc), and NextJS will redirect to Wristband in order to show users those pages.
Within the demo app code base, you can search in your IDE of choice for the text WRISTBAND_TOUCHPOINT. This will show the various places in both the React frontend code and NextJS server code where Wristband is involved. You will find the search results return one of a few possible comments using that search text:
/* WRISTBAND_TOUCHPOINT - AUTHENTICATION */- Code that deals with an authenticated user's application session. This includes managing their application session cookie and JWTs, OAuth2-related endpoints for login/callback/logout, API routes and SSR pages for validating/refreshing tokens, and React context used to check the user's authenticated session./* WRISTBAND_TOUCHPOINT - AUTHORIZATION */- Code that checks whether a user has the required permissions to interact with Invotastic-specific resource APIs or can access certain application functionality in the UI./* WRISTBAND_TOUCHPOINT - RESOURCE API */- Code that interacts with any Wristband-specific resource APIs or workflow APIs that are not related to authentication or authorization directly. For example, it could be an API call to update the user's profile or change their password.
If you choose to use vanity domains as the domain format for the demo application, you will need to install a local DNS server to provide custom configurations. This configuration forces any requests made to domains ending with .business.invotastic.com to get routed to your localhost. This configuration is necessary since all vanity domains that get generated when running the demo application locally will have a domain suffix of *.business.invotastic.com. Therefore, the above setting will force those domains to resolve back to your local machine instead of attempting to route them out to the web.
The goal is the following mapping:
business.invotastic.com => 127.0.0.1.
Here are some options which you can use, depending on your operating system:
This demo app is leveraging the Wristband nextjs-auth SDK for all authentication interaction in the NextJS server. Refer to that GitHub repository for more information.
Reach out to the Wristband team at support@wristband.dev for any questions regarding this demo app.