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
    • Maven
    • Gradle
  • Quick Start
  • Configuration
  • Security Features
    • Role-Based Access Control
    • Account Lockout
    • Audit Logging
  • User Management
    • Registration
    • Profile Management
  • Email Verification
  • Authentication
    • Local Authentication
    • OAuth2/SSO
      • SSO OIDC with Keycloak
  • Extensibility
    • Custom User Profiles
    • SSO OAuth2 with Google and Facebook
  • Examples
  • Contributing
  • Reference Documentation
  • License

Features

• User Registration and Authentication

  • 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
  • Configurable password policies
  • Account lockout after failed login attempts
  • Audit logging for security events
  • CSRF protection out of the box

• 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

Installation

Maven

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

Gradle

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

Quick Start

1. Add the dependency as shown above

2. Set essential configuration in your application.yml:

spring:
  datasource:
    url: jdbc:mariadb://localhost:3306/yourdb
    username: dbuser
    password: dbpassword
    driver-class-name: org.mariadb.jdbc.Driver
  jpa:
    hibernate:
      ddl-auto: update
  mail:
    host: smtp.example.com
    port: 587
    username: your-username
    password: your-password
    properties:
      mail:
        smtp:
          auth: true
          starttls:
            enable: true

user:
  mail:
    fromAddress: [email protected]
  security:
    defaultAction: deny
    bcryptStrength: 12
    failedLoginAttempts: 5
    accountLockoutDuration: 15

3. Create a UserProfile extension for your application-specific user data:

@Entity
@Table(name = "app_user_profile")
public class AppUserProfile extends BaseUserProfile {
    // Add your application-specific fields
    private String preferredLanguage;
    private boolean receiveNewsletter;

    // Getters and setters
}

4. Run your application and navigate to /user/login.html to see the login page.

Configuration

The framework uses a configuration-first approach to customize behavior. See the Configuration Guide for detailed documentation of all configuration options.

Key configuration categories:

• Security: Access control, password policies, CSRF protection
• Mail: Email server settings for verification and notification emails
• User Registration: Self-registration options, verification requirements
• Authentication: Local and OAuth2 provider configuration
• UI: Paths to customized templates and views

Security Features

Role-Based Access Control

Define roles and privileges with hierarchical inheritance:

user:
  roles:
    roles-and-privileges:
      "[ROLE_ADMIN]":
        - ADMIN_PRIVILEGE
        - USER_MANAGEMENT_PRIVILEGE
      "[ROLE_USER]":
        - LOGIN_PRIVILEGE
        - SELF_SERVICE_PRIVILEGE
    role-hierarchy:
      - ROLE_ADMIN > ROLE_USER

Account Lockout

Prevent brute force attacks with configurable lockout policies:

user:
  security:
    failedLoginAttempts: 5
    accountLockoutDuration: 30  # minutes

Audit Logging

Track security-relevant events with built-in audit logging:

user:
  audit:
    logEvents: true
    logFilePath: /path/to/audit/log
    flushOnWrite: false
    flushRate: 10000

User Management

Registration

Default registration flow includes:

• Form submission validation
• Email uniqueness check
• Email verification (optional)
• Welcome email
• Configurable initial roles

Profile Management

Users can:

• Update their profile information
• Change their password
• Delete their account (configurable to either disable or fully delete)

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

Username/password authentication with:

• Secure password hashing (bcrypt)
• Account lockout protection
• Remember-me functionality

OAuth2/SSO

Support for social login providers:

• Google
• Facebook
• Apple
• Keycloak
• Custom providers

Configuration example:

spring:
  security:
    oauth2:
      client:
        registration:
          google:
            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.

SSO OIDC with Keycloak

To enable SSO:

1. Create OIDC client in Keycloak admin console.
2. Update your application-docker-keycloak.yml:

   spring:
     security:
       oauth2:
         client:
            registration:
              keycloak:
                client-id: ${DS_SPRING_USER_KEYCLOAK_CLIENT_ID} # Keycloak client ID for OAuth2
                client-secret: ${DS_SPRING_USER_KEYCLOAK_CLIENT_SECRET} # Keycloak client secret for OAuth2
                authorization-grant-type: authorization_code # Authorization grant type for OAuth2
                scope:
                  - email # Request email scope for OAuth2
                  - profile # Request profile scope for OAuth2
                  - openid # Request oidc scope for OAuth2
                client-name: Keycloak # Name of the OAuth2 client
                provider: keycloak
            provider:
              keycloak: # https://www.keycloak.org/securing-apps/oidc-layers
                issuer-uri: ${DS_SPRING_USER_KEYCLOAK_PROVIDER_ISSUER_URI}
                authorization-uri: ${DS_SPRING_USER_KEYCLOAK_PROVIDER_AUTHORIZATION_URI}
                token-uri: ${DS_SPRING_USER_KEYCLOAK_PROVIDER_TOKEN_URI}
                user-info-uri: ${DS_SPRING_USER_KEYCLOAK_PROVIDER_USER_INFO_URI}
                user-name-attribute: preferred_username # https://www.keycloak.org/docs-api/latest/rest-api/index.html#UserRepresentation
                jwk-set-uri: ${DS_SPRING_USER_KEYCLOAK_PROVIDER_JWK_SET_URI}

Extensibility

The framework is designed to be extended without modifying the core code.

Custom User Profiles

Extend the BaseUserProfile to add your application-specific user data:

@Service
public class CustomUserProfileService implements UserProfileService<CustomUserProfile> {
    @Override
    public CustomUserProfile getOrCreateProfile(User user) {
        // Implementation
    }

    @Override
    public CustomUserProfile updateProfile(CustomUserProfile profile) {
        // Implementation
    }
}

Read more in the Profile Guide.

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. 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.

Contributing

We welcome contributions of all kinds! If you'd like to help improve SpringUserFramework, please read our Contributing Guide for details on how to get started, report issues, and submit pull requests. Let's build something great together!

Reference Documentation

• API Documentation
• Configuration Guide
• Security Guide
• Customization Guide
• Demo Application

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

---

Created by Devon Hillard at Digital Sanctuary