Spring User Framework

A comprehensive Spring Boot User Management Framework that simplifies the implementation of robust user authentication and management features. Built on top of Spring Security, this library provides ready-to-use solutions for user registration, login, account management, and more.

Check out the Spring User Framework Demo Application for a complete example of how to use this library.

Table of Contents

• Spring User Framework
  • Table of Contents
  • Features
  • Installation
    • Spring Boot 4.0 (Latest)
      • Spring Boot 4.0 Key Changes
    • Spring Boot 3.5 (Stable)
  • Migration Guide
  • Quick Start
    • Prerequisites
    • Step 1: Add Dependencies
    • Step 2: Database Configuration
    • Step 3: JPA Configuration
    • Step 4: Email Configuration (Optional but Recommended)
    • Step 5: Essential Framework Configuration
    • Step 6: Create User Profile Extension (Optional)
    • Step 7: Start Your Application
    • Step 8: Test Core Features
    • Step 9: Customize Pages (Optional)
    • Complete Example Configuration
    • Next Steps
  • Configuration
  • Security Features
    • Role-Based Access Control
    • Account Lockout
    • Audit Logging
    • HTMX Support
  • User Management
    • Registration
    • Profile Management
    • Admin Password Reset
  • Email Verification
  • Authentication
    • Local Authentication
    • WebAuthn / Passkeys
    • OAuth2/SSO
      • SSO OIDC with Keycloak
  • Extensibility
    • Custom User Profiles
    • Handling User Account Deletion and Profile Cleanup
      • Enabling Actual Deletion
    • SSO OAuth2 with Google and Facebook
  • GDPR Compliance
    • Enabling GDPR Features
    • Data Export (Right of Access)
    • Account Deletion (Right to be Forgotten)
    • Consent Management
    • Extending GDPR Exports
    • GDPR Events
  • Examples
  • Contributing
  • Reference Documentation
  • License

Features

• User Registration and Authentication

  • Registration, with optional email verification.
  • Login and logout functionality.
  • Forgot password flow.
  • Admin-initiated password reset with optional session invalidation.
  • Database-backed user store using Spring JPA.
  • SSO support for Google
  • SSO support for Facebook
  • SSO support for Keycloak
  • WebAuthn/Passkey support for passwordless login (biometrics, security keys, device authentication)
  • 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
  • HTMX-aware session expiry handling — returns 401 JSON instead of 302 redirect for HTMX requests, preventing broken UI fragments

• Advanced Security

  • Role and privilege-based authorization
  • Configurable password policies
  • Account lockout after failed login attempts
  • Audit logging for security events
  • CSRF protection out of the box
  • WebAuthn/Passkey credential management (register, rename, delete)

• Extensible Architecture

  • Easily extend user profiles with custom data
  • Override default behaviors where needed
  • Integration with Spring ecosystem
  • Customizable UI templates

• Developer-Friendly

  • Minimal boilerplate code to get started
  • Configuration-driven features
  • Comprehensive documentation
  • Demo application for reference
  • Built-in dev login controller for quick user switching during local development

• GDPR Compliance (opt-in)

  • Data export (Right of Access - Article 15)
  • Account deletion (Right to be Forgotten - Article 17)
  • Consent tracking and management (Article 7)
  • Extensible data contributor system for custom data
  • Audit trail for all GDPR operations

Installation

Choose the version that matches your Spring Boot version:

| Spring Boot Version | Framework Version | Java Version | Spring Security | | ------------------- | ----------------- | ------------ | --------------- | | 4.0.x | 4.0.x | 21+ | 7.x | | 3.5.x | 3.5.x | 17+ | 6.x |

Spring Boot 4.0 (Latest)

Spring Boot 4.0 brings significant changes including Spring Security 7 and requires Java 21.

Maven:

<dependency>
    <groupId>com.digitalsanctuary</groupId>
    <artifactId>ds-spring-user-framework</artifactId>
    <version>4.3.2</version>
</dependency>

Gradle:

implementation 'com.digitalsanctuary:ds-spring-user-framework:4.3.2'

Spring Boot 4.0 Key Changes

When upgrading to Spring Boot 4.0, be aware of these important changes:

• Java 21 Required: Spring Boot 4.0 requires Java 21 or higher
• Spring Security 7: Includes breaking changes from Spring Security 6.x
  • All URL patterns in security configuration must start with /
  • Some deprecated APIs have been removed
• Jackson 3: JSON processing uses Jackson 3.x with some API changes
• Modular Test Infrastructure: Test annotations have moved to new packages:
  • @AutoConfigureMockMvc → org.springframework.boot.webmvc.test.autoconfigure
  • @DataJpaTest → org.springframework.boot.data.jpa.test.autoconfigure
  • @WebMvcTest → org.springframework.boot.webmvc.test.autoconfigure

For testing, you may need these additional dependencies:

testImplementation 'org.springframework.boot:spring-boot-data-jpa-test'
testImplementation 'org.springframework.boot:spring-boot-webmvc-test'
testImplementation 'org.springframework.boot:spring-boot-starter-security-test'

Upgrading from 3.x? See the Migration Guide for detailed upgrade instructions.

Spring Boot 3.5 (Stable)

For projects using Spring Boot 3.5.x with Java 17+:

Maven:

<dependency>
    <groupId>com.digitalsanctuary</groupId>
    <artifactId>ds-spring-user-framework</artifactId>
    <version>3.5.1</version>
</dependency>

Gradle:

implementation 'com.digitalsanctuary:ds-spring-user-framework:3.5.1'

Migration Guide

If you're upgrading from a previous version, see the Migration Guide for:

• Step-by-step upgrade instructions
• Breaking changes and how to address them
• Spring Security 7 compatibility requirements
• Test infrastructure changes
• Guidance for developers extending the framework

Quick Start

Follow these steps to get up and running with the Spring User Framework in your application.

Prerequisites

• For Spring Boot 4.0: Java 21 or higher
• For Spring Boot 3.5: Java 17 or higher
• A database (MariaDB, PostgreSQL, MySQL, H2, etc.)
• SMTP server for email functionality (optional but recommended)

Step 1: Add Dependencies

1. Add the main framework dependency (see Installation for version selection):

   Spring Boot 4.0 (Java 21+):

   implementation 'com.digitalsanctuary:ds-spring-user-framework:4.3.2'
   

   Spring Boot 3.5 (Java 17+):

   implementation 'com.digitalsanctuary:ds-spring-user-framework:3.5.1'
   

2. Add required dependencies:

   Important: This framework requires these additional Spring Boot starters to function properly:

   Maven:

   <dependency>
       <groupId>org.springframework.boot</groupId>
       <artifactId>spring-boot-starter-thymeleaf</artifactId>
   </dependency>
   <dependency>
       <groupId>org.springframework.boot</groupId>
       <artifactId>spring-b