TypeScript Tutorial: Building a Simple Web-Based Authentication App

Written by

learnmodernjavascript

in

In today’s interconnected world, securing user data is paramount. Authentication, the process of verifying a user’s identity, is the cornerstone of any application that handles sensitive information. Whether you’re building a social media platform, an e-commerce site, or a simple to-do list app, implementing secure and reliable authentication is crucial. This tutorial will guide you through building a simple, yet functional, web-based authentication application using TypeScript. We’ll explore the core concepts, best practices, and practical implementation details, empowering you to create secure and user-friendly applications.

Why TypeScript for Authentication?

TypeScript, a superset of JavaScript, offers several advantages when building authentication systems:

  • Type Safety: TypeScript’s static typing helps catch errors during development, reducing the likelihood of runtime bugs that could compromise security.
  • Code Readability: TypeScript’s type annotations and interfaces make your code easier to understand and maintain, especially in complex authentication workflows.
  • Enhanced Developer Experience: TypeScript provides better code completion, refactoring, and tooling support, leading to faster development cycles.
  • Scalability: TypeScript’s structure facilitates building large, maintainable authentication systems.

Core Concepts of Authentication

Before diving into the code, let’s understand the fundamental concepts:

  • Authentication: Verifying a user’s identity (e.g., username/password).
  • Authorization: Determining what a user is allowed to access after authentication.
  • Sessions: Maintaining a user’s logged-in state across multiple requests.
  • Tokens: Securely representing a user’s identity (e.g., JSON Web Tokens – JWTs).

Project Setup

Let’s set up the project. We’ll use Node.js, npm (or yarn), and a basic HTML structure.

  1. Create a Project Directory: Create a new directory for your project (e.g., `authentication-app`).
  2. Initialize npm: Navigate to the project directory in your terminal and run `npm init -y` to create a `package.json` file.
  3. Install TypeScript: Install TypeScript globally or locally. For local installation, run `npm install –save-dev typescript`.
  4. Create `tsconfig.json`: Run `npx tsc –init` in your terminal to generate a `tsconfig.json` file. This file configures the TypeScript compiler. You can customize the settings as per your needs. Here’s a basic `tsconfig.json` example: 
    {
  "compilerOptions": {
    "target": "es5",
    "module": "commonjs",
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  },
  "include": ["src/**/*"]
}
  5. Create Project Folders: Create `src` directory for your source code and `dist` directory for the compiled javascript.
  6. Install Dependencies: We will need some packages to create this app. For now, we’ll install `express` for the backend, and `@types/express` for the type definitions. 
    npm install express @types/express

Backend Implementation (Node.js & Express)

Let’s build a simple backend using Node.js and Express. This backend will handle user registration, login, and token generation. We’ll use a very basic in-memory store for user data for simplicity. Important: In a production environment, you would use a database (e.g., PostgreSQL, MongoDB) to store user credentials securely.

Create a file named `src/index.ts` and add the following code:

import express, { Request, Response } from 'express';
import { v4 as uuidv4 } from 'uuid';

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

app.use(express.json()); // Middleware to parse JSON request bodies

// In-memory user store (replace with a database in production)
interface User {
    id: string;
    username: string;
    passwordHash: string; // Store password hashes (NEVER store plain passwords)
    // You might include other user details here
}

const users: User[] = [];

// --- Utility Functions ---

// Simple password hashing (for demonstration purposes only; use a strong library in production)
const hashPassword = (password: string): string => {
    // In a real application, use bcrypt, Argon2, or a similar library
    return `hashed-${password}`; // Replace with actual hashing
};

// --- API Endpoints ---

// 1. User Registration
app.post('/register', (req: Request, res: Response) => {
    const { username, password } = req.body;

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

    // Check if the user already exists (basic check)
    if (users.some(user => user.username === username)) {
        return res.status(409).json({ message: 'Username already exists' });
    }

    const passwordHash = hashPassword(password);
    const newUser: User = {
        id: uuidv4(),
        username,
        passwordHash,
    };

    users.push(newUser);
    console.log('Registered users:', users)
    res.status(201).json({ message: 'User registered successfully' });
});

// 2. User Login
app.post('/login', (req: Request, res: Response) => {
    const { username, password } = req.body;

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

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

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

    const passwordHash = hashPassword(password);
    if (passwordHash !== user.passwordHash) {
        return res.status(401).json({ message: 'Invalid credentials' });
    }

    // --- Token generation (example) ---
    const token = `your-jwt-token-for-${user.id}`; // Replace with JWT generation

    res.status(200).json({ token, message: 'Login successful' });
});

