Auth0 SSO Authentication Middleware

[butschster]

This feature request outlines the development of a comprehensive Auth0 SSO authentication middleware for RoadRunner that provides enterprise-grade authentication capabilities with flexible URL protection patterns and seamless integration with PHP applications.

Core Requirements

1. Authentication Flow

• OAuth2 + OpenID Connect integration with Auth0
• Universal Login Page redirection for unauthenticated users
• Callback handling for Auth0 responses
• Session management with configurable storage (memory-based for RR artifacts)
• Token validation and refresh capabilities
• Logout flow with proper Auth0 logout URL redirection

2. URL Protection Patterns

• Global protection - protect all routes by default
• Pattern-based protection - protect specific URL patterns using regex or glob patterns
• Exclusion patterns - exclude specific URLs from authentication (e.g., health checks, public assets)
• Route-level configuration - allow per-route authentication requirements

3. User Information Injection

• PSR7 attributes injection with user profile data
• Configurable attribute names for user information
• Claims extraction from ID tokens
• Role/permission mapping from Auth0 user metadata

4. Configuration Management

• Environment-based configuration via .rr.yaml
• Auth0 domain and credentials configuration
• Session configuration (timeout, cookie settings)
• URL pattern configuration for protection rules
• Callback URL configuration

Technical Specifications

Configuration Structure (.rr.yaml)

auth0:
  # Auth0 Configuration
  domain: "your-tenant.auth0.com"
  client_id: "${AUTH0_CLIENT_ID}"
  client_secret: "${AUTH0_CLIENT_SECRET}"
  
  # Callback Configuration
  callback_url: "http://localhost:8080/auth/callback"
  logout_url: "http://localhost:8080"
  
  # Session Configuration
  session:
    cookie_name: "auth0_session"
    secret_key: "${SESSION_SECRET}"
    max_age: 3600 # 1 hour
    secure: false # set to true in production
    http_only: true
    same_site: "lax"
  
  # URL Protection Configuration
  protection:
    mode: "pattern" # "global", "pattern", "disabled"
    
    # Protected URL patterns (regex)
    protected_patterns:
      - "^/admin/.*"
      - "^/user/profile.*"
      - "^/api/private/.*"
    
    # Excluded URL patterns (regex) - these bypass authentication entirely
    excluded_patterns:
      - "^/health.*"
      - "^/public/.*"
      - "^/assets/.*"
    
    # Public routes that bypass authentication
    public_routes:
      - "/"
      - "/about"
      - "/contact"
  
  # User Attribute Configuration
  user_attributes:
    profile_attribute: "auth0_user"
    claims_attribute: "auth0_claims"
    roles_attribute: "auth0_roles"
  
  # Auth0 Scopes
  scopes:
    - "openid"
    - "profile"
    - "email"
  
  # Authentication Routes (handled by RoadRunner middleware, NOT passed to PHP)
  routes:
    login: "/auth/login"        # RR handles: redirect to Auth0
    callback: "/auth/callback"  # RR handles: OAuth callback processing
    logout: "/auth/logout"      # RR handles: session cleanup + Auth0 logout
    user_info: "/auth/user"     # RR handles: return user profile as JSON

http:
  middleware: ["auth0"]

Environment Variables

# Auth0 Configuration
AUTH0_DOMAIN=your-tenant.auth0.com
AUTH0_CLIENT_ID=your_client_id
AUTH0_CLIENT_SECRET=your_client_secret

# Session Security
SESSION_SECRET=your_random_session_secret_key

# Optional: Override URLs
AUTH0_CALLBACK_URL=http://localhost:8080/auth/callback
AUTH0_LOGOUT_URL=http://localhost:8080

User Stories

US1: Global Authentication Protection

As a system administrator
I want to protect all application routes by default
So that unauthorized users cannot access any part of the application

Acceptance Criteria:

• All HTTP requests are intercepted by the middleware
• Unauthenticated requests are redirected to Auth0 login
• Authenticated requests proceed with user information injected
• Public routes can be explicitly excluded

US2: Pattern-Based Route Protection

As a developer
I want to configure specific URL patterns for authentication
So that I can have granular control over which routes require authentication

Acceptance Criteria:

• Support regex patterns for protected routes
• Support exclusion patterns for public content
• Patterns are configurable via .rr.yaml
• Invalid patterns log errors but don't break the middleware

US3: User Information Access in PHP

As a PHP developer
I want to access authenticated user information in my PHP application
So that I can implement user-specific functionality

Acceptance Criteria:

• User profile is available via PSR7 request attributes
• User claims/roles are accessible
• Attribute names are configurable
• Information is properly serialized for PHP consumption

US4: Session Management

As a user
I want my authentication session to be maintained across requests
So that I don't have to re-authenticate frequently

