Ratelimiting OTP endpoints

Understanding OTP

A One-Time Password (OTP) is a unique code valid for only one login session or transaction. It adds an extra layer of security by preventing fraudulent access to your accounts, even if someone else knows your password. You've likely encountered OTPs many times. For instance, when logging into your bank account from a new device, you may receive an OTP via SMS or email, which you must enter to verify your identity. Another typical example is the login flow, where instead of entering a password, an OTP is sent to your email.

Without ratelimiting, an attacker could try several OTPs in quick succession in a so-called 'brute force attack' to find the right one to gain access to an account.

By limiting the number of OTP attempts within a specific timeframe, it becomes practically impossible for an attacker to guess the right OTP before it expires.

Implementing ratelimiting

Prerequisites

• Unkey account
• Unkey root key with permissions create_namespace, limit

If you prefer, you can use our example here and skip the entire tutorial below. Also, if you want to see it live, you can see an implementation below using Unkey and Resend here

Before we begin with the tutorial, it should be stated that OTP implementations will have two separate requests: sending the OTP via email or SMS and verifying the request.

Let’s start with the sending of an OTP. Below is an insecure OTP implementation with a fake email that sends a random 6-digit code to the user via a next.js server action.

1"use server";
2import { randomInt } from "crypto";
3
4export async function sendOTP(formData: FormData) {
5  try {
6    const email = formData.get("email") as string | null;
7    if (!email) {
8      return {
9        success: false,
10        error: "Email was not supplied, please try again",
11        statusCode: 400,
12      };
13    }
14    const otp = randomInt(100000, 999999).toString();
15
16    const { data, error } = await emails.send({
17      from: "james@unkey.com",
18      to: email,
19      subject: "OTP code",
20      text: `Your OTP code is ${otp}`
21    });
22    // handled error
23    if (error) {
24      console.error(error);
25      return { success: false, error: "Failed to send email", statusCode: 500 };
26    }
27    return {
28      success: true,
29      statusCode: 201,
30    };
31    //catch
32  } catch (e) {
33    return { success: false, error: "Failed to send email", statusCode: 500 };
34  }
35}

Adding ratelimiting to sending an OTP

First, you’ll need to install the @unkey/ratelimit package to your project and then add the following imports.

1import { Ratelimit } from "@unkey/ratelimit";
2import { headers } from "next/headers";

We will use the headers to retrieve the IP of the requester and use that as an identifier to limit against. Now we need to configure the ratelimiter

1const unkey = new Ratelimit({
2  rootKey: process.env.UNKEY_ROOT_KEY,
3  namespace: "otp-send",
4  limit: 2,
5  duration: "60s",
6})
7
8export async function sendOTP(formData: FormData) {
9  // sending OTP logic

The above code will configure a new namespace named otp-send if it doesn’t exist and limit the requests to two per minute. Of course, any number of attempts, but two emails per minute should suffice for the end user.

Now that we have our ratelimiter configured, we can modify the request to first retrieve the IP address; this will check for both the forwarded IP address and the real IP from the headers. We will use the forwarded IP first and fall back to the real IP.

1export async function sendOTP(formData: FormData) {
2  try {
3    // check for forwarded
4    let forwardedIP = headers().get("x-forwarded-for");
5    // check for real-ip
6    let realIP = headers().get("x-real-ip");
7    if(forwardedIP){
8      forwardedIP = forwardedIP.split(/, /)[0]
9    }
10    if (realIP) realIP = realIP.trim();
11    // sending logic below

Now we have access to an identifier, and we can run our rate limit against it. Add the following code before checking if the user has provided an email.

1const { success, reset } = await unkey.limit(
2      forwardedIP || realIP || "no-ip",
3    );
4    const millis = reset - Date.now();
5    const timeToReset = Math.floor(millis / 1000);
6		// if this is unsuccesful return a time to reset to the user so they know how long to wait
7    if (!success) {
8      return {
9        success: false,
10        error: `You can request a new code in ${timeToReset} seconds`,
11        statusCode: 429,
12      };
13    }
14
15    const email = formData.get("email") as string | null;
16    //shortened for tutorial.

You’ll notice that we check for forwardedIP and then the realIP, and finally, if nothing is available, we will use no-ip for the fallback. This endpoint is now protected; a user can send two requests per minute. Below is a demo of how you could present this to the user:

Ratelimiting the OTP verification

The endpoint that verifies an OTP has more potential for brute force attacks; sending codes down with no restriction will give a bad actor plenty of time to try numerous codes to get the right one.

This is where the flexibility of ratelimiting for Unkey can come into play while it is similar to the above server action. For example

1export async function verifyOTP(prevState: any, formData: FormData) {
2  try {
3    // check for forwarded
4    let forwardedIP = headers().get("x-forwarded-for");
5    // check for real-ip
6    let realIP = headers().get("x-real-ip");
7    if (forwardedIP) {
8      forwardedIP.split(/, /)[0];
9    }
10    if (realIP) {
11      realIP = realIP.trim();
12    }
13
14    const code = formData.get("code") as string | null;
15
16    if (!code) {
17      return {
18        success: false,
19        error: "Code was not supplied, please try again",
20        statusCode: 400,
21      };
22    }
23
24    const { success, reset } = await unkey.limit(
25      forwardedIP || realIP || "no-ip",
26    );
27    const millis = reset - Date.now();
28    const timeToReset = Math.floor(millis / 1000);
29
30    if (!success) {
31      return {
32        success: false,
33        error: `You have been rate limited, please wait ${timeToReset} seconds and try entering a new code`,
34        statusCode: 429,
35      };
36    }
37    // Handle verification of your OTP

You can set the limits and namespace to be different, allowing you to be more restrictive and keep all your analytical data separated, for example.

1const unkey = new Ratelimit({
2  rootKey: process.env.UNKEY_ROOT_KEY!,
3  namespace: "otp-verify",
4  limit: 2,
5  duration: "30s",
6});

This operation will allow a user to try twice every 30 seconds before it ratelimits the operation for the IP. Below is an example of how this could look in your application from the example code.

Best Practices in Rate Limiting OTP

Implementing rate limiting is one thing, but ratelimiting effectively requires following best practices. Here are some tips:

• Set reasonable limits: Your users should have enough attempts to enter their OTP correctly, but not so many that an attacker could guess.
• Educate your users: Make sure your users understand why they're being blocked from logging in after too many attempts and how long they have to wait before they can try again.
• Monitor and adjust: Regularly review your system's performance and adapt your limits as needed.

These practices enhance the security and efficiency of OTPs while maintaining a positive user experience.

You can read more about Unkey’s Ratelimiting our documentation, you can see the demo of this in action and test what happens when you go over limits.