Next.js & Code Authentication: A Beginner’s Guide

Written by

learnmodernwebdevelopment

in

In the digital age, securing your web applications is not just a best practice; it’s a fundamental necessity. Imagine building a fantastic website or application with all the bells and whistles, only to have unauthorized users access sensitive data or perform actions they shouldn’t. This is where authentication comes in. Authentication is the process of verifying a user’s identity, ensuring that only authorized individuals can access specific features and information. In this comprehensive guide, we’ll dive deep into implementing authentication in your Next.js applications, covering everything from the basics to more advanced techniques.

Why Authentication Matters

Before we get our hands dirty with code, let’s understand why authentication is so crucial. Consider these scenarios:

  • User Accounts: If your application allows users to create accounts, like a social media platform or an e-commerce site, authentication is essential to verify their identity and protect their personal information.
  • Data Security: Authentication prevents unauthorized access to sensitive data, such as financial records, personal details, or intellectual property.
  • Access Control: Authentication enables you to control access to specific features or content based on a user’s role or permissions. For example, only administrators should be able to modify website settings.
  • Compliance: Many industries have regulations that require authentication to protect user data and maintain security.

In essence, authentication is the gatekeeper of your application, ensuring that only trusted users can enter and interact with your protected resources.

Understanding the Basics: Authentication vs. Authorization

It’s easy to confuse authentication with authorization, but they are distinct concepts:

  • Authentication: This is the process of verifying a user’s identity. It answers the question, “Are you who you say you are?” Common methods include username/password, social logins (e.g., Google, Facebook), and multi-factor authentication (MFA).
  • Authorization: This is the process of determining what a user is allowed to do or access after they have been authenticated. It answers the question, “What are you allowed to do?” This often involves assigning roles or permissions to users.

Authentication comes first. Once a user is authenticated, authorization determines their access rights.

Setting Up Your Next.js Project

If you don’t already have one, create a new Next.js project. Open your terminal and run:

npx create-next-app my-auth-app
cd my-auth-app

This command creates a new Next.js project named “my-auth-app” and navigates you into the project directory.

Choosing an Authentication Method

There are various ways to implement authentication in your Next.js application. Here are a few popular options:

  • Username/Password: This is the classic approach where users create an account with a username and password. You’ll typically store these credentials securely (e.g., using hashing and salting) in a database.
  • Social Login: Allow users to sign in with their existing accounts from platforms like Google, Facebook, Twitter, etc. This simplifies the signup process and can improve user experience.
  • JWT (JSON Web Tokens): JWTs are a standard for securely transmitting information between parties as a JSON object. They are often used for stateless authentication, where the server doesn’t need to store session data.
  • Third-Party Authentication Services: Services like Auth0, Firebase Authentication, and AWS Cognito provide pre-built authentication solutions, making it easier to integrate authentication into your app without building it from scratch.

For this tutorial, we will focus on using a username/password combination combined with JWTs, as this provides a solid foundation for understanding authentication principles. However, the concepts can be adapted to other methods.

Implementing Username/Password Authentication with JWTs

Let’s create a basic authentication system with username/password and JWTs. We’ll use a simple in-memory store for user data for simplicity. In a production environment, you would use a database.

1. Project Setup

First, install the necessary packages. In your project directory, run:

npm install jsonwebtoken bcryptjs

These packages are:

  • jsonwebtoken: For creating and verifying JWTs.
  • bcryptjs: For securely hashing passwords.

2. User Data and Helper Functions

Create a file named utils/auth.js. This file will contain functions for user management, password hashing, and JWT generation.

// utils/auth.js
import bcrypt from 'bcryptjs';
import jwt from 'jsonwebtoken';

// In-memory user store (replace with a database in production)
const users = [
  {
    id: 1,
    username: 'testuser',
    password: 'hashedPassword', // Store hashed passwords
  },
];

// Generate a hashed password
async function hashPassword(password) {
  const salt = await bcrypt.genSalt(10);
  return await bcrypt.hash(password, salt);
}

// Compare a password with a hashed password
async function comparePasswords(password, hashedPassword) {
  return await bcrypt.compare(password, hashedPassword);
}

