Welcome back! In the previous lesson, we explored how to implement and rotate refresh tokens using Pydantic models for validation in a Python-based REST API using FastAPI. Now, we will focus on securing these tokens against theft.

Token security refers to the measures and practices implemented to protect authentication tokens (like refresh tokens and access tokens) from unauthorized access, theft, or misuse. In modern web applications, tokens are the keys to your kingdom - if compromised, attackers can impersonate legitimate users and gain unauthorized access to protected resources.

Refresh tokens are particularly sensitive because:

• They have longer lifespans than access tokens
• They can generate new access tokens repeatedly
• They often grant extended access without requiring re-authentication
• They may persist across multiple sessions and devices

Pros:

• Stateless authentication that scales well
• Reduced database lookups for authentication
• Support for cross-domain authentication
• Better user experience with reduced login frequency

Cons:

• Security vulnerabilities if tokens are stolen
• Complexity in token management and rotation
• Challenges in immediate token revocation
• Potential for replay attacks if not properly protected

To detect token theft, we first need to track how tokens are being used. The RefreshLog model serves as our security journal, recording important details each time a refresh token is used:

Key Concept: This model creates a detailed audit trail of token usage. We're tracking not just when tokens are used, but also from where (IP address) and with what device (user agent). This contextual information is crucial for identifying suspicious patterns that might indicate token theft.

Just like we use Pydantic for request validation, we can use it for response models to ensure consistent API responses:

With our logging system in place, we can now implement the logic to detect potential token theft. Let's break this down into manageable pieces to better understand each component.

First, let's set up our FastAPI router and import the necessary dependencies:

This function analyzes token usage patterns to identify suspicious behavior and returns a Pydantic model:

Now let's implement the critical endpoint that handles refresh token requests with full Pydantic validation:

Let's implement an endpoint for security administrators to analyze token usage:

Our token theft detection approach works through these key mechanisms:

1. Contextual Information Collection: We capture IP address and user agent with each request, using our secure JWT secret from config.py for token operations.

2. Complete Audit Trail: We log every token usage attempt before checking validity.

3. Pattern Detection: We analyze usage patterns, particularly focusing on:

   • Multiple IP addresses using the same token
   • Unusual geographical access patterns
   • Frequency of successful and failed attempts

4. Automated Response: When suspicious patterns are detected, we:

   • Immediately invalidate all tokens for the affected user
   • Force re-authentication
   • Log the security incident

5. Administrative Analysis: Security teams can use the /analyze-logs/{user_id} endpoint to:

   • Review token usage patterns with structured Pydantic responses
   • Identify potential security issues
   • Take proactive measures before breaches occur

This approach balances security with user experience by focusing on truly suspicious patterns rather than normal usage variations.

To verify our detection system works, we'll simulate a token theft scenario:

Test Logic: This test demonstrates a real-world scenario where:

1. A legitimate user uses their token normally

While we've implemented a robust theft detection mechanism, it's important to follow additional security best practices:

• Regularly audit your security logs to identify unusual patterns.
• Keep your dependencies and libraries up to date to patch known vulnerabilities.
• Educate users about the importance of securing their tokens and accounts.
• Implement risk-based authentication for sensitive operations.
• Consider using geographical restrictions for token usage based on user's common locations.
• Always use environment variables for JWT secrets in production (never hardcode them).
• Use Pydantic models for all API inputs and outputs to ensure validation and type safety.

These practices help maintain a secure environment and protect against evolving threats.

In this lesson, we explored how to detect and protect against stolen tokens in a Python-based REST API using FastAPI, SQLAlchemy, and Pydantic models. We implemented a comprehensive logging mechanism with secure secret management via config.py, identified suspicious token usage patterns, and provided administrative tools for ongoing security monitoring with type-safe Pydantic responses. By following these steps, you can enhance the security of your API and safeguard user data.

Congratulations on completing the unit! You've learned essential techniques for securing a Python REST API. Remember to apply these security measures in your projects and continue exploring advanced security topics. Well done!