TypeScript Tutorial: Creating a Simple Web-Based Authentication System

Written by

learnmodernjavascript

in

In today’s digital landscape, securing user data is paramount. Building a robust authentication system is no longer a luxury, but a necessity for almost every web application. This tutorial will guide you through creating a simple, yet functional, web-based authentication system using TypeScript. We’ll cover everything from setting up the project to implementing user registration, login, and session management. By the end, you’ll have a solid understanding of the core concepts and be able to apply them to your own projects.

Why TypeScript for Authentication?

TypeScript offers several advantages when building complex applications like authentication systems:

  • Type Safety: TypeScript’s static typing helps catch errors early in the development process, reducing debugging time and improving code reliability.
  • Code Readability: Types and interfaces make your code easier to understand and maintain, especially in team environments.
  • Improved Developer Experience: TypeScript provides better autocompletion, refactoring, and other IDE features, leading to increased productivity.
  • Scalability: TypeScript facilitates building larger, more complex applications by providing structure and organization.

Project Setup

Let’s start by setting up our project. We’ll use Node.js and npm (or yarn) for package management. Open your terminal and create a new project directory:

mkdir typescript-auth-system
cd typescript-auth-system

Initialize a new npm project:

npm init -y

Install TypeScript and a few other necessary packages:

npm install typescript @types/node express express-session bcrypt cors

Explanation of the packages:

  • typescript: The TypeScript compiler.
  • @types/node: Type definitions for Node.js.
  • express: A web application framework for Node.js.
  • express-session: Middleware for handling user sessions.
  • bcrypt: A library for securely hashing passwords.
  • cors: Middleware for enabling Cross-Origin Resource Sharing.

Create a tsconfig.json file in your project root with the following configuration. This file tells the TypeScript compiler how to compile your code.

{
  "compilerOptions": {
    "target": "es2016",
    "module": "commonjs",
    "outDir": "./dist",
    "rootDir": "./src",
    "esModuleInterop": true,
    "forceConsistentCasingInFileNames": true,
    "strict": true,
    "skipLibCheck": true
  },
  "include": ["src/**/*"]
}

Create a src directory and inside it, create an index.ts file. This will be our main entry point.

User Model

Let’s define a user model. Create a file named src/models/User.ts:

// src/models/User.ts
export interface User {
  id: number;
  username: string;
  passwordHash: string; // Store the hashed password
  email: string;
}

This interface defines the structure of our user data. We’ll store the username, a hashed password (for security), an email, and a unique identifier (id).

Authentication Service

Now, let’s create an authentication service that will handle user registration, login, and session management. Create a file named src/services/authService.ts:

// src/services/authService.ts
import bcrypt from 'bcrypt';
import { User } from '../models/User';

// In-memory user store (replace with a database in a real application)
let users: User[] = [];

async function hashPassword(password: string): Promise {
  const saltRounds = 10;
  return bcrypt.hash(password, saltRounds);
}

async function registerUser(username: string, password: string, email: string): Promise {
  const existingUser = users.find(user => user.username === username || user.email === email);
  if (existingUser) {
    return null; // User already exists
  }

  const passwordHash = await hashPassword(password);
  const newUser: User = {
    id: users.length + 1,
    username,
    passwordHash,
    email,
  };
  users.push(newUser);
  return newUser;
}

async function loginUser(username: string, password: string): Promise {
  const user = users.find(user => user.username === username);
  if (!user) {
    return null; // User not found
  }

  const passwordMatch = await bcrypt.compare(password, user.passwordHash);
  if (!passwordMatch) {
    return null; // Incorrect password
  }

  return user;
}

export default {
  registerUser,
  loginUser,
};

Key points about the authService.ts:

  • We use bcrypt to hash passwords securely. Never store plain text passwords!
  • registerUser creates a new user, hashes the password, and stores the user in our in-memory store.
  • loginUser retrieves the user by username, compares the provided password with the stored hash, and returns the user if the credentials are valid.
  • For simplicity, we’re using an in-memory array (users) to store user data. In a production environment, you would use a database (e.g., PostgreSQL, MongoDB, MySQL).

API Endpoints

Next, we’ll create the API endpoints for user registration and login. Modify src/index.ts:

// src/index.ts
import express, { Request, Response } from 'express';
import session from 'express-session';
import cors from 'cors';
import authService from './services/authService';

const app = express();
const port = 3000;

app.use(cors()); // Enable CORS for all origins (for development - configure properly in production)
app.use(express.json()); // Middleware to parse JSON request bodies

// Session configuration
app.use(
  session({
    secret: 'your-secret-key', // Change this to a strong, random secret in production
    resave: false,
    saveUninitialized: false,
    cookie: {
      secure: false, // Set to true in production if using HTTPS
      httpOnly: true,
    },
  })
);

// Registration endpoint
app.post('/register', async (req: Request, res: Response) => {
  const { username, password, email } = req.body;
  if (!username || !password || !email) {
    return res.status(400).json({ message: 'Username, password, and email are required' });
  }

  try {
    const newUser = await authService.registerUser(username, password, email);
    if (newUser) {
      req.session!.user = newUser; // Store user in session after successful registration
      res.status(201).json({ message: 'User registered successfully', user: { id: newUser.id, username: newUser.username, email: newUser.email } });
    } else {
      res.status(409).json({ message: 'User already exists' });
    }
  } catch (error) {
    console.error(error);
    res.status(500).json({ message: 'Registration failed' });
  }
});

