Quick Setup¶

Get the Spring Security Reference Project running on your local machine in just a few minutes.

📋 Prerequisites¶

Before you begin, ensure you have the following installed:

Tool	Version	Purpose
Java	17+	Runtime environment
Maven	3.6+	Build and dependency management
Git	Latest	Version control
IDE	IntelliJ IDEA, Eclipse, or VS Code	Development environment

Verify Prerequisites¶

# Check Java version
java -version

# Check Maven version  
mvn -version

# Check Git version
git --version

🚀 Installation¶

1. Clone the Repository¶

git clone <repository-url>
cd spring-security-reference

2. Build the Project¶

# Clean install all modules
mvn clean install

# Verify build success
echo "Build completed successfully!"

3. Run the Application¶

# Start the main application
mvn spring-boot:run -pl rest-api

The application will start on http://localhost:8080

✅ Verify Installation¶

Test Public Endpoint¶

curl http://localhost:8080/api/public/hello

Expected response:

Hello, world! (public endpoint - no authentication required)

Test Authentication¶

# Get JWT token
curl -X POST http://localhost:8080/api/auth/login \
  -d "username=admin&password=password"

Expected response:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "username": "admin",
  "role": "ROLE_ADMIN",
  "message": "Login successful - use this JWT token for authenticated requests",
  "usage": "Add header: Authorization: Bearer <token>"
}

Test Secured Endpoint¶

# Use the token from previous step
curl -H "Authorization: Bearer <your-jwt-token>" \
  http://localhost:8080/api/admin/secure

Expected response:

{
  "message": "Hello, Admin! (secured endpoint)",
  "user": "admin",
  "authorities": ["ROLE_ADMIN"],
  "authType": "JWT"
}

🔧 Development Setup¶

IDE Configuration¶

IntelliJ IDEA¶

Import Project: File → Open → Select pom.xml
Enable Annotation Processing: Settings → Build → Compiler → Annotation Processors
Set JDK: File → Project Structure → Project → SDK: Java 17+

Eclipse¶

Import Project: File → Import → Existing Maven Projects
Select Root Directory: Browse to project folder
Configure JDK: Right-click project → Properties → Java Build Path

VS Code¶

Open Folder: File → Open Folder → Select project directory
Install Extensions:
Extension Pack for Java
Spring Boot Extension Pack
Configure Java: Ctrl+Shift+P → "Java: Configure Runtime"

Environment Variables¶

Set up optional environment variables for customization:

# Application port (default: 8080)
export SERVER_PORT=8080

# Active profiles (default: default)
export SPRING_PROFILES_ACTIVE=default

# Log level (default: INFO)
export LOGGING_LEVEL_ROOT=INFO

🧪 Testing Setup¶

Run All Tests¶

# Execute all unit and integration tests
mvn test

Module-Specific Testing¶

# Test specific authentication modules
mvn test -pl jdbc-auth
mvn test -pl ldap-auth
mvn test -pl oauth2-auth

HTTP Testing¶

Use the provided api-testing.http file with your IDE's HTTP client:

IntelliJ IDEA: Open api-testing.http → Click play buttons
VS Code: Install REST Client extension → Open file → Send requests
Postman: Import the collection (export available)

🐳 Docker Setup (Optional)¶

For containerized development:

Build Docker Image¶

# Build application image
docker build -t spring-security-ref .

Run with Docker Compose¶

# Start all services
docker-compose up -d

# View logs
docker-compose logs -f

Services Available¶

Application: http://localhost:8080
Database: localhost:5432 (PostgreSQL)
LDAP: localhost:8389 (Embedded)

📊 Application Profiles¶

The application supports multiple profiles for different scenarios:

Profile	Description	Modules Active
`default`	All authentication methods	All modules
`jdbc-only`	Database authentication only	jdbc-auth, common-*
`ldap-only`	LDAP authentication only	ldap-auth, common-*
`oauth2-only`	OAuth2 authentication only	oauth2-auth, common-*

Activate Specific Profile¶

# JDBC authentication only
mvn spring-boot:run -pl rest-api -Dspring-boot.run.profiles=jdbc-only

# LDAP authentication only  
mvn spring-boot:run -pl rest-api -Dspring-boot.run.profiles=ldap-only

🔍 Troubleshooting¶

Common Issues¶

Port Already in Use¶

# Find process using port 8080
netstat -ano | findstr :8080    # Windows
lsof -i :8080                   # macOS/Linux

# Kill the process or use different port
mvn spring-boot:run -pl rest-api -Dspring-boot.run.arguments=--server.port=8081

Java Version Issues¶

# Set JAVA_HOME
export JAVA_HOME=/path/to/java17    # macOS/Linux
set JAVA_HOME=C:\path\to\java17     # Windows

# Verify Maven uses correct Java
mvn -version

Build Failures¶

# Clean and rebuild
mvn clean compile

# Skip tests if needed
mvn clean install -DskipTests

Getting Help¶

📖 Documentation: Browse the troubleshooting guide
🔍 Logs: Check application logs for detailed error messages
💬 Community: Ask questions in project discussions

🎉 Success!¶

You now have the Spring Security Reference Project running locally!

What's Next?¶

Project Structure → Explore the codebase organization
Authentication Methods → Learn about different auth strategies
API Testing → Try out the endpoints

💡 Pro Tips¶

Use HTTP files: The api-testing.http file contains all example requests
Check logs: Educational logging explains every security operation
Try different profiles: Each profile demonstrates specific authentication methods
Explore modules: Each authentication method is in its own independent module