Web API User Authentication & Authorization

TL;DR

Use JWT (JSON Web Tokens) for stateless authentication and authorization. Implement a robust password hashing system (like bcrypt). Protect your API endpoints with appropriate roles/permissions.

1. Choose an Authentication Method: JWTs

JWTs are the industry standard for web APIs because they’re secure, scalable, and don’t require server-side sessions. Here’s how it works:

• User Login: The user provides credentials (username/password).
• Server Verification: Your server verifies the credentials against your database.
• Token Generation: If valid, the server creates a JWT containing user information and signs it with a secret key.
• Token Return: The JWT is sent back to the client (usually in the response body).
• Subsequent Requests: The client includes the JWT in the Authorization header of every API request (e.g., Bearer <token>).
• Server Validation: Your server verifies the token’s signature and extracts user information.

2. Secure Password Storage

Never store passwords in plain text! Use a strong hashing algorithm like bcrypt.

• bcrypt: Adds salt to each password before hashing, making it very difficult to crack even if the database is compromised.

# Example using Python and the bcrypt library
import bcrypt

password = b"mysecretpassword"
hashed_password = bcrypt.hashpw(password, bcrypt.gensalt()) 
print(hashed_password)

# To check if a password matches:
if bcrypt.checkpw(b"mysecretpassword", hashed_password):
    print("Password matches!")
else:
    print("Incorrect password.")

3. Implement User Registration

1. Collect User Data: Gather necessary information (username, email, password, etc.).
2. Validate Input: Ensure data is valid and meets security requirements (e.g., strong password).
3. Hash Password: Use bcrypt to hash the user’s password before storing it in the database.
4. Store User Data: Save the hashed password and other user information in your database.

4. Implement Login

1. Collect Credentials: Get username/password from the client.
2. Retrieve User: Find the user in the database by their username.
3. Verify Password: Use bcrypt to compare the provided password with the stored hashed password.
4. Generate JWT: If valid, create a JWT containing user information (e.g., user ID, roles).
5. Return JWT: Send the JWT back to the client.

5. Protect API Endpoints

Use middleware to protect your API endpoints and verify the JWT.

• Middleware: Intercepts incoming requests before they reach your endpoint handlers.
• Token Extraction: Extract the JWT from the Authorization header.
• Token Validation: Verify the token’s signature and expiration date.
• User Information Access: If valid, extract user information from the token (e.g., user ID, roles).
• Authorization Check: Ensure the user has the necessary permissions to access the endpoint.

# Example using Node.js and Express with JWT middleware
const jwt = require('jsonwebtoken');

function authenticateToken(req, res, next) {
  const authHeader = req.headers['authorization'];
  if (authHeader) {
    const token = authHeader.split(' ')[1]; // Bearer <token>
    jwt.verify(token, 'your-secret-key', (err, user) => {
      if (err) {
        return res.status(403).json({ message: 'Invalid token' });
      }
      req.user = user; // Attach user information to the request object
      next();
    });
  } else {
    return res.status(401).json({ message: 'No token provided' });
  }
}

6. Roles and Permissions

Implement a system to define roles (e.g., admin, user) and permissions (e.g., read, write, delete).

• Role-Based Access Control (RBAC): Assign roles to users and associate permissions with those roles.
• Permission Checks: In your middleware, check if the user’s role has the necessary permission to access the endpoint.

7. Token Expiration & Refresh Tokens

JWTs should have a limited lifespan (e.g., 1 hour). Implement refresh tokens to allow users to stay logged in without re-entering their credentials.

• Short-Lived JWT: Use short expiration times for the main access token.
• Refresh Token: Issue a long-lived refresh token along with the access token.
• Token Refresh Endpoint: Provide an endpoint where users can exchange their refresh token for a new access token.