Overview

This document describes the migration to a secure, enterprise-grade authentication system following BigTech standards (Google, AWS, Auth0). This is a BREAKING CHANGE that will require all users to re-login.

What Changed?

Security Improvements

1. httpOnly Cookies for Refresh Tokens
2. Refresh tokens are now stored in httpOnly cookies (instead of localStorage)
3. XSS attacks can no longer steal long-lived refresh tokens

4. Automatic cookie handling by browser (no JS access)

5. In-Memory Access Tokens

6. Access tokens stored only in memory (class field)
7. Tokens disappear when tab/window closes

8. No persistence in localStorage

9. CSRF Protection

10. CSRF tokens for cookie-based authentication
11. Double-submit cookie pattern

12. Protection against cross-site request forgery

13. Token Rotation

14. Refresh tokens rotated on every use
15. Replay detection with automatic family revocation

16. Minimizes window of compromise

17. Security Headers

18. Content Security Policy (CSP)
19. HTTP Strict Transport Security (HSTS)
20. X-Frame-Options, X-Content-Type-Options, etc.

API Changes

Backend (/v1/token endpoint)

New Query Parameter: response_mode

1
2
3

POST /v1/token?response_mode=cookie  # Web clients (httpOnly cookie)
POST /v1/token?response_mode=json    # Mobile clients (JSON response)
POST /v1/token                       # Default = json (backward compatible)

Response Changes for Web Clients (response_mode=cookie):

Before:

1
2
3
4
5
6

{
  "access_token": "eyJ...",
  "refresh_token": "abc123...",
  "token_type": "Bearer",
  "expires_in": 900
}

After:

1
2
3
4
5
6

{
  "access_token": "eyJ...",
  "csrf_token": "xyz789...",
  "token_type": "Bearer",
  "expires_in": 900
}

• Set-Cookie: refresh_token=abc123...; HttpOnly; Secure; SameSite=Strict; Path=/v1/token; Max-Age=2592000

Database Changes:

New field in refresh_sessions table:

1

ALTER TABLE refresh_sessions ADD COLUMN metadata JSONB DEFAULT NULL;

Frontend

Removed: - All localStorage operations for tokens - httpClient.setRefreshToken() method - httpClient.getRefreshToken() method

Added: - httpClient.getCsrfToken() - get CSRF token from sessionStorage - httpClient.setCsrfToken() - store CSRF token in sessionStorage - Automatic X-CSRF-Token header on state-changing requests (POST/PUT/PATCH/DELETE) - withCredentials: true on all API requests (sends cookies)

Token Storage: - Access token: Memory only (httpClient.accessToken private field) - CSRF token: sessionStorage (csrf_token key) - Refresh token: httpOnly cookie (managed by browser, not accessible via JS)

Configuration

Environment Variables

Add these settings to your .env file or environment:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

# Token Cookie Settings (optional, defaults shown)
TOKEN__TOKENS__COOKIE_NAME=refresh_token
TOKEN__TOKENS__COOKIE_PATH=/v1/token
TOKEN__TOKENS__COOKIE_DOMAIN=  # Leave empty for current domain
TOKEN__TOKENS__COOKIE_SECURE=true
TOKEN__TOKENS__COOKIE_HTTPONLY=true
TOKEN__TOKENS__COOKIE_SAMESITE=strict

# CORS Settings (required for web clients)
TOKEN__CORS__ENABLED=true
TOKEN__CORS__ALLOW_ORIGINS=["https://stage.ai-ops.tech","https://app.ai-ops.tech"]
TOKEN__CORS__ALLOW_CREDENTIALS=true

For development:

1

TOKEN__CORS__ALLOW_ORIGINS=["http://localhost:5173","http://localhost:3000"]

For production:

1
2

TOKEN__CORS__ALLOW_ORIGINS=["https://app.ai-ops.tech"]
TOKEN__TOKENS__COOKIE_SECURE=true

Database Migration

1. Apply database migration:

   1 2	# Add metadata column to refresh_sessions kubectl exec -it session-token-service-pod -- python -m alembic upgrade head

2. Deploy session-token-service with new code:

   1 2 3 4 5 6 7

   cd services/auth/session-token-service uv sync # Run tests pytest # Build and deploy docker build -t session-token-service:v2 . kubectl apply -f k8s/session-token-service/

