Forem: Mert Yerekapan

How to implement Two-Factor Authentication using Next.js, Twilio and Altogic

Mert Yerekapan — Fri, 13 May 2022 12:43:23 +0000

Introduction

This article will cover two-factor authentication basics using Next.js, Twilio, and Altogic, a Backend-as-a-Service platform using its client library. This authentication method allows users to add one more security layer to their application. Many people enable their two-factor authentication settings to increase their security using their phone numbers or authentication apps for security purposes.

You can check out the source code and demo app.

How is the two-factor authentication flow?

Users who already have an account need to set their phone number to enable two-factor authentication.
An SMS with a code is sent to the specified phone number by Altogic and Twilio.
Users verify their phone number by entering the code sent to their phone number.
Users can enable or disable the two-factor authentication setting from their profile.
When users try to sign in, if two-factor authentication is enabled, a code is sent to the specified phone number by Altogic and Twilio.
Users verify their identity by entering the code on the input on the screen.
If two-factor authentication is not enabled, they can sign in without this process.

Youtube Showcase Video

Set up the Project

This project builds on top of the complete e-mail authentication app we created previously. You can follow the tutorial to build the same app or clone the project from here and continue with the rest of the tutorial.

Twilio Integration

You need to sign up for Twilio with a free/paid trial. You need to get the Account SID and Auth Token for integration with Altogic Client Library.

If you use the free trial, you will need to take the Twilio phone number to send SMS messages to the users.

Create an Account on Twilio
Open Console
Click “Get a trial phone number” on the left-top of the Console
Copy Account SID, Auth Token, and My Twilio phone number values to the clipboard

Now, we’ve copied the configuration credentials to the clipboard. You must specify the verified phone numbers in trial accounts, which we defined as “ to number” in Altogic.

Click on the Explore Products in the left sidebar.
Be sure that Messaging and Phone Numbers products are selected.

Now you can navigate to the Verified Caller IDs page by Sidebar → Phone Numbers → Manage → Verified Caller IDs.

You should add your phone number as a Verified Caller from here.

And finally, you have to give geo permission to your phone numbers region. You can go to this page by Sidebar → Messaging → Settings → Geo permissions.

Create the models

Models define the data structure and data validation rules of your applications. A model is composed of basic, advanced, and sub-model fields. As an analogy, you can think of models as tables and fields as columns in relational databases or models as documents and fields as document properties in non-relational databases.

When we create our application, a user model is created by default. We need to add a boolean field to this user model to let users enable and disable the two-factor authentication.

To create a field via the Designer, you need to Navigate to Models view and select the model you would like to add the new field. You will be directed to the model details view.

In the model details view, select New field.
From the dropdown menu, select the Boolean that you would like to create.
In the field name, type “twoFactorAuth” and set a default value of false
Select Create

We need to create a new model called phoneVerificationCode to handle the verification code we send to users’ phone numbers. This data type will be a Transient data type meaning it is not stored in the database. We are defining it as Transient because we don’t need it after completing the verification.

To create a model via the Designer, you have two options. You can either create a model from scratch or a sample JSON document. In either case, first, you need to navigate to the Models view in designer and select +New.

After, you can pick a Model.

And create the phoneVerificationCode model. Afterward, we need to add three fields:

code field, which is an Integer.
userId field, which is an Object reference to the users model.
phoneNumber field, which is a Text field.

Create the endpoints

Endpoints are the communication channels to access the services provided in your applications, and through endpoints, you expose your application services and data to the outside world.

To create an endpoint via the Designer, you need to navigate the Endpoints view in designer and select New->Endpoint.

After clicking, you need to enter a relevant endpoint name and optionally pick a group, pick a method, specify the path and assign a service that handles the requests to the endpoint.

We can also click on the “Session required” checkbox, which enforces a need for a session when a request is made to the endpoint.

In this example, our method is “POST,” and our path is “/users/set-phone” meaning that if we send a POST request to this path, the service we define will run. We created a service by clicking “Add new service” and by naming our service, we will be created an empty service. We will design the service next.

We will create three more endpoints to verify the code while changing the phone, signing in, and implementing the particular sign-in functionality.

Create the verify code during changing phone endpoint:

Create the verify code during the sign-in endpoint:

Create the sign-in endpoint for implementing the particular 2-FA logic:

