OIDC Authentication & Authorization

[NickPadilla]

🔐 Add Comprehensive OIDC Authentication Support

Overview

This PR introduces a complete OpenID Connect (OIDC) authentication system to the Structures framework, enabling secure JWT-based authentication with multiple identity providers including Keycloak, Okta, Microsoft Entra ID, Google, and GitHub.

✨ Key Features

🔧 Backend Implementation

• New structures-auth library with comprehensive OIDC support
• JWT token validation using JJWT 0.12.x with JWKS caching
• Multi-provider support for Keycloak, Okta, Microsoft, Google, and GitHub
• Tenant-aware authentication with configurable tenant ID extraction
• Role-based access control with configurable claims mapping
• Spring Boot auto-configuration for seamless integration

🎨 Frontend Integration

• Modern Vue.js login interface with conditional OIDC provider display
• Automatic token handling and silent refresh capabilities
• Provider-specific branding with custom icons and display names
• Responsive design supporting both desktop and mobile experiences
• State management with localStorage persistence and base64 encoding

🧪 Testing Infrastructure

• Comprehensive test suite with 100+ test cases
• Keycloak test container setup for integration testing
• Docker Compose configurations for local development and testing
• Test coverage for authentication flows, error handling, and edge cases

��️ Architecture

Core Components

• OidcSecurityService: Main authentication service implementing SecurityService interface
• JwksService: Efficient JWKS caching and key management
• OidcAuthVerifier: JWT token validation and participant creation
• OidcSecurityServiceProperties: Configuration management

Frontend Components

• Login.vue: Main authentication interface with conditional provider display
• OidcConfiguration.ts: Provider configuration and environment variable management
• IUserState.ts: User state management interface

📚 Documentation

• OIDC Implementation Guide: Comprehensive technical documentation
• Provider-specific setup guides: Keycloak, Okta, Microsoft Entra ID
• Troubleshooting guides: Common issues and solutions
• Getting Started: Quick setup and configuration examples

🚀 Getting Started

1. Enable OIDC Authentication

oidc-security-service:
  enabled: true
  oidc-providers:
    - provider: "keycloak"
      display-name: "Keycloak"
      enabled: true
      client-id: "your-client-id"
      authority: "http://localhost:8888/auth/realms/your-realm"
      # ... additional configuration

2. Frontend Configuration

# Enable specific providers
VITE_OIDC_OKTA_ENABLED=true
VITE_OIDC_KEYCLOAK_ENABLED=true
VITE_OIDC_GOOGLE_ENABLED=false

3. Run with Keycloak

docker-compose -f docker-compose/compose.keycloak.yml up

🔒 Security Features

• JWT signature validation using provider public keys
• Issuer and audience validation against configured allowlists
• Token expiration checking with automatic rejection
• Role-based access control with configurable claims mapping
• Multi-tenant support with tenant isolation

🧪 Testing

• Unit tests for all authentication components
• Integration tests with Keycloak test container
• Access control tests for different provider configurations
• Error handling tests for various failure scenarios
• Container health checks for reliable test execution

📊 Impact

• 117 files changed with 10,926 additions and 1,029 deletions
• New module: structures-auth library
• Enhanced modules: structures-core, structures-frontend-next, structures-server
• Improved testing: Container-based testing infrastructure
• Better documentation: Comprehensive guides and troubleshooting

�� Breaking Changes

None. This is a purely additive feature that maintains backward compatibility with existing authentication mechanisms.

�� Dependencies

• JJWT 0.12.x for JWT handling
• Caffeine for JWKS caching
• Spring Boot 3.x for auto-configuration
• Vue.js 3.x for frontend components

�� Contributors

This feature was developed with a focus on:

• Security best practices and OIDC compliance
• Developer experience with comprehensive documentation
• Testing reliability using container-based infrastructure
• Flexibility supporting multiple identity providers
• Performance with efficient caching and validation

📝 Next Steps

• Performance testing with high-volume authentication
• Additional provider integrations (Auth0, AWS Cognito)
• Advanced role mapping and permission systems
• Audit logging and compliance features
• Multi-factor authentication support

---

Ready for review and testing! 🎉