// Login endpoint
app.post('/login', async (req: Request, res: Response) => {
  const { username, password } = req.body;
  if (!username || !password) {
    return res.status(400).json({ message: 'Username and password are required' });
  }

  try {
    const user = await authService.loginUser(username, password);
    if (user) {
      req.session!.user = user; // Store user in session after successful login
      res.status(200).json({ message: 'Login successful', user: { id: user.id, username: user.username, email: user.email } });
    } else {
      res.status(401).json({ message: 'Invalid credentials' });
    }
  } catch (error) {
    console.error(error);
    res.status(500).json({ message: 'Login failed' });
  }
});

// Logout endpoint
app.post('/logout', (req: Request, res: Response) => {
  req.session!.destroy(err => {
    if (err) {
      console.error(err);
      return res.status(500).json({ message: 'Logout failed' });
    }
    res.status(200).json({ message: 'Logout successful' });
  });
});

// Protected route example
app.get('/profile', (req: Request, res: Response) => {
  if (req.session!.user) {
    res.json({ message: 'Profile data', user: { id: req.session!.user.id, username: req.session!.user.username, email: req.session!.user.email } });
  } else {
    res.status(401).json({ message: 'Unauthorized' });
  }
});

app.listen(port, () => {
  console.log(`Server is running on port ${port}`);
});

Explanation of the API endpoints:

  • /register (POST): Takes username, password, and email from the request body, registers the user using authService.registerUser, and returns a success or error message. If registration is successful, the user is stored in the session.
  • /login (POST): Takes username and password from the request body, logs the user in using authService.loginUser, and returns a success or error message. If login is successful, the user is stored in the session.
  • /logout (POST): Destroys the user’s session, effectively logging them out.
  • /profile (GET): A protected route that demonstrates how to check if a user is logged in (by checking the session).

Important:

  • CORS: We’ve enabled CORS for all origins using cors() for development purposes. In production, configure CORS properly to restrict access to your API to only allowed origins.
  • Session Secret: The secret in the session configuration is extremely important. Use a strong, randomly generated secret key in production. Never hardcode it or commit it to your repository.
  • HTTPS and Secure Cookies: In production, when using HTTPS, set cookie: { secure: true } in your session configuration to ensure the session cookie is only sent over secure connections.

Running the Application

To run your application, compile the TypeScript code and start the server:

npm run build # or npx tsc
node dist/index.js

Now, you can test your API endpoints using tools like Postman or curl. Here’s how you might test the registration endpoint:

curl -X POST -H "Content-Type: application/json" -d '{"username":"testuser", "password":"password", "email":"test@example.com"}' http://localhost:3000/register

And the login endpoint:

curl -X POST -H "Content-Type: application/json" -d '{"username":"testuser", "password":"password"}' http://localhost:3000/login

And the logout endpoint:

curl -X POST http://localhost:3000/logout

And finally the profile endpoint. You will need to login first.

curl -X GET http://localhost:3000/profile

Common Mistakes and Solutions

Here are some common mistakes and how to fix them:

  • Storing Passwords in Plain Text: Never store passwords in plain text. Always hash them using a library like bcrypt. This is a critical security vulnerability.
  • Using Weak Session Secrets: Use a strong, randomly generated secret key for your session configuration. A weak secret can compromise user sessions.
  • Incorrect CORS Configuration: For production, configure CORS to allow only specific origins. Allowing all origins (cors() without configuration) is a security risk.
  • Not Using HTTPS in Production: Always use HTTPS in production to encrypt all communication between the client and server. This is essential for protecting sensitive data, including login credentials and session cookies.
  • Failing to Sanitize User Input: Always sanitize and validate user input to prevent vulnerabilities like SQL injection and cross-site scripting (XSS) attacks.
  • Ignoring Error Handling: Implement proper error handling throughout your application to catch unexpected issues and provide informative error messages to the user.

Key Takeaways

  • TypeScript enhances code quality and maintainability in authentication systems.
  • Bcrypt is essential for secure password hashing.
  • Session management is crucial for user authentication.
  • Always prioritize security best practices.

FAQ

Here are some frequently asked questions:

  1. What is the purpose of bcrypt? Bcrypt is a password hashing algorithm designed to securely store passwords. It adds salt and uses a computationally expensive algorithm to make it difficult for attackers to crack passwords.
  2. Why use sessions? Sessions allow you to maintain user state across multiple requests. They store user data (like login status) on the server-side, associated with a unique session ID stored in a cookie on the client-side.
  3. How do I deploy this application? You can deploy this application to various platforms such as Heroku, AWS, or Azure. You’ll need to configure a database, set up environment variables for your secret key, and handle HTTPS configuration.
  4. How can I add more features? You can extend this authentication system by adding features like password reset, two-factor authentication (2FA), social login, and role-based access control (RBAC).
  5. Why use TypeScript for this? TypeScript helps to catch errors early, improves code readability, and enhances developer experience, making it easier to build and maintain complex systems like authentication.

Building a web-based authentication system using TypeScript is a crucial step in securing your web applications. By following the steps outlined in this tutorial, you’ve created a functional authentication system that you can expand upon. Remember to always prioritize security best practices, and you’ll be well on your way to building secure and reliable web applications. The concepts presented here form a solid foundation for more complex authentication implementations, allowing you to tailor your system to fit specific project needs. Always keep security at the forefront of your development process, and your users will thank you for it.

More posts