// 3. Protected Route (example)
app.get('/profile', (req: Request, res: Response) => {
    // In a real app, you'd verify the token here
    const authHeader = req.headers.authorization;

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

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

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

    // For demonstration, we simply check if the token starts with a specific prefix
    if (token.startsWith('your-jwt-token-for-')) {
        res.status(200).json({ message: 'Profile data (protected)' });
    } else {
        res.status(401).json({ message: 'Unauthorized' });
    }
});


// Start the server
app.listen(port, () => {
    console.log(`Server listening at http://localhost:${port}`);
});

Here’s a breakdown of the backend code:

  • Imports: We import `express` for the server, `Request` and `Response` from express for type safety and `uuid` to generate unique user IDs.
  • Server Setup: We initialize an Express app and set up middleware to parse JSON request bodies.
  • In-Memory User Store: We create a simple in-memory array (`users`) to store user data. Important: In a real application, replace this with a database (e.g., PostgreSQL, MongoDB).
  • Utility Functions: We include a function for password hashing (for demonstration). Important: In production, use a robust hashing library like `bcrypt` or `Argon2`.
  • API Endpoints: We define three essential API endpoints:
    • `/register`: Handles user registration. It receives a username and password, validates the input, hashes the password (using our simplified method), and stores the user in the `users` array. It returns a success or error message.
    • `/login`: Handles user login. It receives a username and password, validates them against the stored data, and, upon successful authentication, generates a token (for demonstration, we create a placeholder token). In a real application, you’d use a library like `jsonwebtoken` to create a proper JWT. It returns the token and a success message.
    • `/profile`: A protected route that demonstrates how to check for a valid token. This route is accessed only after the user has logged in and has a valid token. This is a simplified example; a real-world application would use a more robust token verification mechanism.
  • Server Start: The server listens on the specified port (3000 in this case).

Important Security Considerations for the Backend:

  • Password Hashing: NEVER store passwords in plain text. Use a strong password hashing algorithm (e.g., bcrypt, Argon2) to securely hash passwords before storing them.
  • Input Validation: Always validate user input on both the client and server sides to prevent security vulnerabilities like SQL injection and cross-site scripting (XSS).
  • Token Security: Use HTTPS to encrypt all traffic between the client and server. Store tokens securely (e.g., in an HTTP-only cookie or local storage with appropriate security measures).
  • Rate Limiting: Implement rate limiting to prevent brute-force attacks.
  • Error Handling: Handle errors gracefully and avoid leaking sensitive information in error messages.
  • Database Security: If you use a database, secure it properly (e.g., strong passwords, regular backups, and appropriate access controls).

Frontend Implementation (HTML, JavaScript/TypeScript)

Now, let’s create a simple frontend to interact with our backend. We’ll use basic HTML, CSS, and JavaScript/TypeScript. We’ll keep the frontend as simple as possible to focus on the authentication flow.

Create the following files in a new folder called `public` in your project folder:

  • `public/index.html`: This is the main HTML file.
  • `public/style.css`: This file will contain the CSS styles.
  • `public/script.ts`: This file will contain the TypeScript code.

Here’s the HTML (`public/index.html`):

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Authentication App</title>
    <link rel="stylesheet" href="style.css">
</head>
<body>
    <div class="container">
        <h2>Authentication App</h2>

        <div id="register-form">
            <h3>Register</h3>
            <input type="text" id="register-username" placeholder="Username">
            <input type="password" id="register-password" placeholder="Password">
            <button onclick="register()">Register</button>
            <p id="register-message"></p>
        </div>

        <div id="login-form">
            <h3>Login</h3>
            <input type="text" id="login-username" placeholder="Username">
            <input type="password" id="login-password" placeholder="Password">
            <button onclick="login()">Login</button>
            <p id="login-message"></p>
        </div>

        <div id="profile-section" style="display: none;">
            <h3>Profile</h3>
            <p id="profile-message"></p>
            <button onclick="logout()">Logout</button>
        </div>
    </div>
    <script src="script.js"></script>
</body>
</html>

Here’s the CSS (`public/style.css`):

body {
    font-family: sans-serif;
    display: flex;
    justify-content: center;
    align-items: center;
    min-height: 100vh;
    background-color: #f0f0f0;
}

.container {
    background-color: white;
    padding: 20px;
    border-radius: 8px;
    box-shadow: 0 0 10px rgba(0, 0, 0, 0.1);
    width: 300px;
}

input {
    width: 100%;
    padding: 10px;
    margin-bottom: 10px;
    border: 1px solid #ccc;
    border-radius: 4px;
}

button {
    width: 100%;
    padding: 10px;
    background-color: #4CAF50;
    color: white;
    border: none;
    border-radius: 4px;
    cursor: pointer;
}

