api-jwt-authenticator

When to Use This Skill

Use this conceptual skill when you need to implement secure JWT-based authentication for FastAPI REST APIs. This skill is appropriate for:

• Protecting API endpoints that require user authentication
• Enforcing user-specific access control (ensuring users can only access their own resources)
• Implementing stateless authentication in microservices
• Securing REST APIs with standard JWT token validation
• Adding role-based access control (RBAC) to API endpoints

This skill should NOT be used for:

• Public APIs that don't require authentication
• APIs that use alternative authentication methods (OAuth, API keys, etc.)
• Simple applications where basic auth is sufficient

Prerequisites

• Understanding of JWT (JSON Web Token) concepts
• FastAPI application framework knowledge
• Basic security principles and authentication patterns
• Environment for managing secret keys securely

Conceptual Implementation Framework

JWT Token Extraction Capability

• Extract JWT tokens from the Authorization header in the format "Bearer <token>"
• Handle malformed or missing authorization headers appropriately
• Validate the presence of the "Bearer" prefix in the header

Token Validation Capability

• Validate JWT tokens using a shared secret key
• Verify token signature to ensure integrity
• Check token expiration (exp) claim to prevent usage of expired tokens
• Validate token issuer (iss) and audience (aud) claims when applicable

User Identity Verification Capability

• Extract user identity information from the token payload
• Compare the user ID in the token with the requested resource
• Enforce access control rules based on user identity
• Ensure users can only access resources belonging to them

Error Handling Capability

• Generate appropriate HTTP 401 Unauthorized responses for invalid tokens
• Generate HTTP 403 Forbidden responses for insufficient permissions
• Provide clear error messages without exposing sensitive information
• Log authentication failures for security monitoring

Expected Input/Output

Input Requirements:

1. JWT Token Format:

   • Token must be in the Authorization header as Bearer <token>
   • Token must contain valid JWT structure with required claims
   • Token must not be expired

2. Token Claims:

   • sub (subject): User identifier
   • exp (expiration): Token expiration timestamp
   • user_id (optional): Unique user identifier for access control
   • role (optional): User role for role-based access control

Output Formats:

1. Successful Authentication Response:

   • HTTP 200 OK for protected endpoints
   • Response body with authenticated user information
   • Properly authenticated user context for downstream processing

2. 401 Unauthorized Response (Invalid/Expired Token):

   • HTTP 401 status code
   • Error message: "Could not validate credentials"
   • Appropriate WWW-Authenticate header

3. 403 Forbidden Response (Insufficient Permissions):

   • HTTP 403 status code
   • Error message: "Access forbidden: Insufficient permissions"
   • Clear indication of permission issue

4. Token Generation Response (when applicable):

   • HTTP 200 OK
   • Response body containing access token and token type
   • Secure token delivery mechanism

Security Considerations

1. Token Transmission: Always use HTTPS in production to prevent token interception
2. Token Storage: Store secret keys securely in environment variables or secure vaults
3. Token Expiration: Set appropriate expiration times to limit exposure windows
4. Token Validation: Always validate token signature and claims before trusting
5. Information Disclosure: Avoid exposing sensitive information in error messages
6. Rate Limiting: Implement rate limiting to prevent brute force attacks
7. Logging: Log authentication events for security monitoring without storing tokens

Integration Patterns

Dependency Injection Pattern

• Use FastAPI's dependency system to inject authentication requirements
• Apply authentication dependencies to specific routes or entire routers
• Combine multiple authentication requirements as needed

Middleware Integration

• Implement authentication as middleware for global application
• Handle authentication at the application level
• Centralize authentication logic for consistent enforcement

Role-Based Access Control (RBAC)

• Define roles and permissions in token claims
• Implement role verification in authentication dependencies
• Enforce role-based access to specific endpoints

Testing Considerations

• Test authentication failure scenarios (invalid tokens, expired tokens)
• Verify user-specific access control rules
• Test role-based access restrictions
• Validate error response formats and status codes
• Test token refresh mechanisms (if implemented)

Performance Implications

• JWT validation has minimal computational overhead
• Consider token caching strategies for high-traffic applications
• Balance token expiration time with performance requirements
• Monitor authentication-related latency in production