Now that we created our endpoints and services, we can start designing the services, which is the most fun part of using Altogic!

Design the Services

Building the flow of service involves three main activities.

Adding the right node from the nodes library to the service flow area.
Customizing the added node parameters using the node properties panel.
Linking the output link point of a node to the input link point of another node using relations.

First, we will implement the “Set phone number service.” We have the start node, which is used to start the execution of the endpoint handling service. It runs only once at the start of the service to trigger nodes connected to its output link point. We define a query string parameter of type text named “phoneNumber” as input for this endpoint.

Then, we check if the phone number sent is a valid phone number with the ISMOBILEPHONE() function.

If no, return an error response.

If yes, create an object of phoneVerificationCode model. For code, we generate a random number with RANDBETWEEN() function and insert the other fields from either the input or the session.

Cache the object we created so we can access it later for verifying the code. I want the code to expire after one minute, so I set the timeout value to 1 minute.

Send the SMS message to the specified phone number with the code. Here we use the Twilio credentials we obtained.

Then we return the success response. This is the final look of our service:

Next, we will implement the “Verify code in change phone service.” This service is used to verify the code when users want to change their phone numbers.

We have the start node, which is used to start the execution of the endpoint handling service. It runs only once at the start of the service to trigger nodes connected to its output link point. We define the request body structure as a single model of “phoneVerificationCode” as input for this endpoint.

Get the cached object with the phone number to check the code.

Return an error response if the cached object does not exist anymore. It means that the code is expired and no longer valid.

Check if the cached code is equal to the code sent in the “phoneVerificationCode” object.

Update the user's phone number and set the “phoneVerified” to true using the “Update Object Fields by Id” node. We need to set the updated object model to “users” and object id to the userId, and we do that by giving the userId we obtain from phoneVerificationCode object.

Then we return the success response. This is the final look of our service:

Next, we will implement the “Verify code in sign-in service.” This service is used to verify the code when users try to sign in when their two-factor authentication is enabled.

Get the cached object with the phone number to check the code.

Return an error response if the cached object does not exist anymore. It means that the code is expired and no longer valid.

Check if the cached code is equal to the code sent in the “phoneVerificationCode” object.

Return error if code is not equal to the one sent in the input.

Get the user using the “Get Single Object by Query” node. We need to set the retrieved object model to users, and our query should be this.phone==inputObject.phoneNumber to get the user with the specified phone.

If there is no user, return an error response.

If there is a user, create a user session.

Then we return the success response. This is the final look of our service:

Next, we will implement the “Sign in service.” This service is used to implement the sign-in feature. Because we want to use two-factor authentication, we can’t use the function in the client library, and we have to design it ourselves. But don’t worry, designing complex business logic in Altogic is relatively easy! :)

We have the start node, which is used to start the execution of the endpoint handling service. It runs only once at the start of the service to trigger nodes connected to its output link point. We define a query string parameter of type email named “email” and type text called “password” as input for this endpoint.

Get the user using the “Get Single Object by Query” node. We need to set the retrieved object model to users, and our query should be this.email==params.body.email to get the user with the specified email.

Return an error if there is no user with the specified email.

Use the “If-Else Condition” node to check if the emailVerified field of the user is true or not.

If the email is not verified, return an error response.

Compare the password sent with the password in the database with ECOMPARE() function. This function compares the password text in the input with the password in the database but does not expose the encrypted password. No one, including the developer, can see the user's passwords.

Return an error response if passwords do not match.

Check if the two-factor authentication of the user is enabled.

If two-factor authentication of the user is not enabled, create the user session and return it with the user data.

If enabled, create an object of phoneVerificationCode model. For code, we generate a random number with RANDBETWEEN() function and insert the other fields from the input.

Cache the object we created so we can access it later for verifying the code. I want the code to expire after one minute, so I set the timeout value to 1 minute.

Send the SMS message to the specified phone number with the code. Here we use the Twilio credentials we obtained.

Then we return the success response. This is the final look of our service:

To learn more about building the service flows, check out the documentation.

Let’s Start Coding!

Set/Change phone functionality

To enable two-factor authentication, users need to set up their phone numbers. This functionality is the same as changing the phone functionality so that we will use the same screen with some minor conditional UI changes.