button:hover {
    background-color: #3e8e41;
}

#profile-section {
    margin-top: 20px;
}

And here’s the TypeScript code (`public/script.ts`):


// --- Helper Functions ---

const displayMessage = (id: string, message: string, color: string = 'green') => {
    const element = document.getElementById(id);
    if (element) {
        element.textContent = message;
        element.style.color = color;
    }
};

const clearMessages = () => {
    displayMessage('register-message', '');
    displayMessage('login-message', '');
    displayMessage('profile-message', '');
};

const showProfileSection = (show: boolean) => {
    const profileSection = document.getElementById('profile-section');
    if (profileSection) {
        profileSection.style.display = show ? 'block' : 'none';
    }
    const registerForm = document.getElementById('register-form');
    if (registerForm) {
        registerForm.style.display = show ? 'none' : 'block';
    }
    const loginForm = document.getElementById('login-form');
    if (loginForm) {
        loginForm.style.display = show ? 'none' : 'block';
    }
};

// --- API Calls ---

const register = async () => {
    clearMessages();
    const username = (document.getElementById('register-username') as HTMLInputElement)?.value;
    const password = (document.getElementById('register-password') as HTMLInputElement)?.value;

    if (!username || !password) {
        displayMessage('register-message', 'Username and password are required', 'red');
        return;
    }

    try {
        const response = await fetch('http://localhost:3000/register', {
            method: 'POST',
            headers: {
                'Content-Type': 'application/json',
            },
            body: JSON.stringify({ username, password }),
        });

        const data = await response.json();

        if (response.ok) {
            displayMessage('register-message', data.message);
        } else {
            displayMessage('register-message', data.message, 'red');
        }
    } catch (error) {
        displayMessage('register-message', 'An error occurred', 'red');
        console.error('Registration error:', error);
    }
};

const login = async () => {
    clearMessages();
    const username = (document.getElementById('login-username') as HTMLInputElement)?.value;
    const password = (document.getElementById('login-password') as HTMLInputElement)?.value;

    if (!username || !password) {
        displayMessage('login-message', 'Username and password are required', 'red');
        return;
    }

    try {
        const response = await fetch('http://localhost:3000/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 for this example)
            localStorage.setItem('token', data.token);
            displayMessage('login-message', data.message);
            showProfileSection(true);
            // Optionally, fetch and display profile data
            fetchProfileData();
        } else {
            displayMessage('login-message', data.message, 'red');
        }
    } catch (error) {
        displayMessage('login-message', 'An error occurred', 'red');
        console.error('Login error:', error);
    }
};

const fetchProfileData = async () => {
    clearMessages();
    const token = localStorage.getItem('token');

    if (!token) {
        showProfileSection(false);
        return;
    }

    try {
        const response = await fetch('http://localhost:3000/profile', {
            method: 'GET',
            headers: {
                'Authorization': `Bearer ${token}`,
            },
        });

        const data = await response.json();

        if (response.ok) {
            displayMessage('profile-message', data.message);
        } else {
            displayMessage('profile-message', data.message, 'red');
            logout(); // If the token is invalid, log the user out.
        }
    } catch (error) {
        displayMessage('profile-message', 'An error occurred', 'red');
        console.error('Profile fetch error:', error);
    }
};

const logout = () => {
    localStorage.removeItem('token');
    showProfileSection(false);
    clearMessages();
};

// Check for existing token on page load
document.addEventListener('DOMContentLoaded', () => {
    const token = localStorage.getItem('token');
    if (token) {
        showProfileSection(true);
        fetchProfileData();
    }
});

Explanation of the Frontend Code:

  • HTML Structure: The HTML provides the basic layout with registration and login forms, and a profile section that’s initially hidden.
  • CSS Styling: The CSS styles the HTML elements for a basic, clean look.
  • TypeScript Logic:
    • Helper Functions: `displayMessage` is used to display messages to the user. `clearMessages` clears any existing messages. `showProfileSection` shows or hides the profile section and login/register forms based on the login state.
    • API Calls: `register` sends a POST request to the `/register` endpoint. `login` sends a POST request to the `/login` endpoint. It stores the received token in local storage. `fetchProfileData` retrieves profile data from the `/profile` endpoint using the token. `logout` removes the token from local storage and hides the profile section.
    • Event Listeners: The `document.addEventListener(‘DOMContentLoaded’, …)` ensures that the code runs after the HTML has loaded. It checks for an existing token on page load and, if found, displays the profile section and fetches profile data.

Building and Running the Application

