Authentication Guide

Overview

The SSO service uses token-based authentication with secure session management. All authentication tokens are cryptographically signed and include expiration timestamps.

Authentication Flow

1. User Registration

   New users must first register with their email and password:

   // Register a new user
   const response = await fetch('/api/users/register', {
     method: 'POST',
     headers: {
       'Content-Type': 'application/json'
     },
     body: JSON.stringify({
       email: 'user@example.com',
       password: 'securepassword',
       name: 'John Doe'
     })
   });

2. User Login

   Registered users can authenticate to receive a session token:

   // Login and receive session token
   const response = await fetch('/api/users', {
     method: 'POST',
     headers: {
       'Content-Type': 'application/json'
     },
     body: JSON.stringify({
       email: 'user@example.com',
       password: 'securepassword'
     })
   });
   
   const { sessionToken } = await response.json();

3. Using Session Token

   Include the session token in subsequent API requests:

   // Make authenticated requests
   const response = await fetch('/api/users/profile', {
     headers: {
       'Authorization': `Bearer ${sessionToken}`
     }
   });

4. Session Validation

   Validate session status and expiration:

   // Check session validity
   const response = await fetch('/api/sso/validate', {
     headers: {
       'Authorization': `Bearer ${sessionToken}`
     }
   });
   
   // Check X-Session-Expires header for expiration
   const expiresAt = response.headers.get('X-Session-Expires');

5. Logout

   End the session when finished:

   // Logout and invalidate session
   await fetch('/api/users/logout', {
     method: 'POST',
     headers: {
       'Authorization': `Bearer ${sessionToken}`
     }
   });

Security Considerations

• All authentication requests must use HTTPS
• Session tokens expire after 24 hours of inactivity
• Failed login attempts are rate-limited
• Passwords must meet minimum complexity requirements
• Session tokens are automatically rotated for security

Error Handling

Common authentication errors and how to handle them:

• INVALID_CREDENTIALS

  Username or password is incorrect

• SESSION_EXPIRED

  Session token has expired - user needs to login again

• INVALID_TOKEN

  Session token is malformed or has been tampered with

• RATE_LIMIT_EXCEEDED

  Too many failed authentication attempts

Best Practices

• Store session tokens securely (e.g., in HttpOnly cookies)
• Implement proper CORS policies for cross-origin requests
• Always validate session status before accessing protected resources
• Clear session data on logout
• Handle authentication errors gracefully in the UI