Welcome to your new app
Sign up for an account to get started
Magic link has expired
}
if (verified) {
return Signed in on other tab
}
return (
)
```
That’s it for the sign up page. As we specified a redirect URL above in the submit method, we also need to handle that logic.
### Setting Up the Verification Page
To complete the magic link flow, we need to perform the verification that will be the final decision between authentication or denial.
1. Start by creating a new folder `verification` in the `app` folder (so, `app/verification`).
2. Create a new file `page.tsx` inside the folder (so, `app/verification/page.tsx`).
3. Import the dependencies:
```jsx
import { MagicLinkErrorCode, isMagicLinkError, useClerk } from '@clerk/nextjs'
import React from 'react'
```
4. Next, create a functional component for the page and the hooks:
```jsx
function Verification() {
const [verificationStatus, setVerificationStatus] = React.useState('loading')
const { handleMagicLinkVerification } = useClerk()
}
```
5. Now, we’ll use the `useEffect` hook from React to perform the flow verification.
```tsx
React.useEffect(() => {
async function verify() {
try {
await handleMagicLinkVerification({
redirectUrl: 'https://redirect-to-pending-sign-up',
redirectUrlComplete: 'https://redirect-when-sign-up-complete',
})
// If we're not redirected at this point, it means
// that the flow has completed on another device.
setVerificationStatus('verified')
} catch (err: any) {
// Verification has failed.
let status = 'failed'
if (isMagicLinkError(err) && err.code === MagicLinkErrorCode.Expired) {
status = 'expired'
}
setVerificationStatus(status)
}
}
verify()
}, [])
```
The verification will happen on the page load, hence the `useEffect` hook.
6. Finish it off with some conditional rendering again:
```jsx
if (verificationStatus === 'loading') {
return Loading...
}
if (verificationStatus === 'failed') {
return Magic link verification failed
}
if (verificationStatus === 'expired') {
return Magic link expired
}
return Successfully signed up. Return to the original tab to continue.
```
### Testing the Magic Link Flow Integration
After writing down the code, let’s test the magic flow integration by starting up the Next.js app with the following command:
```sh
npm run dev
```
After the app has started, navigate to `http://localhost:3000` in your browser. In the input area presented, enter a valid email address on which you will receive a magic link.
Then, press **Sign up with magic link button**. Shortly, an email from Clerk will arrive with the magic link for signing up.
If the verification is successful, you will be presented with a confirmation message.
## Implementing OAuth in Next.js Using Clerk
OAuth stands as a cornerstone in modern authentication, allowing users to securely log in using third-party accounts without sharing passwords.
When integrated effectively, it can transform the user authentication experience, making it both swift and secure.
In this section, we will delve into the intricacies of setting up OAuth, harnessing the utility of Clerk.
### Setting Up Social Connection in Clerk Dashboard
To enable a social connection provider, go to the [Clerk Dashboard](https://dashboard.clerk.com), select your **Application**, and navigate to **User & Authentication >** **Social Connections.** Social connection configuration consists of the following steps:
1. Enable the providers you want to use.
2. (production instances only) Enter your OAuth credentials (Client ID and Client Secret) for each provider
3. (production instances only) Copy the `Authorized redirect URI` from the Clerk Dashboard to the provider's app configuration.
Clerk supports multiple providers, but for the purposes of this guide we will enable social connection with **Google**.
In development, after applying these changes, you're good to go! To make the development flow as smooth as possible, Clerk uses pre-configured shared OAuth credentials and redirect URIs.
Using shared OAuth credentials should not be treated as secure and you will be considered to operate under Development
mode. For this reason, you will be asked to authorize the OAuth application every single time. Also, they are not
allowed for production instances, where you should provide your own instead.
### Creating the Social Sign Up Page
You can start with a blank sign-up page (`app/sign-up/[[…sign-up]]`), described above in the section **Implementing Magic Links in Next.js Using Clerk**.
1. Import the dependencies:
```jsx
'use client'
import { useSignIn } from '@clerk/nextjs'
import { OAuthStrategy } from '@clerk/nextjs/server'
```
2. Create a functional component with some hooks:
```jsx
export default function SignInOAuthButtons() {
const { signIn } = useSignIn()
}
```
3. Next, create a method that will handle the single-sign on (SSO) process:
```tsx
const signInWith = (strategy: OAuthStrategy) => {
if (signIn) {
return signIn.authenticateWithRedirect({
strategy,
redirectUrl: '/sso-callback',
redirectUrlComplete: '/',
})
}
}
```
4. And finish it off with rendering a simple button for signing up:
```jsx
return (
Your Profile
Welcome, {user.username}!
{!isLoggedIn ? (
) : (
)
}
export default AuthForm
```
In this component, we have a form with fields for username and password, and two buttons for signup and login. When either button is clicked, the `handleSubmit` function is called with the corresponding path. If the request is successful, we update the `isLoggedIn` and `user` states, which will cause the `Profile` component to be rendered.
So the user sees this (very simple) form:
If they sign up/log in correctly, they get to their profile page:
On the backend, we can see the new user in our database in Supabase, with their hashed and salted password:
### Extra security
This is a basic example and does not handle all the edge cases you might need to cover in a production app, such as:
- Checking for unique usernames or emails during signup. For instance, the hashing and database retrieval depends on unique usernames.
- Handling password resets.
- Adding email verification.
You can check whether a username exists by running an additional query on the database before you try and select the user:
```jsx
export default async function signup(req, res) {
if (req.method === 'POST') {
const { username, password } = req.body
try {
// Check if a user with the same username already exists
const userExists = await pool.query('SELECT username FROM users WHERE username = $1', [
username,
])
if (userExists.rows.length > 0) {
res.status(409).json({ status: 'Error', message: 'Username already exists' })
return
}
// Hash the password
const hashedPassword = await bcrypt.hash(password, 10)
// Store the username and hashed password in the database
const result = await pool.query(
'INSERT INTO users(username, password) VALUES($1, $2) RETURNING *',
[username, hashedPassword],
)
// If user is created successfully, return a success message
res.status(201).json({ status: 'Created', user: result.rows[0] })
} catch (error) {
res.status(500).json({ status: 'Error', message: error.message })
}
} else {
res.status(405).json({ status: 'Method Not Allowed' })
}
}
```
Here, you’ll get an error message if the user already exists.
Handling password resets and email verification are much more difficult. To handle password resets, you typically need to do the following:
- Generate a unique token for the password reset request.
- Associate this token with the user in your database, and set an expiry time for it.
- Send an email to the user with a link containing this token.
- When the user clicks the link, verify the token and its expiry time.
- If the token is valid, allow the user to enter a new password.
Email verification is similar, but instead of adding a new password at the end, you’ll have a verified boolean on the user that you set to true.
We also haven’t added any ability to force stronger passwords on users. You can do that through using a library such as the validator library. The validator library provides a collection of string validation and sanitization methods, simplifying data validation tasks in the server side, client side, or even for data stored in the database:
```jsx
import bcrypt from 'bcrypt'
import validator from 'validator'
import pool from '../../utils/db'
export default async function signup(req, res) {
if (req.method === 'POST') {
const { username, password } = req.body
// Validate the password
if (
!validator.isStrongPassword(password, {
minLength: 8,
minLowercase: 1,
minUppercase: 1,
minNumbers: 1,
minSymbols: 1,
returnScore: false,
})
) {
res.status(400).json({
status: 'Error',
message: 'Password does not meet complexity requirements',
})
return
}
try {
const hashedPassword = await bcrypt.hash(password, 10)
const result = await pool.query(
'INSERT INTO users(username, password) VALUES($1, $2) RETURNING *',
[username, hashedPassword],
)
res.status(201).json({ status: 'Created', user: result.rows[0] })
} catch (error) {
res.status(500).json({ status: 'Error', message: error.message })
}
} else {
res.status(405).json({ status: 'Method Not Allowed' })
}
}
```
Here we can set that the password must have eight characters and one uppercase letter, one lowercase, one number, and one symbol.
There is a lot to think about to just do the basics of password authentication. Don’t want to do all that?
## Using Clerk with Next.js for password authentication
Clerk allows you to quickly and easily add password [authentication to Next.js](/nextjs-authentication) and has both client and server side components.
Before we get to the code, we first want to set up our application to use email and password authentication in the Clerk dashboard. Head to your dashboard and select “Email, Phone, Username” under the “User & Authentication” menu. Make sure email is selected:
You can see you can make this required and used for sign-in, which is what we want here. We can also, with a quick toggle rather than dozens of lines of JavaScript, say that we want email verification.
Then, in the same menu, find the “Authentication factors” options and select “Password.” Again here you can easily select to force the user to use a more secure password:
Now we can start with the code. Let’s create a new Next.js app:
```
npx create-next-app@latest clerk-auth
cd clerk-auth
```
Now we can install Clerk:
```
npm install @clerk/nextjs
```
Next, we want to create our environment variables for our Clerk API keys and [routes](/docs/nextjs/api-routes). Create a `.env.local file` in the root directory and add your keys and these routes (that we’re going to create in a moment):
```
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_****
CLERK_SECRET_KEY=sk_test_****
NEXT_PUBLIC_CLERK_SIGN_IN_URL=/signin
NEXT_PUBLIC_CLERK_SIGN_UP_URL=/signup
NEXT_PUBLIC_CLERK_AFTER_SIGN_IN_URL=/
NEXT_PUBLIC_CLERK_AFTER_SIGN_UP_URL=/
```
With the keys and routes in place, we can add wrapper. This provides an active session and user context to Clerk’s hooks and other components. We want to wrap the entire to enable the context to be accessible anywhere within the app, so we put it in our `_app.jsx` file:
```tsx
import { ClerkProvider } from '@clerk/nextjs'
import type { AppProps } from 'next/app'
function MyApp({ Component, pageProps }: AppProps) {
return (
Your page's content can go here.
)
}
```
Now when we `npm run dev`, we’ll get the Clerk sign in modal:
As we don’t have an account, we’ll switch to the sign up option:
We can then enter our email address and password. We have email verification turned on, so we have to go and click the link in our email. After that we’ll be redirected to our content:
## Easier passwords in Next.js
That’s it. You now have password authentication set up with the necessary security features. Clerk offers custom [password flows](/docs/authentication/custom-flows/password) so you can design the sign in flow for your app as you want
People expect passwords on their sites. They aren’t going anywhere soon. So if you are creating a new site and want password authentication, use a well-designed library or service rather than creating your own–you and your users will be grateful.
---
# Exploring the Intricacies of OTP Authentication in Next.js
URL: https://clerk.com/blog/otp-authentication-nextjs.md
Date: 2023-07-24
Category: Guides
Description: Learn how one-time passwords work, best practices for using OTPs in authentication, and how to implement OTPs in Next.js.
Passwords aren’t great. They’re often weak, reused, and need to be stored indefinitely making them susceptible to attacks and leaks. [have i been pwned?](https://haveibeenpwned.com) tells me passwords associated with just one of my email addresses have been leaked 18 times, and I have over 800 individual passwords stored in my password manager.
This is why [magic links](/blog/magic-links), [SSO](/blog/social-sso-in-next-js), and one-time passwords (OTPs) are becoming standard authentication methods. They provide better or additional security for your users.
Here we’re going to look at OTPs. One-time passwords are a great option for improving the security of your application. Let’s go through exactly what one-time passwords are, how they can improve the security of your application, the best practices for using them in authentication, and how you can [implement OTPs in Next.js](/features/email-sms-passcodes-otp).
## What is a one-time password?
OTP or One-Time Password authentication is a method in which a unique code is sent to a user's device and the user enters this code into an application to verify their identity. It’s valid for only one login session and usually time-limited.
There are two ways OTPs are implemented:
1. As the main factor for logging in a user. If you don’t want to use any username/password combinations in your authentication flow, you can send a one-time password for log in. You can also use it as an alternative to username/password. This is not particularly common, but can be seen on sites such as local social networking site Nextdoor.
2. As an additional step in [multi-factor authentication (MFA)](/docs/custom-flows/mfa#multi-factor). After a user has logged in with their username/password or another authentication provider (such as Google, Twitter, or GitHub), they are then sent an OTP to a registered email address or phone number as a secondary layer of security for applications. This second option is much more common.
You’d think that one-time passwords would be long and complicated like the suggested passwords from a password manager. But because they are transient in nature and rarely subject to dictionary or brute force attacks, they can be much simpler. OTPs can have different formats, but they usually consist of a series of alphanumeric characters or purely numeric characters. The length of OTPs can vary, but a common format is a 6 or 8-digit numeric code.
The choice between numeric and alphanumeric OTPs depends on the context and requirements. Numeric OTPs can be easier to enter, especially on mobile devices, which makes them a popular choice for SMS-based OTPs. However, alphanumeric OTPs provide a larger possible combination set for the same number of characters, which can be more secure against brute-force attacks.
There are six main steps in the OTP flow:
1. **Trigger**. The user initiates the OTP process. This could be a login attempt, a transaction verification, or any other scenario where identity needs to be confirmed.
2. **OTP generation**. The server generates an OTP. This is typically a random string or number that is time-limited.
3. **OTP delivery**. The generated OTP is sent to the user through a predetermined method. This could be an SMS to their phone, an email to their registered email address, or generated in a hardware token or software app, such as Google Authenticator.
4. **User input**. The user receives the OTP and enters it into the application.
5. **OTP verification**. The server then verifies the OTP. The server also verifies that the OTP is used within the allowed time period, and hasn't been used before.
6. **Authentication**: If the OTP is verified, the server authenticates the user and allows them to proceed. If the OTP is incorrect or expired, the server rejects the request.
Though this is only six steps, there are a lot of moving parts in OTP use. You need extra frontend UI design and logic to handle the OTP inputs; you need to integrate a delivery mechanism such as SMS, email, or an authenticator app; you need extra authentication logic to handle OTP errors; and you need the OTP generation and verification logic as well.
There are several ways to generate and verify an OTP:
- **Time-Synchronized**: In this method, the OTP is generated by applying a cryptographic hash function to a shared secret and the current time, typically measured in intervals of 30 seconds. The Google Authenticator app uses this method.
- **Counter-Based**: Here, the OTP is generated by hashing a shared secret with a counter which increments with each new OTP.
- **Algorithm-Based**: In this method, a mathematical algorithm is applied to the previous password to generate the new one.
If a time-based or counter-based OTP was used, the server repeats the same OTP generation process during verification and checks if the received OTP matches the one it generated.
These algorithms aren’t easy to implement. As you are dealing with an authentication factor, there are specific designs that you must use and RFCs that you must follow, such as this one for [Time-Based OTPs](https://datatracker.ietf.org/doc/html/rfc6238)**.** This is the biggest challenge around building your own one-time password (or any authentication) system–implementation.
## The security benefits (and challenges) of OTPs
You can quickly see the complexity involved in setting up OTP authentication. But doing so is worth it as they provide two key security benefits.
### Risk mitigation
The mitigation of risk with OTPs comes from two different avenues.
The first is mitigating the risk associated with static passwords. Traditional static passwords, if stolen, provide ongoing access until they are changed. OTPs are dynamic and expire after a single use or after a short period of time, limiting the potential damage if they are intercepted or stolen. Another problem is users reusing the same password across multiple services. If one service is compromised, all accounts using the same password are at risk. OTPs eliminate this risk because they are unique for each login session.
The second is the reduction of attack vectors. Because OTPs are typically time-limited, it makes brute-force attacks infeasible. An attacker doesn't have the time to try all possible combinations before the password expires. They also help with phishing. Even if a user is tricked into entering their OTP into a phishing site, the attacker can't reuse that OTP to gain future access to the account.
Additionally, since an OTP is valid for only one login session or transaction, it cannot be reused, preventing replay attacks. In a replay attack, an attacker tries to reuse a password that was intercepted in a previous session. However, if there's a flaw in the system's design where the OTP doesn't expire immediately after use or isn't time-bound, there's a possibility for replay attacks.
### Identity security and verification
OTPs also play a significant role in enhancing identity security and verification processes. They provide an additional layer of protection beyond traditional static passwords, aiding in the confirmation of a user's identity in several ways:
- OTPs are often used as part of a two-factor authentication process. In addition to a traditional username and password (something the user knows), the user must enter an OTP (something the user has, typically their mobile device). This confirms that the user has access to a specific device (like a phone) that is associated with the account, verifying the identity of the user.
- OTPs are commonly used in financial transactions or account changes to verify the identity of the user making the transaction. For example, when conducting a bank transfer or changing account details, an OTP might be sent to the registered mobile number or email address. The user enters the OTP to confirm the transaction, verifying that they are the account holder.
- OTPs are often used in password recovery processes to verify the user's identity. The service sends an OTP to the user's registered email address or mobile number, which the user then enters to verify their identity and proceed with resetting their password.
- When a user logs in from a new device, an OTP might be sent to their registered contact information. The user must enter the OTP to verify they have access to the registered device, confirming their identity and that the new device is trusted.
By integrating OTPs into authentication and verification processes, services can add an extra level of security and significantly reduce the risk of unauthorized access or identity theft.
## Best practices for using one-time passwords
OTPs aren’t infallible, though. But the associated risks are generally around poor implementation rather than inherent to the method. To ensure OTP effectiveness and avoid some of the above potential vulnerabilities, you can follow some best practices.
### Basic security practices
These practices are the principles of any good system:
- **Secure delivery channel**. Use a secure delivery channel for sending the OTP. If you're sending the OTP via email or SMS, ensure the communication channel is secure.
- **Encrypt communication**. Ensure all communications between the client and the server are done over HTTPS to prevent any interception of the OTP.
- **Use secure storage**. When storing OTPs on the server side, consider hashing them. This ensures that even if someone gains access to your storage, they cannot obtain the actual OTPs.
### Good OTP design
These relate to how well you design your OTP algorithm and logic:
- **Use a strong OTP**. Use an OTP that is long and complex enough to resist brute-force attacks. An OTP with at least 6 digits is usually recommended.
- **Time-Bound OTP**. Make sure the OTP is valid only for a short period of time. This reduces the window an attacker has to use a stolen OTP. Usually, OTPs are valid for about 2-10 minutes.
- **Limit OTP attempts**. Implement rate limiting on your OTP endpoints to protect against brute force attacks. After a certain number of incorrect attempts, either block the user or implement a cool-down period.
- **Expiry after use.** The OTP should expire immediately after it has been used once, to prevent replay attacks.
### Good UX
These help users use your OTP and make sure they don’t turn it off:
- **Backup codes**. For applications using OTP as a second factor, provide backup codes that the user can write down and use if they lose access to their OTP delivery method (like losing their phone).
- **Fallback Options**. In case the primary delivery channel fails (e.g., SMS not being delivered), have a secondary option like email or voice call.
Also consider educating users about using OTPs. One of the main threats to OTP use are physical–if an attacker steals a user's phone then they’ll have access to the SMS or email used with OTPs. Or a fraudster can fake a user’s identity to trick a telecoms company into assigning a new SIM with the user’s phone number to them (known as [SIM swapping](https://en.wikipedia.org/wiki/SIM_swap_scam)).
While OTPs can greatly enhance security, they are not foolproof. Implementation within a broader security strategy is key.
## Setting up OTP Authentication in Next.js
Let’s walk through setting up a one time password system within Next.js. If you already have a Next.js app up and running you can add this code directly. Otherwise create a new app using:
```sh
npx create-next-app@latest
```
We’ll also need to use a few modules to help us with our OTPs, namely:
- [**Twilio**](http://twilio.com). Twilio allows us to send SMS messages programmatically. Here we’re going to use it to send the OTP to the user's phone number via SMS.
- [**bcryptjs**](https://www.npmjs.com/package/bcryptjs). bcryptjs is a JavaScript library for hashing and comparing passwords. We’re going to use it to hash the OTP before storing it in the database for added security.
- [**MongoDB**](https://www.mongodb.com). MongoDB is a NoSQL database that we’ll use to store hashed OTPs along with the associated phone numbers and expiry times.
- [**Upstash**](http://upstash.com). Upstash is a serverless data platform. We’re going to use it’s rate limiter and Redis functionality.
Install these with:
```sh
npm install twilio bcryptjs mongodb @upstash/ratelimit @upstash/redis
```
For Twilio and MongoDB, you’ll also need to sign up for accounts and then need your `TWILIO_ACCOUNT_SID`, your `TWILIO_AUTH_TOKEN`, and your `MONGODB_URI`. For Twilio, you’ll also need to buy a `TWILIO_PHONE_NUMBER` that will be used to send your SMS messages.
You’ll also need an account with Upstash, and then your `UPSTASH_REDIS_REST_URL` and `UPSTASH_REDIS_REST_TOKEN` variables.
With that done, we’ll first create the API route that will generate our OTP:
```javascript
// pages/api/generateOTP.js
import crypto from 'crypto'
import twilio from 'twilio'
import bcrypt from 'bcryptjs'
import { MongoClient } from 'mongodb'
export default async function handler(req, res) {
if (req.method !== 'POST') {
return res.status(405).end() // Method Not Allowed
}
// Generate a six digit number using the crypto module
const otp = crypto.randomInt(100000, 999999)
// Hash the OTP
const hashedOtp = await bcrypt.hash(otp.toString(), 10)
// Initialize the Twilio client
const client = twilio(process.env.TWILIO_ACCOUNT_SID, process.env.TWILIO_AUTH_TOKEN)
try {
// Send the OTP via SMS
await client.messages.create({
body: `Your OTP is: ${otp}`,
from: process.env.TWILIO_PHONE_NUMBER, // your Twilio number
to: req.body.phone, // your user's phone number
})
// Store the hashed OTP in the database along with the phone number and expiry time
const mongoClient = new MongoClient(process.env.MONGODB_URI)
await mongoClient.connect()
const otps = mongoClient.db().collection('otps')
await otps.insertOne({
phone: req.body.phone,
otp: hashedOtp,
expiry: Date.now() + 10 * 60 * 1000, // OTP expires after 10 minutes
})
await mongoClient.close()
// Respond with a success status
res.status(200).json({ success: true })
} catch (err) {
console.error(err)
res.status(500).json({ error: 'Could not send OTP' })
}
}
```
With this code we initially import all our dependencies, then create a handler function for our POST endpoint. The body of the POST request will contain the phone number of the user that we’ll get from the frontend. Within the endpoint, we’re doing a few things:
- Creating a six-digit random OTP
- Hashing that OTP with `bcryptjs` for storage
- Creating a Twilio client and then sending the OTP to the user’s phone number
- Creating a MongoDB client and storing the OTP along with the user’s phone number and an expiry time for the password.
Is this best practice? Absolutely not. We are doing a few things right, such as setting an expiry time on the OTP and hashing them. But our OTP generating ‘algorithm’ is laughably simple.
Let’s quickly create a frontend for this now:
```jsx
import { useState } from 'react'
const OTPGenerator = () => {
const [phone, setPhone] = useState('')
const [otp, setOTP] = useState('')
const [isLoading, setIsLoading] = useState(false)
const [message, setMessage] = useState('')
const [otpSent, setOtpSent] = useState(false)
const handleSendOTP = async (event) => {
event.preventDefault()
setIsLoading(true)
setMessage('') // reset message
try {
const response = await fetch('/api/generateOTP', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ phone }),
})
if (response.ok) {
setMessage('OTP has been sent to your phone.')
setOtpSent(true)
} else {
const data = await response.json()
setMessage(data.error)
}
} catch (error) {
setMessage('An error occurred. Please try again.')
console.error(error)
} finally {
setIsLoading(false)
}
}
const handleVerifyOTP = async (event) => {
event.preventDefault()
setIsLoading(true)
setMessage('') // reset message
try {
const response = await fetch('/api/verifyOTP', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ phone, otp }),
})
if (response.ok) {
setMessage('OTP verification successful!')
setOtpSent(false)
setPhone('')
setOTP('')
} else {
const data = await response.json()
setMessage(data.error)
}
} catch (error) {
setMessage(error)
console.error(error)
} finally {
setIsLoading(false)
}
}
return (
{!otpSent ? (
) : (
)}
{message &&
)
}
export default OTPGenerator
```
All this code will just show a single form on the page. On first load this form will ask for the user’s phone number.
When the user enters their phone number and hits submit, the above generateOTP endpoint will be called. This will send the OTP to the user’s phone number:
Hitting submit will also change the form to accept the OTP as the input. The user can then check their phone and enter the six-digit code: and hit submit again to send the OTP and phone number to a verifyOTP endpoint for verification:
```javascript
// pages/api/verifyOTP.js
import bcrypt from 'bcryptjs'
import { MongoClient } from 'mongodb'
import { Ratelimit } from '@upstash/ratelimit'
import { Redis } from '@upstash/redis'
const rateLimiter = new Ratelimit({
redis: Redis.fromEnv(),
limiter: Ratelimit.slidingWindow(2, '3 s'),
})
export default async function handler(req, res) {
const user_ip = req.headers['x-forwarded-for']
const { success } = await rateLimiter.limit(user_ip)
if (!success) {
return res.status(429).json({ error: 'Too Many Requests' })
}
if (req.method !== 'POST') {
return res.status(405).end() // Method Not Allowed
}
const mongoClient = new MongoClient(process.env.MONGODB_URI)
await mongoClient.connect()
const otps = mongoClient.db().collection('otps')
try {
// Fetch the OTP record from the database
const otpRecord = await otps.findOne({ phone: req.body.phone })
if (!otpRecord) {
return res.status(400).json({ error: 'Invalid phone number or OTP' })
}
// Check if the OTP has expired
if (Date.now() > otpRecord.expiry) {
return res.status(400).json({ error: 'OTP has expired' })
}
// Check if the OTPs match
const otpMatch = await bcrypt.compare(req.body.otp.toString(), otpRecord.otp)
if (!otpMatch) {
return res.status(400).json({ error: 'Invalid phone number or OTP' })
}
// OTP is valid and has not expired, so we can delete it now
await otps.deleteOne({ phone: req.body.phone })
// Respond with a success status
res.status(200).json({ success: true })
} catch (err) {
console.error(err)
res.status(500).json({ error: 'Could not verify OTP' })
} finally {
await mongoClient.close()
}
}
```
When called, this API loads the OTP MongoDB database and finds the one associated with the phone number. It checks whether it has expired, and if not, matches the hashed OTPs. If it's valid, the OTP gets deleted from the database and a 200 code is returned to the frontend.
We could then work that response into any other authentication flow we had set up. We also have a basic rate limiter set into that will make sure a user can’t input more than 2 codes in 3 seconds, to try and prevent brute force attacks:
And that’s it. You have one-time passwords working in Next.js.
## OTPs are intricate but worth implementing
This code gives you a one-time password option for [Next.js authentication](/nextjs-authentication). But we’ve only scratched the surface. We haven’t implemented this within any other authentication flow–this just generates, sends, and verifies the OTP, it doesn’t use it to authenticate the user.
We’ve also generated the OTP in the most basic manner, not following the RFCs and guidelines. We do have some nice best practices–rate-limiting, time-bounding, and expiry–but again these are all basic implementations. We also had to buy a new phone number!
This is the intricacy of OTPs. They are easy to set up, but difficult to get right. Like most authentication methods, it is better to use a provider than trying to create your own. Check out Clerk’s [OTP solution here](/docs/custom-flows/email-sms-otp#email-sms-otp) to have these intricacies taken care of for you.
---
# Build a Cookie Clicker App with Clerk and Hasura
URL: https://clerk.com/blog/build-a-cookie-clicker-app-with-clerk-and-hasura.md
Date: 2023-07-23
Category: Guides
Description: In this tutorial we will use Clerk with Hasura to build a full-stack Next.js app with a database and GraphQL API, all without having to write any backend code.
[Hasura](https://hasura.io) provides a GraphQL engine that can help you build real-time APIs and ship modern apps faster. Although Hasura itself does not handle authentication, you can bring your own auth server and integrate it with Hasura via JWTs. This is where [Clerk](/) fits in.
In this tutorial we will use Clerk with Hasura to build a full-stack Next.js app with a database and GraphQL API, all without having to write any backend code.
> If you would like to skip ahead and see the completed codebase, browse to the repo [here](https://github.com/clerkinc/more-cookies-please).
## Assumptions
This tutorial makes the following assumptions:
- Basic command line usage
- Node.js installed and `npm` (or `yarn` if you prefer) for package management
- Experience with React components and hooks
- Familiarity with the Next.js application structure (created with `create-next-app`)
- Comfortable running Docker Compose commands (alternative path is to use Hasura Cloud)
- [Clerk](https://dashboard.clerk.com/sign-in) and [Hasura](https://cloud.hasura.io/login) accounts already set up (if you haven’t done so, do it now\... we’ll wait)
## Set up Clerk project
We’re going to start off with creating a new project from the Clerk dashboard. I’m going to name this application “More Cookies Please” (you’ll see why shortly) and leave the default options selected for authentication strategy and turn on social login with Google.
The next thing we need to do is navigate to JWT Templates from the left menu and create a template based on Hasura.
The next thing we need to do is navigate to JWT Templates from the left menu and create a template based on Hasura.
Click the “Apply changes” button and navigate back to the Home dashboard. Here we’re going to copy the Frontend API key.
That’s all we need to do in the Clerk dashboard.
## Clone the starter repo
Now it’s time to clone the [clerk-hasura-starter](https://github.com/clerkinc/clerk-hasura-starter) repo from GitHub. Name this project directory `more-cookies-please` to match the Clerk instance name.
```bash
git clone https://github.com/clerkinc/clerk-hasura-starter.git more-cookies-please
```
Once you have the repository downloaded to your computer, run the following commands to change into the directory, install the package dependencies, and copy the `.env.local.sample` so we can set a couple environment variables:
```bash
cd more-cookies-please/
npm install
cp .env.local.sample .env.local
```
Add in the Frontend API key from Clerk that was copied earlier. We’re also going to set the GraphQL endpoint even though it hasn’t been created yet.
```bash
NEXT_PUBLIC_CLERK_FRONTEND_API={message}
}Click the cookie
Sign up for an account
Sign up and sign in to explore all the features provided by Clerk out-of-the-box
Click the cookie
Click the cookie
Click the cookie
Current count: {count}
{currentUser?.emailAddresses[0]?.emailAddress}
)
}
```
This reads the primary email address property and removes the absolute positioning styles.
The navigation header should now look similar to:
(Displaying your own account of course.)
Clerk makes it super easy to add in these authentication components. There are more options for customization available as well.
Now that you have an authenticated user, you should be able to safely navigate to [http://localhost:8910/admin/posts](http://localhost:8910/admin/posts) and manage the blog posts.
That’s really all there is to it.
## Going deeper
If you’d like to go deeper into the forest (really stretching this metaphor here), you could try your hand at the following:
- Update the Login and Sign Up pages with [mounted Clerk components](/docs/components/authentication/sign-in)
- Add `roles: ['admin']` to the user public metadata to [implement role-based access control](/docs/guides/basic-rbac)
- Go outside and visit the [Redwood National and State Parks](https://www.nps.gov/redw/index.htm) to see these majestic trees in person
- Connect with other developers or say hi in our [Discord community](https://clerk.com/discord) 👋
---
# Migrating from Pages Router to App Router: An Incremental Guide
URL: https://clerk.com/blog/migrating-pages-router-to-app-router-an-incremental-guide.md
Date: 2023-07-03
Category: Guides
Description: Already know the /pages directory? Here's a simple way to migrate to the /app directory in Next.js 13.
The Next.js [App Router](https://nextjs.org/docs/app) (in the **/app** directory) is a new way to build React applications. If you're already familiar with the [Pages Router](https://nextjs.org/docs/pages) (in the **/pages** directory), Next.js has made it really easy to adopt the App Router incrementally, quite literally on a page-by-page basis. This guide explains how.
## How is this guide different?
The App Router already has a [migration guide](https://nextjs.org/docs/app/building-your-application/upgrading/app-router-migration), so how is this different?
We want to demonstrate a 1-to-1 mapping of Pages Router to App Router, but this is not a complete migration. In the snippets below you will see obvious potential refactors, and **that is on purpose.**
As an example, one App Router snippet below still has function called `getServerSideProps`. It doesn't make sense to keep that name, but we want to demonstrate how `getServerSideProps` can be expressed in the context of the App Router.
One more disclaimer: this will not explain how to migrate *everything*. We focused on the best practices for the Pages Router in Next.js 12.3, but left out older APIs like `getInitialProps`.
## One quick clarification
You probably know that the App Router supports both **Client Components** and the newly introduced **Server Components**.
Before the App Router, Client Components were just called Components. We want to clarify that after the App Router, **absolutely nothing has changed about them.**
Most importantly, within the App Router, **Client Components** are still rendered on the server, then hydrated on client. Search engine crawlers can still index their HTML.
Within this guide, the React code from your Pages Router will be copied to new files and labeled with `"use client"` at the top. This is expected, since we're doing a 1-to-1 mapping.
## Migrating from the Pages Router to the App Router
### 0. Create the /app directory
Before you can get started with the App Router, you will first need to create a **/app** directory as a sibling to your **/pages** directory.
### 1. Migrate /pages/\_document to the App Router
If you have a [Custom Document](https://nextjs.org/docs/pages/building-your-application/routing/custom-document) at **/pages/\_document.tsx**, it should look something like this, though likely with some customization:
```tsx {{ title: '/pages/_document.tsx' }}
import { Html, Head, Main, NextScript } from 'next/document'
export default function Document() {
return (
Welcome {userdata.name} to the dashboard!
LogoutWelcome {userdata.emailAddresses[0].emailAddress} to the dashboard!
Loading...
}
if (error) {
return Error: {error.message}
}
return (
Data from API:
{JSON.stringify(data, null, 2)}
{data ? (
<>
{data.secret}
{data.email}
) : (This isn't a secret
)}Create your profile
setName(ev.target.value)}
className={'inputBox'}
/>
{/* Email input field */}
setEmail(ev.target.value)}
className={'inputBox'}
/>
{/* Button to generate UUIDs */}
setId(ev.target.value)}
className={'inputBox'}
/>
WelcomePage
}
```
To render the welcome page, first navigate to the `App.js` file inside the `src` folder. Import the `WelcomePage.js` file using the following code:
```jsx
import WelcomePage from './WelcomePage.js'
```
Then, inside the return statement, remove everything and add this code:
```jsx
{cookies.user ?
Welcome, {user.username}!
} export default WelcomePage ``` This `WelcomePage` component simply displays a welcome message with the user's username. It receives the user object as a prop, which contains the user's username and password. The parent component (`App` in this case) passes the user object to the `WelcomePage` component when `WelcomePage` is rendered. ## Test Your Application To test your application, go to the browser and fill in the login form with your username and password. When you click **Submit**, the welcome page should be displayed with the words "Welcome" followed by your username. This indicates that the login was successful and the `WelcomePage` component was rendered. It should look like the image below.  To check if a cookie has been set in your Chrome browser, you can use the developer tools. Open your browser, and if you're on Chrome, go to the page where the cookie is set by pressing F12 on your keyboard to open the developer tools. Click on the **Application** tab in the developer tools. In the left panel, expand the **Cookies** section and click on the domain where the cookie is set—in this case, it's `http://localhost:3000`. In the right panel, you should see a cookie that has been set for the domain like in the image above. You can find the complete code for this tutorial on [GitHub](https://github.com/gitnyasha/using-cookies-in-react). ## Conclusion In this tutorial, you learned how to create a login page and a welcome page in a React app and how to store the user's login information in a cookie. You also learned how to only display the welcome page if the user is logged in and how to check if a cookie has been set in the Chrome browser. Using cookies in a React app can make the login process more user-friendly as it allows users to access the welcome page without having to enter their login information every time they visit the page. Clerk provides an easy way to add authentication and user management to your application. Clerk handles session management, including setting cookies on your behalf, saving you time and effort. This allows you to focus on building the features of your app without having to worry about implementing the authentication and session management features from scratch. [Give Clerk a try by signing up today](https://dashboard.clerk.com/sign-up). --- # Adding JWT Authentication to React URL: https://clerk.com/blog/adding-jwt-authentication-to-react.md Date: 2023-04-14 Category: Guides Description: Learn how to implement JSON Web Token (JWT) authentication in a React app using a standard flow, and how Clerk can make the process even easier. JSON Web Token (JWT) authentication is a method of securely authenticating users and allowing them to access protected resources on a website or application. It's a popular and widely used method of web authentication as it allows for easy and secure user authentication without the need for the server to maintain a session state. In this process, the server generates a signed JWT and sends it to the client. The client then includes this token in subsequent requests to the server to authenticate themselves. The JWT is usually stored in the browser's localStorage and sent as part of the request's headers. However, the JWT mechanism can be arduous and error-prone, especially if you're building it from scratch. In this article, you'll learn how to implement JWT in a React application using a standard flow, and then you'll see how much easier it gets when repeating the exercise using [Clerk's React authentication](/react-authentication). ## What Is JWT Authentication? Before we discuss how a user is authenticated with JWT, let's take a closer look at what it contains: 1. `The header:` consists of two parts—the token type, which is JWT, and a signing algorithm, such as HMAC-SHA256 or RSA 2. `The payload:` contains the claims—in other words, the statements about an entity (typically, the user) and additional data 3. `The signature:` used to verify the JWT's integrity To authenticate a client using JWT, the server first generates a signed JWT and sends it to the client. The client then includes the JWT in the header (usually the [authorization header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Authorization)) of subsequent requests to the server. The server then decodes the JWT and verifies the signature to ensure that a trusted party sent it. If the signature is valid, the server can then use the information contained in the JWT to authenticate the client and authorize their access to specific resources. The diagram below shows a standard JWT authentication flow.  ### Advantages and Downsides of Using JWT Using JWT authentication offers the following advantages: 1. `JWT authentication is stateless:` A JWT contains all the information regarding the user's identity and authentication, including the claims. This can be more efficient than storing session information on the server as it reduces the amount of data that needs to be stored and retrieved for each request. 2. `Create anywhere:` Another advantage of JWT authentication is that the token can be generated from anywhere, including external services or third-party applications. This allows for flexibility in terms of where and how the token is generated, which can be useful in a microservices architecture where different services may need to authenticate users. 3. `Fine-grained access control:` JWT can contain information about the user's role and permissions in the form of claims. This gives the application developers a lot of control over what actions a user is allowed to take. However, there are also some disadvantages to using JWT authentication: 1. `Hard to invalidate:` Invalidating JWTs is only possible if you maintain a list on a shared database, which introduces additional overhead. The database is necessary because if you need to revoke a token or if a user's permissions change, the server won't otherwise be able to determine the status of the token and might give access when it shouldn't. If the JWTs you're using are long-lived—in other words, they have a very long (or no) expiration time specified—it becomes even more important that they're stored in an accessible database. 2. `Size and security concerns:` JWTs can sometimes contain unnecessary information that might be useless for the application and, at the same time, make the token larger and more cumbersome to work with. If the JWT is unencrypted, it can also end up revealing too much about the user. Given these challenges, some would say that using cookies over JWT works better in some instances as a method of authentication; for example, when the application needs to keep track of the user's activity across multiple pages, as cookies can be easily read and written on the server side. Let's compare the two in detail. ### Are Cookies Better Than JWT? To start with, you can create session-based cookies, which automatically expire after the user session is closed, or you can easily set an expiration time for a cookie, which gives more control over session invalidation. You can also use HttpOnly cookies to prevent JavaScript from accessing the cookie information. However, it's important to note that cookies come with their own flaws. Specifically, as the cookie data is stored on the server and the cookie identifier is stored on the client, they're not entirely stateless like JWTs. This means that the server needs to store and retrieve the cookie data for each request, which would be additional overhead to the authentication process and slow down the application's performance, especially if the number of concurrent users increases. They're also not ideal for non-browser-based applications, such as mobile and desktop applications. Additionally, cookies can be more vulnerable to certain attacks, such as [cross-site scripting (XSS)](https://owasp.org/www-community/attacks/xss) and [cross-site request forgery (CSRF)](https://owasp.org/www-community/attacks/csrf). Now that we've covered the advantages and some of the potential challenges of JWT authentication, let's see the process in action. In the following section, you'll see how to implement JWT authentication in your React application. ## Implementing JWT Authentication in Your React Application In this tutorial, you'll build a simple full-stack application with [authentication in Next.js](/nextjs-authentication). Next.js allows you to implement frontend applications using React and a backend API server without setting up another Node.js project. You'll also understand the pitfalls of creating a JWT authentication from scratch and learn to overcome those limitations using the Clerk SDK. > For pure React applications (without Next.js), check out our [React authentication solution](/react-authentication) which handles JWT and other auth methods seamlessly. The application stores the key to the user's safehouse (a protected resource) and uses JWT authentication to verify their identity. The application shows the user a welcome page, where they can sign in with a username and password. It generates a JWT for the user, which they can use to verify their identity. Once signed in, users will see their safehouse's secret key by exchanging the JWT with the server. Before you begin, you'll need a code editor like [Visual Studio Code](https://code.visualstudio.com/download). You'll also need Node.js (version 16 or newer) and npm installed. If you want to check out the completed application, you can clone this [GitHub repository](https://github.com/Anshuman71/clerk-jwt-example). ### Setting Up the Project To set up a Next.js project, run the following command: ```bash npx create-next-app clerk-jwt-example ``` You'll be prompted on whether you'd like to use TypeScript and ESLint. For simplicity, choose `No` for TypeScript and then `Yes` for ESLint. After you complete the npm installation, open the project in your code editor and change the directory to the project by running `cd clerk-jwt-example` in your terminal. To use the browser's default styling, remove all existing styles from `styles/globals.css` and `styles/Home.module.css`. ### JWT Authentication Using a Standard Flow In this example, you'll create two pages: `/jwt-home` and `jwt-safehouse`. The former will be the [login page](/blog/building-a-react-login-page-template) to collect credentials, and the latter will be the secured page showing secret information. More specifically, the `/jwt-home` page accepts the user credentials and requests the `/api/auth` API endpoint to generate the signed JWT. The application stores the returned JWT in localStorage as the `jwt-token` key. The `/jwt-safehouse` acts as the secured page and requests the secret information from the `/api/safehouse` API endpoint in exchange for the signed JWT. The `/jwt-safehouse` page then displays the secret information to the signed-in user. In Next.js, you can create a new application route by creating a new file with the route name under the `pages/` folder. Similarly, to create a new API endpoint, you need to create a new file under the `pages/api/` folder. #### Update the Application Home Page To access different parts of your application, update the application home page (`pages/index.js`) to show links to other pages in the application. The code below uses the `Link` component from `next/link`, which is the Next.js version of the `` tag: ```jsx import Link from 'next/link' export default function Home() { return (
Home
)
}
```
Now start the application by running `npm run dev` in the terminal. Open `http://localhost:3000` in a web browser to see the application. You'll see the page, as shown below.
#### Create a Signed JWT
To create a signed JWT, you first need to install the `jsonwebtoken` package. `jsonwebtoken` provides utilities to sign and verify JWTs. Run `npm i jsonwebtoken` to install the package in your project.
You'll need a JWT signing secret to use with `jsonwebtoken`. For this, create a new file, `.env.local`, to store the application's secret credentials. In this file, add a new environment variable, `DIY_JWT_SECRET`, with a random hash string as a value:
```txt
DIY_JWT_SECRET=2182312c81187ab82bbe053df6b7aa55
```
To generate the signed JWT with the user's `signInTime` and `username`, create an API route `/api/auth` by creating the new file `pages/api/auth.js`. The API route accepts the user credentials, and if the provided password is `pikachu`, it returns a `200` response with the signed JWT. Otherwise, it returns a `401` response with an error message:
```js
import jwt from 'jsonwebtoken'
export default function handler(req, res) {
const jwtSecretKey = process.env.DIY_JWT_SECRET
const { username, password } = req.body
// confirm if password is valid
if (password !== 'pikachu') {
return res.status(401).json({ message: 'Invalid password' })
}
let data = {
signInTime: Date.now(),
username,
}
const token = jwt.sign(data, jwtSecretKey)
res.status(200).json({ message: 'success', token })
}
```
#### Create a Login with JWT
Now that the `/api/auth` API endpoint is ready, create the new file `pages/jwt-home.jsx` and implement a login form component to send user credentials to `/api/auth`.
The code below implements a React component, `Home`, that displays a form to collect the user credentials and, on form submission, makes an HTTP POST request to the `/api/auth` endpoint with the collected credentials.
If the response message is `success`, it saves the received JWT in localStorage under the `jwt-token` key. Otherwise, it shows a browser alert with the response message:
```jsx
import { useState } from 'react'
import { useRouter } from 'next/router'
export default function Home() {
const [username, setUsername] = useState('')
const [password, setPassword] = useState('')
const router = useRouter()
function submitUser(event) {
event.preventDefault()
fetch('/api/auth', {
method: 'POST',
headers: {
'content-type': 'application/json',
},
body: JSON.stringify({ username, password }),
})
.then((res) => res.json())
.then((data) => {
if (data.message === 'success') {
localStorage.setItem('jwt-token', data.token)
setUsername('')
setPassword('')
router.push('/jwt-safehouse')
} else {
alert(data.message)
}
})
}
return (
<>
- JWT Home
- JWT Safe house
Login
You're not logged in.
HomeSafehouse
You Safehouse key is {userData?.safehouseKey || 'Loading...'}
Safehouse
You Safehouse key is {userData?.safehouseKey || 'Loading...'}
Home
)
}
```
Your React application is ready with end-to-end authentication.
### Traditional JWT Authentication vs. Clerk
Now that you've implemented authentication in your React application using the traditional JWT flow and with Clerk, you can see how easy it is to implement a full-fledged authentication using the latter approach.
In the do-it-yourself JWT approach, all responsibilities regarding authentication—such as storing the password, verifying user identity, and crafting a beautiful user experience—fall on your shoulders.
Clerk lifts this burden by offering a full-stack solution for managing user authentication. It not only provides easy integrations on the frontend with prebuilt components but also authentication utilities for the backend API routes. With Clerk, you don't have to worry about password management, user session management, or signing and storing the JWT. It's all managed for you automatically.
Apart from its simplicity, the Clerk SDK also uses short-lived JWTs and HttpOnly cookies to provide an additional layer of security for your application. While short-lived JWTs help to protect against replay attacks and limit the window of opportunity for an attacker to use a compromised token, HttpOnly cookies help to protect against XSS attacks.
## Conclusion
In this article, you've successfully set up JWT authentication in a React application. While doing so, you learned more about JWT authentication and how to overcome some of its challenges. In particular, you saw how using a solution like Clerk can tremendously simplify JWT authentication in React and make the process more secure at the same time.
Clerk is a one-stop solution for authentication and customer identity management. It can help you build a flawless user authentication flow that supports login with password, multifactor authentication, and social logins with providers like Google, LinkedIn, Facebook, GitHub, and many more.
Clerk provides beautiful components ready to plug into your application and build the authentication flow in no time. Sign up to try [Clerk](https://dashboard.clerk.com/sign-up) today.- JWT Home
- JWT Safe house
- Clerk Safe house