// Generate a JWT
function generateToken(user) {
  const payload = {
    id: user.id,
    username: user.username,
  };
  const secret = process.env.JWT_SECRET; // Store your secret in environment variables
  const options = {
    expiresIn: '1h',
  };

  return jwt.sign(payload, secret, options);
}

// Verify a JWT
function verifyToken(token) {
  const secret = process.env.JWT_SECRET;
  try {
    return jwt.verify(token, secret);
  } catch (error) {
    return null; // Token is invalid or expired
  }
}

export { hashPassword, comparePasswords, generateToken, verifyToken, users };

Important notes:

  • Security: Never store passwords in plain text. Always hash them using a strong hashing algorithm like bcrypt.
  • JWT Secret: Store your JWT secret in environment variables. This prevents it from being hardcoded in your application.
  • Token Expiry: Set an expiration time for your JWTs. This helps to mitigate the risk of compromised tokens.
  • Database: This example uses an in-memory user store for simplicity. For production, integrate with a database (e.g., PostgreSQL, MongoDB) to store user data.

3. API Routes for Authentication

Next.js uses API routes to handle backend logic. Create the following API routes in the pages/api/auth directory. If the directory doesn’t exist, create it.

3.1. Signup Route (pages/api/auth/signup.js)

// pages/api/auth/signup.js
import { hashPassword, users } from '../../../utils/auth';

export default async function handler(req, res) {
  if (req.method === 'POST') {
    const { username, password } = req.body;

    if (!username || !password) {
      return res.status(400).json({ message: 'Username and password are required' });
    }

    try {
      const hashedPassword = await hashPassword(password);

      // In a real application, check if the username already exists in the database
      const newUser = {
        id: users.length + 1,
        username: username,
        password: hashedPassword,
      };

      users.push(newUser);

      return res.status(201).json({ message: 'User created successfully' });
    } catch (error) {
      console.error('Signup error:', error);
      return res.status(500).json({ message: 'Failed to create user' });
    }
  }

  return res.status(405).json({ message: 'Method not allowed' });
}

Key points:

  • Input Validation: The code checks if the username and password are provided in the request body.
  • Password Hashing: The provided password is hashed using the hashPassword function.
  • User Storage: The new user (with the hashed password) is stored in the in-memory users array. In a real application, you’d save this to a database.
  • Error Handling: Includes basic error handling for common issues.

3.2. Login Route (pages/api/auth/login.js)

// pages/api/auth/login.js
import { comparePasswords, generateToken, users } from '../../../utils/auth';

export default async function handler(req, res) {
  if (req.method === 'POST') {
    const { username, password } = req.body;

    if (!username || !password) {
      return res.status(400).json({ message: 'Username and password are required' });
    }

    const user = users.find((u) => u.username === username);

    if (!user) {
      return res.status(401).json({ message: 'Invalid credentials' });
    }

    try {
      const passwordMatch = await comparePasswords(password, user.password);

      if (!passwordMatch) {
        return res.status(401).json({ message: 'Invalid credentials' });
      }

      const token = generateToken(user);
      return res.status(200).json({ token: token });
    } catch (error) {
      console.error('Login error:', error);
      return res.status(500).json({ message: 'Failed to login' });
    }
  }

  return res.status(405).json({ message: 'Method not allowed' });
}

Important points:

  • Credential Check: The code retrieves the user from the in-memory users array by username.
  • Password Verification: The provided password is compared with the stored hashed password using the comparePasswords function.
  • JWT Generation: If the credentials are valid, a JWT is generated using the generateToken function.
  • Token Return: The generated JWT is returned in the response.

4. Creating a Protected Route (Example)

Let’s create a protected route to demonstrate how to use the JWT to authorize access. Create a file called pages/api/protected.js.

// pages/api/protected.js
import { verifyToken } from '../../../utils/auth';

