Authentication Flow

This document describes the authentication flow in the Tracker GraphQL application, including how the login process works and how authentication is handled for API requests.

Overview

The Tracker GraphQL application uses JWT (JSON Web Tokens) for authentication. When a user logs in, they receive an access token and a refresh token as HTTP-only cookies. These tokens are used to authenticate subsequent API requests.

Login Process

The login process follows these steps:

1. When a user attempts to access a protected resource without valid authentication:

   • The server returns a 401 Unauthorized response
   • The client redirects the user to the login page (/login.html)

2. On the login page:

   • The user enters their credentials (email and password)
   • The client sends a GraphQL mutation to the /graphql endpoint
   • If the credentials are valid, the server returns a success response and sets the JWT cookies
   • The client redirects the user back to the application

Authentication Middleware

The AuthMiddleware in app/middleware/auth.py handles authentication for all requests:

• It checks for the presence of a valid JWT token in cookies or the Authorization header
• It allows certain paths to be accessed without authentication (static files, login page, etc.)
• It handles token refresh when the access token expires
• It adds the authenticated user's client list to the request context for authorization

Token Refresh

When an access token expires:

1. The client attempts to refresh the token using the refresh token
2. If successful, the server issues a new access token and refresh token
3. The client retries the original request with the new access token
4. If the refresh token is invalid or expired, the user is redirected to the login page

Static File Serving

Static files are served from the root path (/) instead of a /static prefix. This allows for cleaner URLs and better organization of the application. The login page is served as /login.html directly from the static files directory.

Client-Side Authentication Handling

The client-side code handles authentication in several key components:

1. GraphQL Client (app/static/js/graphql/client.js):

   • Handles 401 responses from the GraphQL API
   • Attempts to refresh tokens when they expire
   • Redirects to the login page when authentication fails

2. Socket.IO Client (app/static/js/socket.js):

   • Establishes real-time connections with authentication
   • Handles authentication failures for socket connections
   • Redirects to the login page when socket authentication fails

3. Login Page (app/static/login.html):

   • Provides a simple login form
   • Handles login form submission
   • Displays error messages when login fails
   • Redirects to the application after successful login

Authentication Flow Diagram

Security Considerations

• JWT tokens are stored as HTTP-only cookies to prevent JavaScript access
• The server validates tokens on every request
• Refresh tokens have a longer expiration time than access tokens
• Authentication failures are logged for security monitoring
• The login page is served over HTTPS to protect credentials