We have already created the endpoint and designed the service. We need to send a request to the endpoint using Altogic Client Library using EndpointManager and the post method like altogic.endpoint.post()

SMS verify during change phone functionality

Code above runs the service for setting/changing the phone number and sending the SMS for verification code. Now, users need a screen to enter the SMS code. We have already created the endpoint and designed the service for this case. We need to send a request to that particular endpoint.

Here is the code for that:

Toggle Two Factor Authentication functionality

Users should be able to switch on and off two-factor authentication if they want to. For this, we are implementing a basic switch. We are updating the twoFactorAuth boolean field.

Sign in functionality

When users want to sign in, we will use the service we designed because we need to check if two-factor authentication is enabled and if yes, we need to send an SMS with a code. We replace the client library function with sending a request to the endpoint.

SMS verify during sign-in functionality

Code above runs the service for signing in and sending the SMS for verification code. Now, users need a screen to enter the SMS code. We have already created the endpoint and designed the service for this case. We need to send a request to that particular endpoint with code, phone number, and userId.

Here is the code for that:

Conclusion

This article covered adding the two-factor authentication method to our email authentication app using Next.js, Twilio, and Altogic Client Library. Thanks to Altogic, we can build this functionality with just a few lines of code.

You can check out the GitHub repository for other functionalities and the rest of the code. You can also clone it and build your app on top of it.

How to implement Magic Link Authentication with Next.js and Altogic

Mert Yerekapan — Thu, 05 May 2022 05:16:57 +0000

How to implement Magic Link Authentication with Next.js and Altogic

Introduction

This article will cover magic-link authentication basics using Next.js and Altogic, a backend-as-a-service platform using its client library. This authentication method allows users to sign in to the application without remembering their password.

To reduce UX friction and avoid remembering multiple passwords, some small/medium and even large organizations are moving out from the password-based authentication flow to magic authentication, depending on their risk appetite.

You can check out the source code and demo app.

Benefits

With the magic link authentication method, the user does not have to remember another password or enter it to access their account. So we can clearly understand that magic link authentication highly simplifies the login burden for users and provides a better user experience.

Disadvantages

For that authentication method, the primary condition is that the link needs to be safe and can not be able to manipulated from outside of the application. And the links should have to be used for just a few minutes and only once. So except for these conditions, a passwordless authentication seems safer than one with a password.

💡 If you know any other disadvantages that you discover or faced before, please write in the comments section, we would love to discuss and learn.

How is the magic link authentication flow in Altogic?

Users who already have an account enter their email and click the “Send magic link” button.
An email with the magic link is sent to the specified email address by Altogic.
Users click on the link in the sent email.
Altogic redirects users to specified “Redirect URL” with an access token in the query string parameter.
This access token is used to get a session token, and users are directed to their profile page.

Youtube Promo Video

You can check out the video below to see a live demonstration of our app.

Set up the project

Let’s start coding!

We already have the backend and frontend of the email authentication now. We can start implementing the magic link functionality.

Set up the magic link page

We need a page where we get the email input from the user.

Using the “altogic.auth.sendMagicLinkEmail(email)” we can send magic link mail to the specified email.

Here is the source code of the /auth/send-magic-link page:

In the end, your screen should look like this:

Magic Link Email

You can also change all of the message templates from the App settings → Authentication → Message templates view of Altogic Designer and use any HTML template you want.

Here is how to do that:

Now that we sent the email, users need to click on the link to sign in.

Redirect URL route

When users click on the link, Altogic redirects to our specified Redirect URL, which is /auth-redirect in this case.

Here in getServerSideProps, we check the query string parameters, and according to each action, we perform some actions. Here is an important part!

getAuthGrant() function either takes a session token as a parameter or uses the one in the URL.

Here, we run this code only on the server-side, so we must give the session token as the parameter.

What happens if we click on the link again?

Magic links are one-time links. If users click on the link a second time or after it expires, they get an error. This feature makes the magic link authentication method more secure.

As we can see from the URL, the access token is already used or invalid.

💡 You can directly insert the error message from the link for convenience.

Conclusion

This article added the magic link authentication method to our email authentication app using Next.js and Altogic Client Library. Thanks to Altogic, we can build this functionality with just a few lines of code.

You can check out the GitHub repository for other functionalities and the rest of the code. You can also clone it and build your app on top of it.