export default function handler(req, res) {
  const authHeader = req.headers.authorization;

  if (!authHeader) {
    return res.status(401).json({ message: 'No token provided' });
  }

  const token = authHeader.split(' ')[1]; // Bearer 

  if (!token) {
    return res.status(401).json({ message: 'Invalid token' });
  }

  const decoded = verifyToken(token);

  if (!decoded) {
    return res.status(401).json({ message: 'Invalid token' });
  }

  // If the token is valid, you can access the user information
  // For example:
  // const userId = decoded.id;
  // const username = decoded.username;

  return res.status(200).json({ message: 'Protected route accessed successfully', user: decoded });
}

Explanation:

  • Authorization Header: The code retrieves the authorization header from the request. This header should contain the JWT in the format “Bearer [token]”.
  • Token Extraction: The code extracts the token from the authorization header.
  • Token Verification: The code uses the verifyToken function to verify the token.
  • Access Granted: If the token is valid, the route grants access to the protected resource. In this example, it returns a success message.

5. Setting Environment Variables

For security, store your JWT secret in an environment variable. Create a .env.local file in the root of your project and add the following line. Replace “your-secret-key” with a strong, randomly generated secret:

JWT_SECRET=your-secret-key

Restart your Next.js development server after creating or modifying the .env.local file.

Building the Frontend

Now that we have the backend API routes, let’s build the frontend components for signup, login, and accessing the protected route.

1. Signup Form (components/SignupForm.js)

// components/SignupForm.js
import { useState } from 'react';

function SignupForm() {
  const [username, setUsername] = useState('');
  const [password, setPassword] = useState('');
  const [message, setMessage] = useState('');

  const handleSubmit = async (e) => {
    e.preventDefault();
    try {
      const response = await fetch('/api/auth/signup', {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
        },
        body: JSON.stringify({ username, password }),
      });

      const data = await response.json();

      if (response.ok) {
        setMessage('User created successfully. Please login.');
        setUsername('');
        setPassword('');
      } else {
        setMessage(data.message || 'Signup failed');
      }
    } catch (error) {
      setMessage('An error occurred during signup.');
      console.error('Signup error:', error);
    }
  };

  return (
    <div>
      <h2>Signup</h2>
      
        <div>
          <label>Username:</label>
           setUsername(e.target.value)}
          />
        </div>
        <div>
          <label>Password:</label>
           setPassword(e.target.value)}
          />
        </div>
        <button type="submit">Signup</button>
      
      {message && <p>{message}</p>}
    </div>
  );
}

export default SignupForm;

Key points:

  • State Management: The component uses the useState hook to manage the form input values (username and password) and the message to display to the user.
  • Form Submission: The handleSubmit function is called when the form is submitted. It sends a POST request to the /api/auth/signup API route with the user’s credentials.
  • Error Handling: The code includes error handling to display appropriate messages to the user if the signup fails.

2. Login Form (components/LoginForm.js)

// components/LoginForm.js
import { useState } from 'react';
import { useRouter } from 'next/router';

function LoginForm() {
  const [username, setUsername] = useState('');
  const [password, setPassword] = useState('');
  const [message, setMessage] = useState('');
  const router = useRouter();

  const handleSubmit = async (e) => {
    e.preventDefault();
    try {
      const response = await fetch('/api/auth/login', {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
        },
        body: JSON.stringify({ username, password }),
      });

      const data = await response.json();

      if (response.ok) {
        // Store the token in local storage or a cookie
        localStorage.setItem('token', data.token);
        setMessage('Login successful!');
        // Redirect to a protected route or the homepage
        router.push('/protected');
      } else {
        setMessage(data.message || 'Login failed');
      }
    } catch (error) {
      setMessage('An error occurred during login.');
      console.error('Login error:', error);
    }
  };

  return (
    <div>
      <h2>Login</h2>
      
        <div>
          <label>Username:</label>
           setUsername(e.target.value)}
          />
        </div>
        <div>
          <label>Password:</label>
           setPassword(e.target.value)}
          />
        </div>
        <button type="submit">Login</button>
      
      {message && <p>{message}</p>}
    </div>
  );
}

export default LoginForm;

