Build an authenticated application where each user can access only their own todo list.
Java 21Spring Boot 4.1.1Maven 3.9+MongoDB Atlas
How to use this manual: Read Spring foundations and complete Atlas setup once. Then follow the numbered steps here in order. Every source file is included below with a copy button, its exact relative path, and an explanation. Downloading the bundle is an alternative to creating the files by hand.
1. Understand the personal application
Each registered user has an independent todo list. React runs on http://localhost:5173; Spring Boot runs on port 8082 and connects to Atlas database todo_personal. A user registers, signs in, receives a JWT, and sends it with every todo request.
Authentication answers “Who is calling?” Authorization answers “Which data may they access?” A valid token alone does not authorize access to every todo. The repository must include ownerId in each query for a known task.
2. Understand passwords, JWT, CORS, and CSRF
A JWT has a header, payload, and signature separated by dots. Base64url encoding is readable; it is not encryption. This lab signs tokens with HS256 using a backend-only random secret. Signature verification detects modifications. exp limits lifetime, iss identifies this issuer, aud identifies this API, and sub identifies the user. A stolen bearer token can be used until expiration, so keep it out of URLs and logs.
BCrypt uses a salt and work factor to store a one-way password hash. During login, matches compares the supplied password against the stored hash. Each registration produces its own salt. The API never returns the user document, and it never puts a password or hash into JWT claims.
The backend uses Spring Security’s resource-server support to verify tokens; there is no custom token filter to maintain. The app also issues its own tokens for this example. It is not a full OAuth authorization server or OpenID Connect provider. The issuer is a local identifier, and the decoder is explicitly configured rather than using discovery.
CORS is the browser’s cross-origin response policy. localhost:5173 and localhost:8082 are different origins because ports differ. A request with Authorization or JSON can cause an OPTIONS preflight. Spring Security enables the configured CORS support so preflight processing can occur before authentication. Postman does not enforce browser CORS.
CSRF concerns credentials automatically attached by the browser, such as cookies. This API accepts an explicit Authorization bearer header and has no authentication cookie, so its stateless security chain disables CSRF. The Thymeleaf app uses forms and keeps CSRF protection. If you move authentication into cookies later, revisit CSRF handling.
Choose a working folder, such as C:\training, in which you can create projects. In the downloaded bundle, open projects/todo-personal directly in your IDE as a Maven project. To build from this manual instead, create a folder called todo-personal, then create every file shown in the next step at its exact path.
PowerShell / Bash · manual creation only
mkdir todo-personal
cd todo-personal
A directory separator may be / or \ on Windows. Match Java class names and filenames exactly. Do not place Java source files in the project root or inside resources. The first line of each Java file is package com.example.todo;.
Import or reload Maven after saving pom.xml. The package root is src/main/java/com/example/todo. Tests go under src/test/java/com/example/todo. Resources go under src/main/resources. No Lombok, code-generation step, or omitted helper class is required.
Node.js 22.12+ is required by the pinned Vite 7 tooling. This manual includes the entire frontend, so do not run create-vite over these files. Create frontend/src and save the listed frontend files directly.
The parent pins Spring Boot 4.1.1 and manages compatible dependency versions. Web MVC supplies DispatcherServlet and embedded Tomcat. MongoDB supplies Spring Data repositories and the driver; validation supplies Jakarta Bean Validation. Java 21 is the example baseline. The Boot Maven plugin builds an executable JAR.
This main method starts the Spring container and the embedded web server. @SpringBootApplication combines configuration, auto-configuration, and component scanning. Keep every application class below com.example.todo so Spring discovers it.
Java
package com.example.todo;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
@SpringBootApplication
public class TodoApplication {
public static void main(String[] args) {
SpringApplication.run(TodoApplication.class, args);
}
}
Boot 4 uses spring.mongodb.uri and spring.mongodb.database. Environment placeholders keep credentials out of source. Each lab has its own database and port. Automatic index creation is enabled for the example database; personal users require a unique email index. In a deployed system, create and review indexes through a migration process.
Build output and local secret files must stay out of Git. An .env file is not automatically loaded by Spring Boot; use the documented terminal environment variables.
@RestControllerAdvice handles controller exceptions in one place. Field validation and JSON parse failures return 400; explicit status exceptions preserve their HTTP code. Database duplicate keys become 409 without exposing internal database messages. Security filter failures occur before controllers and use SecurityConfig’s handlers in the personal app.
users stores a normalized email and a one-way password hash. The unique email index enforces uniqueness even when registrations race. This object is never returned by a controller: passwordHash must stay server-side. The id, not the email, becomes the stable JWT subject.
Java
package com.example.todo;
import org.springframework.data.annotation.Id;
import org.springframework.data.mongodb.core.index.Indexed;
import org.springframework.data.mongodb.core.mapping.Document;
@Document("users")
public class AppUser {
@Id private String id;
@Indexed(unique=true) private String email;
private String passwordHash;
public AppUser() {}
public AppUser(String email,String passwordHash) { this.email=email; this.passwordHash=passwordHash; }
public String getId() { return id; }
public String getEmail() { return email; }
public String getPasswordHash() { return passwordHash; }
}
Spring derives an equality query from findByEmail. Normalizing emails before storage and lookup gives consistent matching. The unique index supplies the final duplicate-registration safeguard.
Every personal todo carries ownerId. The owner index helps list queries. There is no public owner setter or owner field in the request DTO. Ownership is assigned from the verified token and remains fixed when the title or status changes.
Java
package com.example.todo;
import org.springframework.data.annotation.Id;
import org.springframework.data.mongodb.core.index.Indexed;
import org.springframework.data.mongodb.core.mapping.Document;
@Document("personal_todos")
public class PersonalTodo {
@Id private String id;
@Indexed private String ownerId;
private String title;
private boolean completed;
public PersonalTodo() {}
public PersonalTodo(String ownerId,String title,boolean completed) {
this.ownerId=ownerId; this.title=title; this.completed=completed;
}
public String getId() { return id; }
public String getOwnerId() { return ownerId; }
public String getTitle() { return title; }
public boolean isCompleted() { return completed; }
public void setTitle(String title) { this.title=title; }
public void setCompleted(boolean completed) { this.completed=completed; }
}
The database query includes the authenticated owner, not merely a check in the React screen. findByIdAndOwnerId returns empty for missing and foreign-owned ids. Both become 404, limiting information about another user’s tasks. All read, update, and delete paths use this query.
The owner is a required argument for every operation. A malicious id cannot bypass authorization because update and delete load through the owner-filtered get. Creating a todo attaches the owner derived from JWT. This is the central authorization rule, independent of the UI.
Java
package com.example.todo;
import java.util.List;
import org.springframework.stereotype.Service;
import org.springframework.web.server.ResponseStatusException;
import static org.springframework.http.HttpStatus.NOT_FOUND;
@Service
public class PersonalTodoService {
private final PersonalTodoRepository repository;
public PersonalTodoService(PersonalTodoRepository repository) { this.repository=repository; }
public List<PersonalTodo> list(String owner) { return repository.findByOwnerIdOrderByIdAsc(owner); }
public PersonalTodo get(String id,String owner) {
return repository.findByIdAndOwnerId(id,owner)
.orElseThrow(() -> new ResponseStatusException(NOT_FOUND,"Todo not found"));
}
public PersonalTodo create(String owner,TodoRequest request) {
return repository.save(new PersonalTodo(owner,request.title().strip(),request.completed()));
}
public PersonalTodo update(String id,String owner,TodoRequest request) {
PersonalTodo todo=get(id,owner); todo.setTitle(request.title().strip());
todo.setCompleted(request.completed()); return repository.save(todo);
}
public void delete(String id,String owner) { repository.delete(get(id,owner)); }
}
Spring Security injects the verified Jwt through @AuthenticationPrincipal. jwt.getSubject() is the user’s database id from a signed claim. No owner parameter, email query string, or client-provided header is accepted as proof of ownership.
BCrypt hashes passwords; it does not encrypt them for later recovery. The secret is Base64-encoded random key material and is used only on the backend. HS256 is explicitly selected for signing and verification. The decoder checks signature, issuer, timestamps, audience, subject, and presence of expiration. The resource-server filter performs verification before controllers. CORS allows exactly the React origin. CSRF is disabled here because authentication uses a bearer header and no authentication cookie; the MVC lab keeps CSRF. Stateless means the server does not use an HTTP session for login.
Register validates and normalizes email, hashes the password, and inserts a user. It never stores the plaintext password. Login uses the same normalization and BCrypt matches; unknown-user and wrong-password errors share a generic message. A dummy hash avoids skipping BCrypt work for unknown emails. BCrypt has a 72-byte input limit, so UTF-8 byte length is checked explicitly. Login emits a signed 15-minute JWT with sub, iss, aud, iat, and exp. JWT payloads are readable, so passwords and hashes are never claims. Registration does not automatically log in.
Java
package com.example.todo;
import java.nio.charset.StandardCharsets;
import java.time.Instant;
import java.util.List;
import java.util.Locale;
import java.util.Map;
import jakarta.validation.Valid;
import jakarta.validation.constraints.*;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.http.ResponseEntity;
import org.springframework.security.crypto.password.PasswordEncoder;
import org.springframework.security.oauth2.jose.jws.MacAlgorithm;
import org.springframework.security.oauth2.jwt.*;
import org.springframework.web.bind.annotation.*;
import org.springframework.web.server.ResponseStatusException;
import static org.springframework.http.HttpStatus.*;
@RestController
@RequestMapping("/api/auth")
public class AuthController {
public record Credentials(@NotBlank @Email @Size(max=254) String email,
@NotBlank @Size(min=8,max=72) String password) {}
public record TokenResponse(String accessToken,String tokenType,long expiresIn,String email) {}
private final UserRepository users;
private final PasswordEncoder passwords;
private final JwtEncoder encoder;
private final String issuer,audience;
private final long ttl;
private final String dummyHash;
public AuthController(UserRepository users,PasswordEncoder passwords,JwtEncoder encoder,
@Value("${app.jwt.issuer}") String issuer,@Value("${app.jwt.audience}") String audience,
@Value("${app.jwt.ttl-seconds}") long ttl) {
this.users=users; this.passwords=passwords; this.encoder=encoder;
this.issuer=issuer; this.audience=audience; this.ttl=ttl;
this.dummyHash=passwords.encode("dummy-password-not-an-account");
}
private String email(Credentials c) { return c.email().strip().toLowerCase(Locale.ROOT); }
private void checkPasswordBytes(String password) {
if(password.getBytes(StandardCharsets.UTF_8).length>72)
throw new ResponseStatusException(BAD_REQUEST,"Password must be at most 72 UTF-8 bytes");
}
@PostMapping("/register") public ResponseEntity<Map<String,String>> register(@Valid @RequestBody Credentials c) {
checkPasswordBytes(c.password());
users.save(new AppUser(email(c),passwords.encode(c.password())));
return ResponseEntity.status(CREATED).body(Map.of("message","Registered. Sign in now."));
}
@PostMapping("/login") public TokenResponse login(@Valid @RequestBody Credentials c) {
checkPasswordBytes(c.password());
AppUser user=users.findByEmail(email(c)).orElse(null);
boolean matches=passwords.matches(c.password(),user==null ? dummyHash : user.getPasswordHash());
if(user==null || !matches) throw new ResponseStatusException(UNAUTHORIZED,"Invalid email or password");
Instant now=Instant.now();
JwtClaimsSet claims=JwtClaimsSet.builder().issuer(issuer).subject(user.getId())
.audience(List.of(audience)).issuedAt(now).expiresAt(now.plusSeconds(ttl)).build();
String token=encoder.encode(JwtEncoderParameters.from(
JwsHeader.with(MacAlgorithm.HS256).build(),claims)).getTokenValue();
return new TokenResponse(token,"Bearer",ttl,user.getEmail());
}
}
These tests verify the authorization boundary: a foreign id cannot be read, updated, or deleted, and create uses the authenticated owner. The manual also includes a two-user HTTP test to verify the full request path against Atlas.
JWT tests check acceptance, wrong issuer, wrong audience, expired tokens, and a mismatched key. The all-zero key exists only inside this isolated test; the running application requires a randomly generated key.
Pinned dependencies make the development setup predictable. npm install produces package-lock.json; keep that file and use npm ci for later identical installs. Vite is the development server and production bundler. This is a fixed example baseline, not a claim to use every latest package.
createRoot starts the React tree. StrictMode adds development checks. React handles browser rendering; Spring Boot handles API and database operations.
JSX
import React from 'react';
import { createRoot } from 'react-dom/client';
import App from './App.jsx';
import './style.css';
createRoot(document.getElementById('root')).render(<React.StrictMode><App /></React.StrictMode>);
useState holds form, list, login, and feedback state. Controlled inputs copy browser changes into state. fetch sends JSON and a bearer header. Tokens stay in memory and are cleared on logout, refresh, and expiration; there is no localStorage persistence. useEffect schedules expiration cleanup. A ref prevents an old response from repopulating a later session. Errors and network failures are displayed and busy state prevents repeated mutations. Rendering escaped text through JSX helps avoid HTML injection.
Set MONGODB_URI and JWT_SECRET in the backend terminal. The code below generates 32 random bytes and stores the Base64 encoding in the process environment without printing it. Do not replace it with a short phrase.
Windows PowerShell
# Backend terminal, in projects/todo-personal:
$env:MONGODB_URI = 'mongodb+srv://YOUR_DB_USER:YOUR_ENCODED_PASSWORD@YOUR_CLUSTER.mongodb.net/?retryWrites=true&w=majority&authSource=admin'
$jwtBytes = New-Object byte[] 32
$jwtRng = [System.Security.Cryptography.RandomNumberGenerator]::Create()
$jwtRng.GetBytes($jwtBytes)
$jwtRng.Dispose()
$env:JWT_SECRET = [Convert]::ToBase64String($jwtBytes)
# This creates a cryptographically random key without printing it.
mvn test
mvn spring-boot:run
Bash · requires openssl
# macOS / Linux Bash, in projects/todo-personal:
export MONGODB_URI='mongodb+srv://YOUR_DB_USER:YOUR_ENCODED_PASSWORD@YOUR_CLUSTER.mongodb.net/?retryWrites=true&w=majority&authSource=admin'
export JWT_SECRET="$(openssl rand -base64 32)"
mvn test
mvn spring-boot:run
Look for Started TodoApplication and port 8082. Index creation may fail startup if Atlas is unreachable or the users collection already contains duplicate emails. Verify the unique email index in Atlas before registrations.
Keep the same JWT_SECRET in the backend terminal when restarting if you want existing tokens to remain verifiable until expiration. Regenerating it invalidates tokens signed with the previous key. All backend replicas would need the same managed key. Never copy it into React.
To package and run, use mvn clean package, then java -jar target/todo-personal-1.0.0.jar from the backend folder with both environment variables set.
6. Install and start React
Open a second terminal. Change into the frontend directory relative to the backend folder:
Terminal · run in a second window
cd frontend
npm install
npm run dev
On Windows, if your execution policy blocks npm.ps1, use npm.cmd install and npm.cmd run dev. The Vite command uses strictPort so a busy 5173 produces an error instead of silently switching to a CORS-mismatched port.
Open http://localhost:5173 exactly. Opening http://127.0.0.1:5173 creates a different browser origin; the backend currently allows localhost. Use the documented host, or change app.cors.origin deliberately.
Click “Need an account? Register”, use an email and a password with at least 8 characters, then sign in. Create a task, edit its title and completed checkbox, and delete it. Use the Refresh button to reload from the API.
Build the frontend separately using npm run build. The output is frontend/dist. This manual’s development setup uses two servers. Serving a built frontend from another origin requires updating CORS and its API URL configuration.
7. Trace the React workflow
Controlled inputs pair value with onChange; the browser edit updates useState. onSubmit prevents a full-page navigation and calls fetch. The api helper adds Content-Type only when there is a JSON body and Authorization only when a session exists.
Successful login stores accessToken, email, and expiresAt in memory. refresh obtains the owner-filtered list. After create, update, or delete, the list is fetched again. JSX escapes displayed title text. The component never hides a global list by filtering ownerId in the browser; the backend has already selected authorized data.
Tokens are deliberately held in memory. Refreshing the page signs the user out, and logout clears the current browser state. An expiry timer signs out after 15 minutes; a backend 401 also clears an active session. Expiration checking on the backend remains authoritative. A browser timer is only a usability aid.
The helper reads 204 as an empty response and displays validation details or HTTP errors. Network failures are caught and shown. A ref tracks the current session so a stale response from an earlier session cannot repopulate its tasks.
React reference: React Quick Start. Component state, events, and list keys are the main concepts used here.
8. Test authentication and ownership in Postman
Import the personal collection and select the Todo local environment. baseAuthUrl must be http://localhost:8082. The collection creates unique run-specific Alice and Bob email values, stores both tokens, and verifies cross-user access denial.
Method / URL
Body / authorization
Expected
POST /api/auth/register
email and password; no token
201 registration message; 409 duplicate email
POST /api/auth/login
email and password; no token
200 TokenResponse; 401 wrong credentials
GET /api/todos
Authorization: Bearer <accessToken>
200 · only that user’s tasks
POST /api/todos
title and completed + token
201 · server-assigned owner
GET / PUT / DELETE /api/todos/{id}
Valid user token
200 / 200 / 204 for owned id; 404 for another user’s id
8.1 Register Alice
Postman request
POST http://localhost:8082/api/auth/register
Content-Type: application/json
{"email":"alice@example.com","password":"AlicePass123!"}
Expect 201. A second registration with the same normalized email returns 409. Use another fictitious address if this account already exists in your example database.
8.2 Sign in
Postman request
POST http://localhost:8082/api/auth/login
Content-Type: application/json
{"email":"alice@example.com","password":"AlicePass123!"}
In Postman Authorization → Bearer Token, paste the accessToken only; the UI adds Bearer. In a manually constructed header, use Authorization: Bearer followed by a space and the token. Do not send the token in a query string.
8.3 Create Alice’s task
Postman request
POST http://localhost:8082/api/todos
Authorization: Bearer ALICE_TOKEN
Content-Type: application/json
{"title":"Alice private task","completed":false}
Save the returned id. Register and log in as Bob with a different email. Bob’s list must not contain Alice’s task. With Bob’s token, GET, PUT, and DELETE against Alice’s id must all return 404. Afterwards, Alice’s GET must still return her unchanged task.
9. Execute the security and failure checklist
Request GET /api/todos without a bearer token. Expect 401.
Use malformed or tampered token text. Expect 401.
Use a token signed with a different key. Expect 401; the included JWT unit test exercises this.
Use expired, wrong-issuer, or wrong-audience tokens. Expect rejection; included unit tests check each.
Sign in with a wrong password or unknown email. Expect the same 401 message.
Register an already-used email with different case. Expect 409 because normalization and the unique index apply.
Register a password whose UTF-8 encoding is longer than 72 bytes. Expect 400.
Send whitespace title, missing completed, or malformed JSON with a valid token. Expect 400.
Verify Bob cannot list, read, update, or delete Alice’s tasks. Verify Alice can still read and update her task.
Inspect users in Atlas. Expect a BCrypt hash rather than the plaintext password; inspect the unique email index.
Sign out in React. Expect the login screen. Refresh while signed in. Expect a fresh login screen because the token was held in memory.
Wait for expiration, or temporarily reduce app.jwt.ttl-seconds to 30 for a demo, restart, and log in again. React should sign out. The decoder’s default timestamp skew may allow a recently expired token briefly in API tests; the unit test uses an expiration several minutes in the past.
Restart both servers and sign in again. Expect personal tasks to persist.
10. Explain the deployment boundary
This code is complete for the local development example. Before exposing it to real users, add HTTPS, managed secrets and key rotation, login/registration rate limits, email verification and password reset, monitoring, pagination, and a tested recovery process. Keep MongoDB access tightly scoped. Serve production React assets from a deliberate deployment origin and update API/CORS configuration.
There is no refresh-token flow or server-side logout revocation in this example app. Logout removes the browser’s in-memory token; a copied access token remains valid until expiration. Introduce refresh-token rotation and revocation as a separate advanced module, or use an established identity provider. Never describe this logout as immediately revoking all existing tokens.
Read-then-save CRUD uses last-write-wins. Add @Version and conflict handling before relying on concurrent edits. A collection-wide list without pagination fits small example datasets; a production list needs bounds and query design.
Exercise: prove that adding an ownerId field to a malicious JSON body cannot grant access. The request DTO does not accept ownerId, and the service derives ownership from the verified subject. Then add pagination while preserving the owner predicate.
11. Troubleshooting
Symptom
Cause and fix
mvn is not recognized
Install Maven and add its bin directory to PATH. Open a new terminal. Verify mvn -version.
Cannot resolve placeholder MONGODB_URI
Set the environment variable in the terminal that starts the app. IDE launches need an environment variable in their Run Configuration. Spring does not automatically read a .env file.
Connection points to localhost
Use spring.mongodb.uri for this Boot 4 project; a Boot 3 spring.data.mongodb.uri property is not the property used here. Check spelling and active configuration.
Authentication failed / code 18
Use the Atlas database user, not your Atlas website login. Reset its password if needed. Percent-encode URI reserved characters. Verify authSource=admin.
Server selection timeout
Add your current public IP in Atlas Network Access; verify firewall access, active cluster, hostname, and outbound network connectivity. IP addresses can change on Wi-Fi or VPN.
UnknownHostException / SRV lookup failed
Re-copy the actual hostname. SRV requires DNS support; corporate DNS may block it. Use the standard connection string provided by Atlas if your environment cannot resolve SRV.
Address already in use
Stop the old process with Ctrl+C or override SERVER_PORT. If changing the personal API port, change React BASE and the Postman baseUrl too.
HTTP 400
Check the JSON syntax, Content-Type, title, and completed. Inspect details in the JSON error. In the MVC lab, inspect the form validation message.
HTTP 404
Check route and id. In the personal app, a task owned by another user also returns 404.
Browser fails but Postman works
Postman does not enforce browser CORS. Use the documented frontend origin exactly and inspect the browser Network panel.
Dependency download fails
Check proxy settings, Maven settings.xml, and repository reachability. An offline build works only after dependencies have already been downloaded.
JWT_SECRET decode failure: use the Base64 random-key commands. Do not wrap the value in extra quotation marks inside an IDE environment field. 401 after restart: verify the same secret is still configured or sign in again. 403/CORS failure: open the exact http://localhost:5173 origin, inspect preflight, and verify app.cors.origin. Duplicate-key startup failure: resolve duplicate emails in the disposable example database so the unique index can be built.