Complete Email Authentication with Next.js and Altogic

Mert Yerekapan — Mon, 25 Apr 2022 13:05:36 +0000

Introduction

This article will cover email-based authentication basics using Next.js and Altogic, a backend-as-a-service platform using its client library. This authentication method requires users to specify their email and passwords during sign-up. After signing up, users can log in to the application using their email and password. You can check the source code and demo app.
By default, email verification is enabled in your App settings → Authentication view of Altogic Designer. If you would like to change this, you can disable “Confirm email addresses” in the Authentication view of Altogic Designer.

How is the email authentication flow in Altogic?

Users sign up with their email and password.
A verification email is sent to the specified email address by Altogic.
Users confirm their email by clicking on the link in the sent email.
Altogic checks the token in clicked link and if valid changes the user’s email address to verified and returns an access token in the query string parameter of the redirect URL.
This access token is used to get a session token and users are directed to their profile page.

Youtube Promo Video

You can check out the video below to see a live demonstration of our app.

Set up the backend

Create an app in Altogic

First things first: To use Altogic, we need to create an app in Altogic. We can create an app in Designer easily. All you need to do is enter a name for your app.

We need envUrl and clientKey to access our environment via Altogic Client Library. envUrl is specific to each environment, and Altogic initially creates one environment for you when you create your app. Here is how to get the envUrl from environment details page.

We can get the clientKey by clicking on the App Settings button in the left-bottom corner of the Designer and clicking on the Client library keys section.

Users model

By default, Altogic creates a user model for you. You can customize it by adding different fields. Some of them are pretty advanced and customized, which is very handy.

Set up the Frontend

Install the packages

Before you start to use the npx command, make sure you have NodeJS installed in your development environment. Also, installing VSCode and some extensions might be better for faster development.
💡 You can visit https://nodejs.org/en/download/ to download.
To get started, open the terminal and create a new Next.js project.

npx create-next-app@latest

Next.js will ask you to name the project. Name it whatever you want; I will use “altogic-email-authentication” for this example. Move to the folder just created and install the Altogic Client Library.

cd altogic-email-authentication
npm i altogic

Open the project in VSCode.
Install tailwind CSS and create tailwind.config.js

npm install -D tailwindcss postcss autoprefixer
npx tailwindcss init -p

Add the paths to all of your template files in your tailwind.config.js file.

Add the following directives to your globals.css file.

Install Font Awesome to use the icons.

npm i --save @fortawesome/fontawesome-svg-core
npm install --save @fortawesome/free-solid-svg-icons
npm install --save @fortawesome/react-fontawesome
npm i @fortawesome/free-brands-svg-icons

Install cookies-next to set cookies for server-side rendering easily.

npm i cookies-next

Install @headlesui/react for styling.

npm i @headlessui/react

Update the next.config.js file to allow the Next.js Image component to load images from Altogic’s storage. "c1-na.altogic.com" value is retrieved from the envUrl which starts with c1-na.altogic.com in my case.

Set up the environment variables

Environment variables are used to secure your secret keys, reuse them in different places and reduce production mistakes. Create a .env.localfile in the root directory of your application, open the file in your editor and paste the following. You can check more about environment variables in Next.js here.

Replace YOUR-APPLICATION-ENV-URL and YOUR-APPLICATION-CLIENT-KEY with the envUrl and clientKey values you retrieved while setting up your backend.
Next, create a file to create the Altogic Client Library instance.

mkdir helpers
cd helpers
touch client.js

This creates a client.js file in the helpers directory. Open the file in your editor and paste the following.

Here, you need to enter the envUrl and clientKey. Optionally you can paste signInRedirect to redirect your users to the specified sign-in page in some cases. This works in a way that if users try to perform a session-required action while their session has been destroyed, Altogic redirects them to the signInRedirect route.

Building our components

The next step is to create the components we’ll need for our application. You can also clone our example repository and use the components right away.
First, create a components folder with the mkdir components command. Let me walk you through the components we use for our app.

