Spring User Framework Demo Application

A comprehensive demonstration application for the Spring User Framework, showcasing how to implement user management features in a Spring Boot web application.

Table of Contents

• Spring User Framework Demo Application
  • Table of Contents
  • Overview
  • Features Demonstrated
  • Quick Start
    • Prerequisites
    • Steps
  • Project Structure
    • Configuration Guide
      • Database
      • Mail Sending (SMTP)
      • SSO OIDC with Keycloak
  • Running the Application
    • Running Locally
      • Using Gradle
      • Using Maven
      • With specific profile
    • Running with Docker
    • Development Tools
      • Spring Boot DevTools
      • Resources for Live Reload:
    • Notes

Overview

This demo application serves as a reference implementation of the Spring User Framework, showing how to integrate user management features into a real-world Spring Boot application. It includes a complete user interface built with Bootstrap, Thymeleaf templates, and JavaScript.

The application implements an event management system where users can browse, register for, and manage events. This demonstrates how to build application-specific functionality on top of the user management framework.

Features Demonstrated

• User Management

  • Registration with email verification
  • Login/logout functionality
  • Password reset workflow
  • User profile management
  • Account deletion/disabling

• Authentication & Security

  • Username/password authentication
  • OAuth2 login with Google and Facebook
  • Role-based access control
  • CSRF protection
  • Security audit logging

• Application-Specific Features

  • Custom user profile with additional fields
  • Event listing and management
  • User-to-event registration
  • Role-based permissions for events

• Technical Features

  • Spring Boot auto-configuration
  • Thymeleaf templating with fragments
  • REST API with JSON responses
  • Responsive Bootstrap UI
  • Docker integration

Quick Start

Prerequisites

• JDK 17 or higher
• Maven or Gradle
• MariaDB or MySQL (or Docker for containerized database)

Steps

1. Clone the repository

   git clone https://github.com/devondragon/SpringUserFrameworkDemoApp.git
   cd SpringUserFrameworkDemoApp

2. Set up the database

   Using Docker:

   docker run -d --name springuser-db \
     -e MYSQL_ROOT_PASSWORD=root \
     -e MYSQL_DATABASE=springuser \
     -e MYSQL_USER=springuser \
     -e MYSQL_PASSWORD=springuser \
     -p 3306:3306 \
     mariadb:latest

3. Configure application

   Copy the example configuration:

   cp src/main/resources/application-local.yml-example src/main/resources/application-local.yml

   Edit the file to update database credentials and other settings as needed.

4. Run the application

   • For using Keycloak copy the provided example configuration:

     cp src/main/resources/application-docker-keycloak.yml-example src/main/resources/application-docker-keycloak.yml

   Using Gradle:

   ./gradlew bootRun

   Using Maven:

   mvn spring-boot:run

   • Using Docker Compose with Keycloak stack:

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

5. Access the Application:

   • Navigate to http://localhost:8080 in your browser.

---

Project Structure

└── src/
    ├── main/
    │   ├── java/
    │   │   └── com/digitalsanctuary/spring/demo/
    │   │       ├── controller/            # Page controllers
    │   │       ├── event/                 # Event-related functionality
    │   │       ├── user/
    │   │       │   └── profile/           # User profile extensions
    │   │       └── util/                  # Utility classes
    │   └── resources/
    │       ├── static/                    # Static resources (CSS, JS)
    │       ├── templates/                 # Thymeleaf templates
    │       │   ├── fragments/             # Reusable template fragments
    │       │   ├── mail/                  # Email templates
    │       │   └── user/                  # User management templates
    │       └── application.yml            # Application configuration
    └── test/                              # Test classes

Configuration Guide

Database

The demo uses MariaDB as the default database. You can quickly spin up a MariaDB instance using Docker:

docker run -p 127.0.0.1:3306:3306 --name springuserframework \
  -e MARIADB_ROOT_PASSWORD=springuserroot \
  -e MARIADB_DATABASE=springuser \
  -e MARIADB_USER=springuser \
  -e MARIADB_PASSWORD=springuser \
  -d mariadb:latest

If you're running the application in a production-like environment, ensure you set the appropriate database properties in application.yml or your active profile.

---

Mail Sending (SMTP)

The application requires an SMTP server for sending emails (e.g., account verification and password reset). Update the SMTP settings in your configuration file:

spring:
  mail:
    host: smtp.example.com
    port: 587
    username: your-username
    password: your-password
    properties:
      mail.smtp.auth: true
      mail.smtp.starttls.enable: true

user:
  mail:
    fromAddress: noreply@yourdomain.com

For local testing, the Docker Compose configuration includes a mail server that captures all outgoing emails.


---

#### **SSO OAuth2 with Google and Facebook**
To enable SSO:
1. Create OAuth credentials in Google and Facebook developer consoles.
2. Update your `application.yml`:
   ```yaml
   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"

3. Use a tool like ngrok for local testing of OAuth callbacks:

   ngrok http 8080

Then update your OAuth2 providers' callback URLs to use the ngrok domain.

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}

3. Refer to keycloak.env for default values for the above environment variables
4. You can directly start with Keycloak using the default realm provided in this project under keycloak/realm/realm-export.json that comes pre configured with a OIDC client and secret for this application Keycloak

---

Running the Application

Running Locally

Using Gradle

./gradlew bootRun

Using Maven

mvn spring-boot:run

With specific profile

./gradlew bootRun --args='--spring.profiles.active=dev'

Running with Docker

The project includes a complete Docker setup with the application, MariaDB database, and a mail server.

docker-compose up --build

To launch the Keycloak stack:

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

Note: Test emails sent from the local Postfix server may not be accepted by all email providers. Use a real SMTP server for production use.

---

Development Tools

Spring Boot DevTools

This project supports Spring Boot DevTools for live reload and auto-restart. If you are working with HTTPS locally, follow these steps to enable live reload:

1. Set the following property in application.yml:

   spring.devtools.livereload.https=true

   Or when using Keycloak stack set the following property in application-docker-keycloak.yml:

   spring.devtools.livereload.https=true

2. Use a reverse proxy like mitmproxy for HTTPS traffic interception:

   mitmproxy --mode reverse:http://localhost:35729 -p 35739

Resources for Live Reload:

• Spring Boot Live Reload
• HTTPS Live Reload Setup

---

Notes

• This demo is based on the principles outlined in the Baeldung Spring Security Course.
• Feel free to customize and extend the provided functionality to suit your needs.
• Disclaimer: No warranty or guarantee of functionality, performance, or security is provided. Use at your own risk.