Merge pull request #152 from devondragon/issue-137-Add-Keycloak-Authentication-Support

devondragon · web-flow · commit 8b51908fadf4 · 2025-03-23T15:34:35.000-06:00
Issue 137 add keycloak authentication support
diff --git a/README.md b/README.md
@@ -39,11 +39,19 @@ Check out the [Spring User Framework Demo Application](https://github.com/devond
 ## Features
 
 - **User Registration and Authentication**
-  - Local username/password authentication
-  - OAuth2/SSO with Google, Facebook, and more
-  - Email verification workflow
-  - Password reset functionality
-  - Account management (update profile, change password)
+The framework provides support for the following features:
+- Registration, with optional email verification.
+- Login and logout functionality.
+- Forgot password flow.
+- Database-backed user store using Spring JPA.
+- SSO support for Google
+- SSO support for Facebook
+- SSO support for Keycloak
+- Configuration options to control anonymous access, whitelist URIs, and protect specific URIs requiring a logged-in user session.
+- CSRF protection enabled by default, with example jQuery AJAX calls passing the CSRF token from the Thymeleaf page context.
+- Audit event framework for recording and logging security events, customizable to store audit events in a database or publish them via a REST API.
+- Role and Privilege setup service to define roles, associated privileges, and role inheritance hierarchy using `application.yml`.
+- Configurable Account Lockout after too many failed login attempts
 
 - **Advanced Security**
   - Role and privilege-based authorization
@@ -212,12 +220,15 @@ Users can:
 
 ## Email Verification
 
+
+
 The framework includes a complete email verification system:
 - Token generation and verification
 - Customizable email templates
 - Token expiration and renewal
 - Automatic account activation
 
+
 ## Authentication
 
 ### Local Authentication
@@ -244,10 +255,21 @@ spring:
       client:
         registration:
           google:
-            client-id: your-client-id
-            client-secret: your-client-secret
-            scope: profile,email
+            client-id: YOUR_GOOGLE_CLIENT_ID
+            client-secret: YOUR_GOOGLE_CLIENT_SECRET
+            redirect-uri: "{baseUrl}/login/oauth2/code/google"
+          facebook:
+            client-id: YOUR_FACEBOOK_CLIENT_ID
+            client-secret: YOUR_FACEBOOK_CLIENT_SECRET
+            redirect-uri: "{baseUrl}/login/oauth2/code/facebook"
+          keycloak:
+            client-id: YOUR_KEYCLOAK_CLIENT_ID
+            client-secret: YOUR_KEYCLOAK_CLIENT_SECRET
+            redirect-uri: "{baseUrl}/login/oauth2/code/keycloak"
+
 ```
+For public OAuth you will need a public hostname and HTTPS enabled.  You can use ngrok or Cloudflare tunnels to create a public hostname and tunnel to your local machine during development.  You can then use the ngrok hostname in your Google, Facebook and Keycloak developer console configuration.
+
 
 ## Extensibility
 
@@ -273,6 +295,11 @@ public class CustomUserProfileService implements UserProfileService<CustomUserPr
 ```
 Read more in the [Profile Guide](PROFILE.md).
 
+
+### SSO OAuth2 with Google and Facebook
+The framework supports SSO OAuth2 with Google, Facebook and Keycloak.  To enable this you need to configure the client id and secret for each provider.  This is done in the application.yml (or application.properties) file using the [Spring Security OAuth2 properties](https://docs.spring.io/spring-security/reference/servlet/oauth2/login/core.html). You can see the example configuration in the Demo Project's `application.yml` file.
+
+
 ## Examples
 
 For complete working examples, check out the [Spring User Framework Demo Application](https://github.com/devondragon/SpringUserFrameworkDemoApp).
diff --git a/db-scripts/mariadb-schema.sql b/db-scripts/mariadb-schema.sql
@@ -64,7 +64,7 @@ CREATE TABLE `user_account` (
   `last_name` VARCHAR(255) DEFAULT NULL,
   `locked` BIT(1) NOT NULL,
   `password` VARCHAR(60) DEFAULT NULL,
-  `provider` ENUM('LOCAL','FACEBOOK','GOOGLE','APPLE') DEFAULT NULL,
+  `provider` ENUM('LOCAL','FACEBOOK','GOOGLE','APPLE','KEYCLOAK') DEFAULT NULL,
   `registration_date` DATETIME(6) DEFAULT NULL,
   `failed_login_attempts` INT(11) NOT NULL,
   `locked_date` DATETIME(6) DEFAULT NULL,
diff --git a/gradle.properties b/gradle.properties
@@ -1 +1 @@
-version=3.1.2-SNAPSHOT
+version=3.2.0-SNAPSHOT
diff --git a/mise.toml b/mise.toml
@@ -1,2 +1,3 @@
 [tools]
+java = "17"
 python = "3.13"
diff --git a/src/main/java/com/digitalsanctuary/spring/user/controller/UserPageController.java b/src/main/java/com/digitalsanctuary/spring/user/controller/UserPageController.java
@@ -27,12 +27,15 @@ public class UserPageController {
 	@Value("${user.registration.googleEnabled}")
 	private boolean googleEnabled;
 
+	@Value("${user.registration.keycloakEnabled}")
+	private boolean keycloakEnabled;
+
 	/**
 	 * Login Page.
 	 *
 	 * @param userDetails the user details
-	 * @param session     the session
-	 * @param model       the model
+	 * @param session the session
+	 * @param model the model
 	 *
 	 * @return the string
 	 */
@@ -45,15 +48,16 @@ public String login(@AuthenticationPrincipal DSUserDetails userDetails, HttpSess
 		}
 		model.addAttribute("googleEnabled", googleEnabled);
 		model.addAttribute("facebookEnabled", facebookEnabled);
+		model.addAttribute("keycloakEnabled", keycloakEnabled);
 		return "user/login";
 	}
 
 	/**
 	 * Register Page.
 	 *
 	 * @param userDetails the user details
-	 * @param session     the session
-	 * @param model       the model
+	 * @param session the session
+	 * @param model the model
 	 * @return the string
 	 */
 	@GetMapping("${user.security.registrationURI:/user/register.html}")
@@ -65,6 +69,7 @@ public String register(@AuthenticationPrincipal DSUserDetails userDetails, HttpS
 		}
 		model.addAttribute("googleEnabled", googleEnabled);
 		model.addAttribute("facebookEnabled", facebookEnabled);
+		model.addAttribute("keycloakEnabled", keycloakEnabled);
 		return "user/register";
 	}
 
@@ -82,8 +87,8 @@ public String registrationPending() {
 	 * Registration complete.
 	 *
 	 * @param userDetails the user details
-	 * @param session     the session
-	 * @param model       the model
+	 * @param session the session
+	 * @param model the model
 	 *
 	 * @return the string
 	 */
@@ -134,10 +139,11 @@ public String forgotPasswordChange() {
 		return "user/forgot-password-change";
 	}
 
+
 	/**
 	 * @param userDetails the user details
-	 * @param request     the request
-	 * @param model       the model
+	 * @param request the request
+	 * @param model the model
 	 * @return String
 	 */
 	@GetMapping("${user.security.updateUserURI:/user/update-user.html}")
diff --git a/src/main/java/com/digitalsanctuary/spring/user/persistence/model/User.java b/src/main/java/com/digitalsanctuary/spring/user/persistence/model/User.java
@@ -40,7 +40,12 @@ public enum Provider {
 		/**
 		 * Login using Apple as the authentication provider.
 		 */
-		APPLE
+		APPLE,
+
+		/**
+		 * Login using Keycloak as the authentication provider.
+		 */
+		KEYCLOAK
 	}
 
 	/** The id. */
diff --git a/src/main/java/com/digitalsanctuary/spring/user/security/WebSecurityConfig.java b/src/main/java/com/digitalsanctuary/spring/user/security/WebSecurityConfig.java
@@ -6,6 +6,8 @@
 import java.util.Collections;
 import java.util.List;
 import java.util.stream.Collectors;
+
+import com.digitalsanctuary.spring.user.service.DSOidcUserService;
 import org.springframework.beans.factory.annotation.Value;
 import org.springframework.context.ApplicationEventPublisher;
 import org.springframework.context.annotation.Bean;
@@ -113,6 +115,7 @@ public class WebSecurityConfig {
 	private final LogoutSuccessService logoutSuccessService;
 	private final RolesAndPrivilegesConfig rolesAndPrivilegesConfig;
 	private final DSOAuth2UserService dsOAuth2UserService;
+	private final DSOidcUserService dsOidcUserService;
 
 	/**
 	 *
@@ -183,7 +186,10 @@ private void setupOAuth2(HttpSecurity http) throws Exception {
 					request.getSession().setAttribute("error.message", exception.getMessage());
 					response.sendRedirect(loginPageURI);
 					// handler.onAuthenticationFailure(request, response, exception);
-				}).userInfoEndpoint(userInfo -> userInfo.userService(dsOAuth2UserService)));
+				}).userInfoEndpoint(userInfo -> {
+					userInfo.userService(dsOAuth2UserService);
+					userInfo.oidcUserService(dsOidcUserService);
+				}));
 	}
 
 	// Commenting this out to try adding /error to the unprotected URIs list instead
diff --git a/src/main/java/com/digitalsanctuary/spring/user/service/DSOidcUserService.java b/src/main/java/com/digitalsanctuary/spring/user/service/DSOidcUserService.java
@@ -0,0 +1,171 @@
+package com.digitalsanctuary.spring.user.service;
+
+import com.digitalsanctuary.spring.user.persistence.model.User;
+import com.digitalsanctuary.spring.user.persistence.repository.UserRepository;
+import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.security.oauth2.client.oidc.userinfo.OidcUserRequest;
+import org.springframework.security.oauth2.client.oidc.userinfo.OidcUserService;
+import org.springframework.security.oauth2.client.userinfo.OAuth2UserRequest;
+import org.springframework.security.oauth2.client.userinfo.OAuth2UserService;
+import org.springframework.security.oauth2.core.OAuth2AuthenticationException;
+import org.springframework.security.oauth2.core.OAuth2Error;
+import org.springframework.security.oauth2.core.oidc.user.OidcUser;
+import org.springframework.security.oauth2.core.user.OAuth2User;
+import org.springframework.stereotype.Service;
+
+/**
+ *
+ * This class is an implementation of the OAuth2UserService interface that is used to handle Oidc logins for a Spring Security application. It
+ * provides methods to handle successful Oidc logins, register new users with Oidc accounts, update existing users with new Oidc information,
+ * and retrieve user information from an OidcUser object. This service is used in conjunction with Spring Security's OAuth2LoginConfigurer to enable
+ * Oidc login functionality for a web application. The OAuth2LoginConfigurer configures Spring Security to authenticate users with an Oidc
+ * provider, and uses this service to handle the authentication process and retrieve user information from the provider. This class is annotated with
+ * the @Service annotation to indicate that it is a Spring service that should be automatically detected and instantiated by the Spring container.
+ *
+ * @see org.springframework.security.oauth2.client.registration.ClientRegistration
+ * @see OAuth2UserService
+ * @see OAuth2UserRequest
+ * @see OAuth2User
+ * @see org.springframework.security.oauth2.core.user.DefaultOAuth2User
+ * @see org.springframework.security.oauth2.core.user.OAuth2UserAuthority
+ * @see org.springframework.security.core.userdetails.UserDetails
+ * @see org.springframework.security.core.userdetails.User
+ * @see User
+ * @see UserRepository
+ */
+@Slf4j
+@Service
+@RequiredArgsConstructor
+public class DSOidcUserService implements OAuth2UserService<OidcUserRequest, OidcUser> {
+
+    /** The user repository. */
+    private final UserRepository userRepository;
+
+    OidcUserService defaultOidcUserService = new OidcUserService();
+
+    /**
+     *
+     * Handles a successful Oidc login. If the user is already registered, updates their account with any new information from the Oidc provider.
+     * If the user is not already registered, creates a new user account with the information from the Oidc provider and saves it to the database.
+     *
+     * @param registrationId The registration ID for the Oidc provider.
+     * @param oidcUser The OidcUser object containing information about the authenticated user.
+     * @return A User object representing the authenticated user.
+     */
+    public User handleOidcLoginSuccess(String registrationId, OidcUser oidcUser) {
+        User user = null;
+        if (registrationId.equalsIgnoreCase("keycloak")) {
+            user = getUserFromKeycloakOidc2User(oidcUser);
+        } else {
+            log.error("Sorry! Login with " + registrationId + " is not supported yet.");
+            throw new OAuth2AuthenticationException(new OAuth2Error("Login Exception"),
+                    "Sorry! Login with " + registrationId + " is not supported yet.");
+        }
+        if (user == null) {
+            log.error("handleOidcLoginSuccess: user is null");
+            throw new OAuth2AuthenticationException(new OAuth2Error("Login Exception"),
+                    "Sorry! An error occurred while processing your login request.");
+        }
+        log.debug("handleOidcLoginSuccess: looking up user with email: {}", user.getEmail());
+        User existingUser = userRepository.findByEmail(user.getEmail());
+        log.debug("handleOidcLoginSuccess: existingUser: {}", existingUser);
+        if (existingUser != null && registrationId != null) {
+            log.debug("handleOidcLoginSuccess: existingUser.getProvider(): {}", existingUser.getProvider());
+            // If the user is already registered with a different auth provider (OAuth2 or Local), throw an exception.
+            if (!existingUser.getProvider().toString().equals(registrationId.toUpperCase())) {
+                log.debug("handleOidcLoginSuccess: ERROR! existingUser.getProvider(): {}", existingUser.getProvider());
+                throw new OAuth2AuthenticationException(new OAuth2Error("User Registered With Alternate Provider"),
+                        "Looks like you're signed up with your " + existingUser.getProvider() + " account. Please use your "
+                                + existingUser.getProvider() + " account to log in.");
+            }
+            existingUser = updateExistingUser(existingUser, user);
+            return userRepository.save(existingUser);
+        } else {
+            log.debug("handleOidcLoginSuccess: registering new user with email: {}", user.getEmail());
+            user = registerNewOidcUser(registrationId, user);
+            return user;
+        }
+    }
+
+    /**
+     *
+     * Registers a new user with an Oidc account. Creates a new user account with the information from the Oidc provider and saves it to the
+     * database.
+     *
+     * @param registrationId The registration ID for the Oidc provider.
+     * @param user The User object representing the authenticated user.
+     * @return A User object representing the newly registered user.
+     */
+    private User registerNewOidcUser(String registrationId, User user) {
+        User.Provider provider = User.Provider.valueOf(registrationId.toUpperCase());
+        user.setProvider(provider);
+        // user.setRoles(Collections.singletonList(roleRepository.findByName(RoleName.ROLE_USER)));
+        // We will trust OAuth2 providers to provide us with a verified email address.
+        user.setEnabled(true);
+        return userRepository.save(user);
+    }
+
+    /**
+     *
+     * Updates an existing user's account with any new information from the Oidc provider.
+     *
+     * @param existingUser The existing User object representing the user to be updated.
+     * @param user The User object representing the authenticated user.
+     * @return The updated User object.
+     */
+    private User updateExistingUser(User existingUser, User user) {
+        existingUser.setFirstName(user.getFirstName());
+        existingUser.setLastName(user.getLastName());
+        return existingUser;
+    }
+
+    /**
+     *
+     * Retrieves user information from a Keycloak OidcUser object.
+     *
+     * @param principal The OidcUser object containing information about the authenticated user.
+     * @return A User object representing the authenticated user.
+     */
+    public User getUserFromKeycloakOidc2User(OidcUser principal) {
+        log.debug("Getting user info from Keycloak Oidc provider with principal: {}", principal);
+        if (principal == null) {
+            return null;
+        }
+        log.debug("Principal attributes: {}", principal.getAttributes());
+        User user = new User();
+/*        user.setEmail(principal.getAttribute("email"));
+        user.setFirstName(principal.getAttribute("given_name"));
+        user.setLastName(principal.getAttribute("family_name"));*/
+        user.setEmail(principal.getEmail());
+        user.setFirstName(principal.getGivenName());
+        user.setLastName(principal.getFamilyName());
+        user.setProvider(User.Provider.KEYCLOAK);
+        return user;
+    }
+
+
+    /**
+     *
+     * Loads user information from an Oidc provider and creates a UserDetails object representing the authenticated user.
+     *
+     * @param userRequest The OidcUserRequest object containing information about the user request.
+     * @return A UserDetails object representing the authenticated user.
+     * @throws OAuth2AuthenticationException If there is an error authenticating the user with the OAuth2 provider.
+     */
+    @Override
+    public OidcUser loadUser(OidcUserRequest userRequest) throws OAuth2AuthenticationException {
+        log.debug("Loading user from OAuth2 provider with userRequest: {}", userRequest);
+        OidcUser user = defaultOidcUserService.loadUser(userRequest);
+        String registrationId = userRequest.getClientRegistration().getRegistrationId();
+        log.debug("registrationId: " + registrationId);
+        User dbUser = handleOidcLoginSuccess(registrationId, user);
+        DSUserDetails dsUserDetails = DSUserDetails.builder()
+                .user(dbUser)
+                .oidcUserInfo(user.getUserInfo())
+                .oidcIdToken(user.getIdToken())
+                .grantedAuthorities(user.getAuthorities())
+                .build();
+        return dsUserDetails;
+    }
+}
diff --git a/src/main/java/com/digitalsanctuary/spring/user/service/DSUserDetails.java b/src/main/java/com/digitalsanctuary/spring/user/service/DSUserDetails.java
diff --git a/src/main/resources/META-INF/additional-spring-configuration-metadata.json b/src/main/resources/META-INF/additional-spring-configuration-metadata.json
diff --git a/src/main/resources/config/dsspringuserconfig.properties b/src/main/resources/config/dsspringuserconfig.properties

Original file line number	Diff line number	Diff line change
`@@ -1 +1 @@`
`1`		`-version=3.1.2-SNAPSHOT`
	`1`	`+version=3.2.0-SNAPSHOT`
Original file line number	Diff line number	Diff line change
`@@ -1,2 +1,3 @@`
`1`	`1`	`[tools]`
	`2`	`+java = "17"`
`2`	`3`	`python = "3.13"`