Sign-in.js and Sign-up.js file in auth directory. Those are the form components we use to sign-up and sign in our users.
EmailConfirmResend.js and PasswordReset.js file in auth-redirect directory. Those are the components we will show our users when redirected to the our-domain.com/auth-redirect route.
AltogicBadge.js, Header.js and Layout.js file in layout directory. Those are the components we use for our layout throughout the app.
SessionListItem.js ,SessionList.js , ProfilePhoto.js, NameSection.js , ChangePassword.js and ChangeEmail.js file in profile directory. Those are the components we use on the profile page.
Button.js , Notification.js and ErrorMessage.js file in ui directory. Those are the components we use many times to build our UI.

In the end, your components folder should look like this:

Let’s start coding!

We have the backend and frontend setup ready. We can start integrating them now.

Some UI components we use often

It is best to separate the logic of some of the components we use frequently and put them into a different folder to reuse.
Button:

Error:

Sign up functionality with Altogic

Altogic Client Library has a built-in function for creating new users with an email and password. You can check about it more here.
altogic.auth.signUpWithEmail takes three inputs:

email (mandatory)
password (mandatory)
name (optional) The code snippet handles the form input using the signUpWithEmail function.

Our sign-up screen should look like this:

This function will create a user object in your database with the provided email, password, and optionally name field. Altogic will send an email to the user’s email address.

Redirect URL route

In Altogic, you can redirect your users to a predefined route for some actions.

When the user is successfully authenticated using an oAuth provider or a magic link, they will be redirected here.
When the email confirmation link is clicked, they are redirected to this route.
When a user changes their email, if the email confirmation setting of the app is enabled, an email is sent to them. After the user clicks it, they will be redirected to this route.
When a user recovers their password, they are redirected to this route.

You can check and edit this route from Designer like below.

Here in getServerSideProps, we check the query string parameters and according to each action, we perform some actions. Here is an important part!

getAuthGrant() function either takes a session token as a parameter or uses the one in the URL.

In the example below, Altogic sent the user an email confirmation mail. When clicked, it redirects to our specified Redirect URL, which is auth-redirect.
There are three query parameters:

status=200 indicates that Altogic managed to send me a valid token for my operation.
access_token gives us the token value I am going to use.
action=email-confirm indicates for which action I am going to use this token. In this case, it is confirming my email.

Here, we run this code only on the server-side, so we must give the session token as the parameter.

Sign in functionality with Altogic

Altogic Client Library also has a built-in function for signing in users. You can check about it more here. The code snippet handles the form input using the signInWithEmail function.

altogic.auth.signInWithEmail takes two inputs:

email (mandatory)
password (mandatory)

As you can see in the code above, we are sending a POST request to /api/login route. We are doing this to set the cookie for server-side rendering (SSR). If you are not going to use SSR, you can delete these lines.

Why do we need cookies for SSR?

One of the key features of Next.js is server-side rendering. Meaning that some of the code will run only on the server and not on the client side. But session and user information is stored on the client-side. How do we understand if we have a user authenticated when a request is made to the server? For this purpose, we need to set a cookie on the server-side when we sign in and delete it when we sign out. This way, we can check if the user is authenticated on the server-side and then perform the actions we want.
Here is the code you need to add to your api/login folder:

On any page, we can check if there is a user signed in or not. This part is needed both for route protection and fetching data special to the user with SSR.

Our sign-in screen should look like this:

How to check if there is a user authenticated via SSR?

getServerSideProps function runs every time the user makes a request. It runs only on the server, and its content is not exposed to the client. We check if a user is authenticated and redirect them to their profile or sign-in page accordingly.

Signout users

Here is the page you can redirect your users to log them out. It simply invalidates the session, clears the context, and sends a POST request to our-domain/api/logout to clear the cookies.

When we sign out, we need to delete the cookie we set on the server-side because the token value in the cookie is no longer valid.
Here is the code you need to add to your api/logout file:

Storing user information in context

The UserContext creates a context and sets the user and session property null by default. To learn more about context and how to effectively use them, read React’s documentation on context.

More features

Our example application covers more features like uploading a profile picture, managing sessions, password recovery, password change, and email change. You can check all of them in the repository. Here, I just want to show you how easily you can implement them with client library functions.

Conclusion

In this article, we built a simple yet capable email authentication app using Next.js and Altogic Client Library. Generally, building authentication is one of the most challenging parts of app development. Thanks to Altogic, we can build this functionality with just a few lines of code.
You can check out the GitHub repository for other functionalities and the rest of the code. You can also clone it and build your app on top of it.