Key points:

  • State Management: Similar to the signup form, this component uses useState to manage form input values and messages.
  • Form Submission: The handleSubmit function sends a POST request to the /api/auth/login API route.
  • Token Storage: If the login is successful, the JWT is stored in local storage using localStorage.setItem('token', data.token). You could also store it in a cookie.
  • Redirection: The component uses the useRouter hook to redirect the user to a protected route (e.g., “/protected”) after successful login.
  • Error Handling: Includes error handling to display appropriate messages to the user.

3. Protected Route (pages/protected.js)

// pages/protected.js
import { useEffect, useState } from 'react';
import { useRouter } from 'next/router';

function Protected() {
  const [message, setMessage] = useState('');
  const [user, setUser] = useState(null);
  const router = useRouter();

  useEffect(() => {
    const token = localStorage.getItem('token');

    if (!token) {
      // Redirect to login if no token
      router.push('/login');
      return;
    }

    async function fetchProtectedData() {
      try {
        const response = await fetch('/api/protected', {
          method: 'GET',
          headers: {
            'Authorization': `Bearer ${token}`,
          },
        });

        if (response.ok) {
          const data = await response.json();
          setMessage(data.message);
          setUser(data.user); // Access user data from the response
        } else {
          // If token is invalid or expired, remove token and redirect to login
          localStorage.removeItem('token');
          router.push('/login');
        }
      } catch (error) {
        console.error('Error fetching protected data:', error);
        localStorage.removeItem('token');
        router.push('/login');
      }
    }

    fetchProtectedData();
  }, [router]);

  const handleLogout = () => {
    localStorage.removeItem('token');
    router.push('/login');
  };

  return (
    <div>
      <h2>Protected Route</h2>
      {message && <p>{message}</p>}
      {user && (
        <div>
          <p>Welcome, {user.username}!</p>
        </div>
      )}
      <button>Logout</button>
    </div>
  );
}

export default Protected;

Explanation:

  • Token Check: The useEffect hook checks for the presence of a JWT in local storage. If no token is found, it redirects the user to the login page.
  • API Request: If a token is found, the component makes a GET request to the /api/protected API route, including the token in the Authorization header.
  • Token Validation: The API route verifies the token. If the token is invalid or expired, the API route returns an error. The component then removes the token from local storage and redirects to the login page.
  • Displaying User Data: If the API request is successful, the component displays a welcome message and any user-specific data that was returned from the API.
  • Logout Functionality: The handleLogout function removes the token from local storage and redirects the user to the login page.

4. Creating the Login and Signup Pages

Create two new pages in your pages directory to render the signup and login forms. These will be the entry points for your users.

Login Page (pages/login.js):

// pages/login.js
import LoginForm from '../components/LoginForm';

function LoginPage() {
  return (
    <div>
      <h1>Login</h1>
      
    </div>
  );
}

export default LoginPage;

Signup Page (pages/signup.js):

// pages/signup.js
import SignupForm from '../components/SignupForm';

function SignupPage() {
  return (
    <div>
      <h1>Signup</h1>
      
    </div>
  );
}

export default SignupPage;

Important Note: Always handle user input with care. Sanitize and validate all user inputs on both the client and server sides to prevent security vulnerabilities like cross-site scripting (XSS) and SQL injection (if you’re using a database).

Testing Your Authentication System