Here’s how to build and run your application:

  1. Compile the Backend: Open your terminal, navigate to your project directory, and run `npx tsc`. This will compile your TypeScript backend code into JavaScript, placing the output in the `dist` directory.
  2. Run the Backend: In the terminal, navigate to your project directory. Run `node dist/index.js` to start the Node.js server. You should see a message in the console indicating that the server is running (e.g., “Server listening on port 3000”).
  3. Compile the Frontend: In your project directory, run `npx tsc` again (if you haven’t already). This will compile the TypeScript frontend code into JavaScript, resulting in a `script.js` file in the `public` directory.
  4. Serve the Frontend: You can serve your frontend using a simple HTTP server. One easy way is to use the `serve` package (install it globally with `npm install -g serve`). Navigate to the `public` directory in your terminal and run `serve`. This will start a local server, usually on port 5000 (or another available port).
  5. Access the Application: Open your web browser and go to `http://localhost:5000` (or the address provided by `serve`). You should see the registration and login forms.
  6. Test the Application: Register a user, then log in. Upon successful login, the profile section should appear.

Common Mistakes and Troubleshooting

Here are some common mistakes and how to fix them:

  • CORS Errors: If you encounter CORS (Cross-Origin Resource Sharing) errors, it means your frontend is trying to access a different domain than your backend. To fix this, you need to configure your backend to allow requests from your frontend’s origin. In your Express app, you can use the `cors` middleware: 
    import cors from 'cors'; // Import the cors middleware

app.use(cors()); // Enable CORS for all origins (for development - be more specific in production)

    For production, restrict the allowed origins to your frontend’s domain. Install cors with `npm install cors`

  • Incorrect Paths: Double-check the paths in your `fetch` calls in the frontend to ensure they match your backend API endpoints (e.g., `/register`, `/login`, `/profile`).
  • Type Errors: TypeScript’s type checking can help you catch errors early. Make sure you are using types correctly. Check the console of your browser and terminal for any type errors.
  • Token Storage: For simplicity, we used `localStorage` to store the token. This is not the most secure method. For production, consider using HTTP-only cookies to store tokens.
  • Password Hashing Implementation: The example uses a simplified hashing. In a real-world scenario, you MUST use a strong password hashing library like `bcrypt` or `Argon2`.
  • Server Not Running: Make sure your backend server is running and listening on the correct port (default is 3000 in this example).
  • Frontend Not Served: Ensure your frontend files (HTML, CSS, JavaScript) are served by a web server (e.g., `serve`, or a development server).
  • Incorrect Headers: When making `fetch` requests, ensure you are setting the correct `Content-Type` header (e.g., `application/json`) for POST requests that send JSON data.
  • Debugging: Use your browser’s developer tools (Network tab, Console tab) to inspect network requests, view error messages, and debug any issues.

Key Takeaways

  • TypeScript enhances the development of authentication systems by providing type safety, code readability, and improved tooling.
  • Authentication involves verifying a user’s identity, while authorization controls access to resources.
  • A basic authentication flow includes registration, login, and protected routes.
  • Always prioritize security by using strong password hashing algorithms, validating user input, and securing tokens.
  • In a real-world application, use a database to store user credentials.

FAQ

  1. What is the difference between authentication and authorization?
    Authentication is the process of verifying a user’s identity (e.g., confirming they are who they claim to be). Authorization is the process of determining what a user is allowed to access after they have been authenticated.
  2. Why should I use TypeScript for authentication?
    TypeScript helps catch errors during development, improves code readability, and enhances the overall developer experience. It also makes your code more scalable and maintainable.
  3. How secure is local storage for storing tokens?
    Local storage is generally not the most secure place to store tokens. It is vulnerable to cross-site scripting (XSS) attacks. For production, consider using HTTP-only cookies, which are more secure.
  4. What is a JWT (JSON Web Token)?
    A JWT is a standard for securely transmitting information between parties as a JSON object. It is often used for authentication and authorization.
  5. What are some best practices for securing my authentication application?
    Use strong password hashing, validate user input, use HTTPS, store tokens securely (e.g., HTTP-only cookies), implement rate limiting, and protect against common web vulnerabilities.

Building a secure authentication system is a critical skill for modern web development. This tutorial has provided a practical foundation for implementing authentication with TypeScript. Remember to prioritize security at every stage of development, focusing on strong password hashing, secure token management, and robust input validation. By understanding these concepts and practices, you can create web applications that protect user data and provide a safe and reliable user experience. As you progress, explore advanced topics like multi-factor authentication, OAuth, and more sophisticated security measures to enhance the robustness of your applications. The principles of security are constantly evolving; staying informed and adapting to new threats is paramount. Continuously refine your understanding and stay vigilant in your pursuit of building secure and dependable web applications.

More posts