3. Verify CORS configuration:

   1 2 3 4 5

   curl -H "Origin: https://stage.ai-ops.tech" \ -H "Access-Control-Request-Method: POST" \ -H "Access-Control-Request-Headers: X-CSRF-Token" \ -X OPTIONS \ https://api.stage.ai-ops.tech/v1/token

Should return:

1
2
3
4

Access-Control-Allow-Origin: https://stage.ai-ops.tech
Access-Control-Allow-Credentials: true
Access-Control-Allow-Methods: POST, ...
Access-Control-Expose-Headers: X-CSRF-Token, ...

2. Deploy Frontend Changes

1. Build and deploy web-app:

   1 2 3 4 5

   cd services/web-app npm install npm run build docker build -t web-app:v2 . kubectl apply -f k8s/web-app/

2. Clear browser storage (optional, but recommended for testing):

   1 2 3

   // In browser console localStorage.clear(); sessionStorage.clear();

3. User Communication

Announcement Template:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

Subject: Security Upgrade - Re-login Required

We're upgrading our authentication system to enterprise-grade security
standards used by Google, AWS, and other tech leaders.

What you need to do:
- Re-login once after deployment (automatic logout will happen)
- No other action required

What's improved:
- Enhanced protection against XSS attacks
- Stronger token security with httpOnly cookies
- CSRF protection for all requests
- Automatic token rotation

Deployment date: [DATE]
Expected downtime: None (rolling deployment)

Thank you for your understanding!

Testing Checklist

Security Testing

• [ ] XSS Protection
• Open DevTools Console
• Try document.cookie - should NOT see refresh_token

• Try localStorage.getItem("refresh_token") - should be null

• [ ] CSRF Protection

• Remove X-CSRF-Token header in DevTools

• Try POST request - should fail with 403

• [ ] Token Rotation

• Login successfully
• Get refresh_token cookie value from DevTools
• Wait for access_token to expire
• Make API request (triggers refresh)

• Check refresh_token cookie - should have NEW value

• [ ] Session Expiration

• Wait 30 days (or manually delete cookie)
• Try to make API request

• Should redirect to login

• [ ] Logout

• Click logout
• Check DevTools: no access_token in memory, no csrf_token in sessionStorage
• Check cookies: refresh_token should be deleted

Functional Testing

• [ ] Login flow works
• [ ] Logout flow works
• [ ] Token refresh works (automatic on 401)
• [ ] API requests include Authorization: Bearer <token>
• [ ] API requests include X-CSRF-Token header
• [ ] Browser sends refresh_token cookie automatically

Browser Compatibility

Test in: - [ ] Chrome/Edge (latest) - [ ] Firefox (latest) - [ ] Safari (latest)

Rollback Plan

If critical issues found:

1. Revert frontend to previous version:

   1	kubectl rollout undo deployment/web-app

2. Users will need to re-login again (acceptable for security fix)

3. Backend remains backward compatible (supports both old and new flows)

Monitoring

Watch these metrics after deployment:

1. Token endpoint errors:

   1	rate(http_requests_total{endpoint="/v1/token", status=~"4.."}[5m])

2. Refresh success rate:

   1	rate(token_refreshed_total[5m]) / rate(token_refresh_attempts_total[5m])

3. CSRF errors:

   1	rate(csrf_errors_total[5m])

4. User re-logins:

   1	rate(user_login_total[1h])

FAQ

Q: Why do all users need to re-login? A: We're changing how tokens are stored (localStorage → httpOnly cookies). Old tokens in localStorage won't work with the new system.

Q: Will this affect mobile apps? A: No. Mobile apps can continue using JSON-based flow with response_mode=json or default behavior.

Q: How long do sessions last now? A: Same as before - 15 minutes for access tokens, 30 days for refresh tokens.

Q: Can users stay logged in forever? A: No. After 30 days of inactivity, refresh token expires and re-login is required.

Q: What if I clear cookies? A: You'll need to re-login. This is expected behavior for security.

References

• OAuth2 RFC 6749
• OWASP CSRF Prevention
• Google OAuth2 Implementation
• AWS Cognito Best Practices