Now, let’s test the authentication system:

  1. Run Your Development Server: In your project directory, run npm run dev.
  2. Signup: Navigate to the signup page (e.g., http://localhost:3000/signup). Enter a username and password and submit the form.
  3. Login: Navigate to the login page (e.g., http://localhost:3000/login). Enter the same credentials you used for signup and submit the form. You should be redirected to the protected route.
  4. Access Protected Route: You should now be able to access the protected route (e.g., http://localhost:3000/protected). You should see a success message and, if you modify the protected route to display user data, the welcome message.
  5. Logout: Click the logout button on the protected route. You should be redirected back to the login page.
  6. Access Protected Route Without Login: Try to directly access the protected route without logging in. You should be redirected to the login page.

If you encounter any issues, carefully review the code, check the browser’s console for error messages, and ensure your environment variables are set correctly.

Common Mistakes and Troubleshooting

Here are some common mistakes and how to fix them:

  • Incorrect API Route Paths: Double-check that your API route paths (e.g., /api/auth/login, /api/protected) are correct.
  • CORS Errors: If you’re encountering CORS (Cross-Origin Resource Sharing) errors, make sure your API routes are configured to handle requests from your frontend’s origin. You might need to install and configure a CORS middleware.
  • Missing or Incorrect JWT Secret: Ensure your JWT secret is set correctly in your .env.local file and that you’re referencing it correctly in your code.
  • Incorrect Token Storage: Make sure you are correctly storing the token in local storage or cookies and retrieving it when making requests to protected routes.
  • Expired or Invalid Tokens: If you’re having trouble accessing protected routes, check the browser’s console for token-related errors. You might need to debug your token generation and verification logic.
  • Frontend Errors: Check the browser’s console for JavaScript errors, especially related to API requests.
  • Backend Errors: Check the server logs (terminal) for any server-side errors.

Enhancements and Advanced Techniques

This tutorial provides a basic foundation for authentication in Next.js. Here are some ways to enhance your authentication system:

  • Database Integration: Replace the in-memory user store with a database (e.g., PostgreSQL, MongoDB, MySQL) for persistent user data.
  • Social Login: Implement social login using providers like Google, Facebook, and Twitter.
  • Multi-Factor Authentication (MFA): Add an extra layer of security with MFA.
  • Role-Based Access Control (RBAC): Implement RBAC to control access to specific features or content based on user roles.
  • Password Reset Functionality: Allow users to reset their passwords.
  • Rate Limiting: Implement rate limiting to prevent brute-force attacks.
  • CSRF Protection: Implement CSRF (Cross-Site Request Forgery) protection to secure your forms.
  • Session Management: While JWTs are stateless, you can use cookies with JWTs for session management.

Summary / Key Takeaways

Authentication is a critical component of any web application that handles user data or provides access to protected resources. This guide walked you through the process of implementing a basic authentication system in Next.js using username/password and JWTs. We covered the core concepts, created API routes for signup and login, built frontend components, and demonstrated how to protect a route. Remember to always prioritize security by hashing passwords, storing your JWT secret in environment variables, and validating user inputs. By following these steps and exploring the enhancements, you can create robust and secure Next.js applications that protect user data and provide a great user experience.

FAQ

  1. What are the best practices for storing JWTs?
    You can store JWTs in local storage, cookies, or session storage. Local storage is a common choice, but be aware of potential XSS vulnerabilities. Cookies are more secure against XSS (if the `httpOnly` flag is set), but they can be vulnerable to CSRF attacks. Session storage is similar to local storage but the data is cleared when the tab is closed. Choose the storage method that best fits your application’s security requirements.
  2. How do I handle token expiration?
    When you generate a JWT, you specify an expiration time. After this time, the token is no longer valid. On the frontend, you can check the token’s expiration time and automatically redirect the user to the login page if the token has expired. You may also refresh the token using a refresh token strategy.
  3. How can I implement “remember me” functionality?
    You can implement “remember me” functionality by using a long-lived cookie or local storage to store a refresh token. When the user revisits the site, you can use the refresh token to obtain a new access token without requiring the user to re-enter their credentials. Be mindful of the security implications of storing long-lived tokens.
  4. What is the difference between JWT and OAuth?
    JWT (JSON Web Token) is a standard for securely transmitting information between parties. OAuth is an open standard for authorization. JWT is often used as the mechanism for carrying the user’s identity in an OAuth flow. OAuth allows a user to grant access to their resources on one site (e.g., Google) to another site (your application) without sharing their credentials.
  5. How do I handle user roles and permissions?
    You can add user roles and permissions to your JWT payload. When a user authenticates, you include their role (e.g., “admin”, “user”) in the JWT. On the backend, you can use the role to authorize access to specific resources or features.

Authentication is more than just a technical implementation; it’s about building trust with your users. By prioritizing security and following best practices, you can create applications that are not only functional but also secure, earning the confidence of your users and protecting their valuable data.

More posts