Acceptance Criteria:

• Sessions are maintained using secure cookies
• Session expiration is configurable
• Sessions can be invalidated on logout
• Session security follows best practices

Architecture Components

1. Main Plugin (plugin.go)

• Implements RoadRunner plugin interfaces
• Handles dependency injection (logger, config)
• Manages Auth0 client initialization
• Implements middleware interface

2. Auth0 Client (auth0/client.go)

• Wraps OAuth2 and OIDC libraries
• Handles Auth0 API communication
• Token validation and refresh
• User profile retrieval

3. Session Manager (session/manager.go)

• In-memory session storage (RR compatible)
• Session lifecycle management
• Cookie handling
• Security implementations

4. Route Handler (handlers/handlers.go)

• RoadRunner-native route handling for auth endpoints
• Login redirect handler (direct Auth0 redirect, no PHP involvement)
• OAuth callback handler (token exchange and session creation in RR)
• Logout handler (session cleanup and Auth0 logout redirect in RR)
• User info endpoint handler (JSON response with user data, handled by RR)
• No PHP involvement for authentication routes

5. URL Matcher (matcher/matcher.go)

• Pattern matching logic
• Route protection evaluation
• Configuration-based routing decisions

6. User Context (context/user.go)

• User information structures
• PSR7 attribute injection
• Claims processing
• Role/permission mapping

Security Considerations

1. Token Security

• PKCE (Proof Key for Code Exchange) for OAuth2 flows
• State parameter validation to prevent CSRF
• Nonce validation for ID tokens
• Token encryption in sessions

2. Session Security

• HTTP-only cookies to prevent XSS
• Secure cookie flag for HTTPS environments
• SameSite attribute for CSRF protection
• Session timeout and rotation

3. Configuration Security

• Environment variable usage for sensitive data
• Configuration validation on startup
• Secure defaults for all security settings

Performance Considerations

1. Caching Strategy

• In-memory user session cache
• Token validation caching
• Configuration caching
• Pattern matching optimization

2. Resource Management

• Connection pooling for Auth0 API calls
• Graceful degradation on Auth0 service issues
• Circuit breaker pattern for external API calls
• Memory-efficient session storage

Integration Points

1. RoadRunner Integration

• Endure container plugin registration
• HTTP middleware interface implementation
• Configuration system integration
• Logging system integration

2. PHP Application Integration

• PSR7 request attributes for user data (PHP never handles auth routes)
• Authentication-agnostic PHP code - receives pre-authenticated requests only
• Standard user data access patterns via request attributes
• No authentication logic in PHP - all auth handled by RoadRunner middleware

Error Handling Strategy

1. Authentication Errors

• Invalid credentials → Redirect to login
• Expired sessions → Redirect to login with message
• Auth0 service errors → Graceful fallback or error page
• Configuration errors → Plugin startup failure with clear messages

2. Operational Errors

• Network issues → Retry logic with exponential backoff
• Token validation failures → Force re-authentication
• Session corruption → Clear session and redirect to login

Testing Strategy

1. Unit Tests

• Configuration parsing and validation
• URL pattern matching logic
• Token validation logic
• Session management functions

2. Integration Tests

• Full OAuth flow simulation
• RoadRunner middleware integration
• PHP application attribute injection
• Error scenario handling

3. Security Tests

• CSRF protection validation
• XSS prevention testing
• Session hijacking prevention
• Token manipulation attempts

Deployment Considerations

1. Environment Setup

• Auth0 application configuration guide
• RoadRunner configuration examples
• Environment variable templates
• Docker deployment examples

2. Production Readiness

• Health check endpoints
• Monitoring and logging integration
• Performance metrics collection
• Scaling considerations

Success Metrics

1. Functionality Metrics

• ✅ Successful authentication flow completion rate > 99%
• ✅ Session management accuracy (no false logouts) > 99.9%
• ✅ URL pattern matching accuracy > 100%
• ✅ User attribute injection success rate > 99.9%

2. Performance Metrics

• ⚡ Authentication check latency < 10ms
• ⚡ Login flow completion time < 2 seconds
• ⚡ Memory usage per session < 1KB
• ⚡ CPU overhead < 5% under normal load

3. Security Metrics

• 🔒 Zero successful session hijacking attempts
• 🔒 Zero successful CSRF attacks
• 🔒 Zero token leakage incidents
• 🔒 100% secure cookie implementation

Future Enhancements

Phase 2 Features

• Multi-tenant support for multiple Auth0 domains
• Role-based access control with fine-grained permissions
• API key authentication for service-to-service calls
• Social login provider extensions beyond Auth0

Phase 3 Features

• Advanced session storage (Redis, database)
• Distributed session management for multi-instance deployments
• Advanced audit logging and compliance features
• Machine-to-machine authentication support