Add Keycloak Authentication Support

[devondragon]

Summary

Integrate Keycloak as the Identity and Access Management (IAM) solution for SpringUserFramework to provide secure, standards-based authentication and authorization. This integration will enable Single Sign-On (SSO), role-based access control, and centralized user management through Keycloak.

Background

SpringUserFramework currently handles user authentication internally. Moving to Keycloak will provide enterprise-grade security features, reduce maintenance overhead, and enable seamless integration with other applications through standardized protocols like OAuth 2.0 and OpenID Connect.

Requirements

Authentication Flow

• Implement OAuth 2.0 Authorization Code flow with PKCE
• Configure Spring Security to use Keycloak as the authentication provider
• Redirect unauthenticated users to Keycloak login page
• Handle post-authentication token management and refresh
• Support logout with proper session termination both locally and in Keycloak

Configuration

• Add Keycloak client configuration in application.properties/yaml
• Create separate configurations for development, staging, and production environments
• Document all required Keycloak realm settings
• Implement configuration validation on application startup

User Management

• Map Keycloak user attributes to SpringUserFramework user model
• Sync user roles and groups from Keycloak
• Handle user session management
• Implement user profile data retrieval from Keycloak

Security

• Secure all REST endpoints using Spring Security
• Implement role-based access control using Keycloak roles
• Configure CORS appropriately for frontend applications
• Handle token validation and signature verification
• Implement proper error handling for authentication failures

Performance

• Implement token caching to reduce Keycloak server load
• Optimize token validation process
• Handle high concurrent authentication requests efficiently

Acceptance Criteria

Configuration

• [ ] Keycloak client successfully registered and configured
• [ ] Application connects to Keycloak using configuration properties
• [ ] Different environment configurations working as expected
• [ ] Configuration validation prevents startup with invalid settings

Authentication

• [ ] Users can log in using Keycloak login page
• [ ] PKCE flow implemented and working correctly
• [ ] Access tokens are properly validated
• [ ] Refresh tokens are handled automatically
• [ ] Logout terminates both local and Keycloak sessions

Authorization

• [ ] Role-based access control working with Keycloak roles
• [ ] Protected endpoints only accessible with valid tokens
• [ ] User permissions correctly synchronized from Keycloak
• [ ] Group memberships properly mapped to application roles

User Management

• [ ] User profile data successfully retrieved from Keycloak
• [ ] User attributes correctly mapped to application model
• [ ] Session management handling multiple concurrent sessions
• [ ] User data updated when changed in Keycloak

Testing

(This would be done in the https://github.com/devondragon/SpringUserFrameworkDemoApp project)

• [ ] Unit tests covering authentication flows
• [ ] Integration tests with Keycloak test container
• [ ] Performance tests showing acceptable authentication latency
• [ ] Security tests verifying proper token validation
• [ ] Error handling tests for various failure scenarios

Documentation

• [ ] Update Readme and Configuration guide
• [ ] Configuration reference for all Keycloak settings
• [ ] Developer guide for authentication flow
• [ ] Troubleshooting guide for common issues
• [ ] API documentation updated to reflect authentication changes

[anirbandas18]

I would like to implement this feature

[create-issue-branch[bot]]

Branch issue-137-Add-Keycloak-Authentication-Support created!

[devondragon]

@anirbandas18 - wonderful! Thank you!

[anirbandas18]

Tested with local Keycloak and it works. Ready for review.