REST Endpoints¶
Complete reference for all REST API endpoints in the Spring Security Reference project. Each endpoint demonstrates different authentication and authorization patterns.
🔓 Public Endpoints¶
GET /api/public/hello¶
Public endpoint requiring no authentication.
🎓 Learning Points:
- No security constraints applied
- Accessible without any credentials
- Used for health checks and public information
🔐 Authentication Endpoints¶
POST /api/auth/login¶
Generate JWT token for API authentication.
{
"token": "eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJhZG1pbiIsInJvbGUiOiJST0xFX0FETUlOIiwiaWF0IjoxNjk0NTIwMDAwLCJleHAiOjE2OTQ2MDY0MDB9.signature",
"username": "admin",
"role": "ROLE_ADMIN",
"message": "Login successful - use this JWT token for authenticated requests",
"usage": "Add header: Authorization: Bearer eyJhbGciOiJIUzUxMiJ9..."
}
🎓 Learning Points:
- Generates JWT tokens with user identity and role claims
- No authentication required to obtain token
- Token expires after 24 hours (configurable)
- Role determination based on username pattern
📝 Available Test Users:
admin/password→ROLE_ADMINuser/password→ROLE_USERjdbcadmin/password→ROLE_ADMINldapadmin/password→ROLE_ADMIN
GET /api/auth/info¶
Retrieve current authentication information.
🎓 Learning Points:
- Requires valid authentication
- Shows current security context details
- Identifies authentication method used
- Useful for debugging authentication issues
👨💼 Admin Endpoints¶
GET /api/admin/secure¶
Secure endpoint requiring ROLE_ADMIN authority.
🎓 Learning Points:
- Requires
ROLE_ADMINauthority - Returns 403 Forbidden for non-admin users
- Authenticated via the JWT bearer token from
/api/auth/login—/api/**is stateless - Demonstrates role-based access control
⚠️ Error Response (403 Forbidden):
{
"error": "Access Denied",
"message": "You don't have permission to access this resource",
"timestamp": "2024-01-15T10:30:00Z",
"path": "/api/admin/secure"
}
👤 User Endpoints¶
GET /api/user/secure¶
Secure endpoint for users with ROLE_USER or ROLE_ADMIN.
🎓 Learning Points:
- Accepts both
ROLE_USERandROLE_ADMIN - Demonstrates role hierarchy (ADMIN > USER)
- Multi-role endpoint access pattern
- Role-based response customization
🗄️ JDBC Authentication Endpoints¶
GET /api/jdbc/users¶
Demonstration endpoint for JDBC database authentication.
🎓 Learning Points:
- The JDBC
AuthenticationProvidervalidates credentials at/api/auth/login - The endpoint itself accepts a Bearer JWT —
/api/**is stateless - Works in the
defaultandjdbc-onlyprofiles
📝 JDBC Test Credentials:
- Username:
jdbcadmin, Password:password(ROLE_ADMIN) - Username:
jdbcuser, Password:password(ROLE_USER)
🏢 LDAP Authentication Endpoints¶
GET /api/ldap/users¶
Demonstration endpoint for LDAP directory authentication.
# Step 1: login through the LDAP provider (the embedded test
# directory starts automatically on port 18389)
TOKEN=$(curl -s -X POST http://localhost:8080/api/auth/login \
-d "username=ldapadmin&password=password" | jq -r .token)
# Step 2: call the endpoint with the issued JWT
curl -H "Authorization: Bearer $TOKEN" \
http://localhost:8080/api/ldap/users
🎓 Learning Points:
- The
LdapAuthenticationProviderbinds to the directory during login - The endpoint itself accepts a Bearer JWT —
/api/**is stateless - LDAP provider active in
defaultandldap-onlyprofiles; embedded LDAP is disabled by default - Group-based role mapping
📝 LDAP Test Credentials:
- Username:
ldapadmin, Password:password(ROLE_ADMIN) - Username:
ldapuser, Password:password(ROLE_USER)
🌐 OAuth2 Authentication Endpoints¶
GET /api/oauth2/profile¶
User profile endpoint for OAuth2/OIDC authenticated users.
🎓 Learning Points:
- Handles both OAuth2 and traditional users (branches on principal type)
- Extracts OAuth2 user attributes (email, name, picture) when the principal is an
OAuth2User - The
OAuth2Userbranch requires a completedoauth2Loginflow — see LAB-011 (local IdP, Docker) - With a JWT, you get the fallback branch (
user+authorities)
🔧 OAuth2 Configuration:
- Targets the local IdP lab (
infrastructure/idp, Docker) — no Google/GitHub/Facebook registrations are configured - OIDC (OpenID Connect) compatible
oauth2-onlyprofile chain exists;oauth2Loginwiring is pending the end-to-end lab
📊 Endpoint Summary Matrix¶
| Endpoint | Auth Method | Role Required | Profile | Purpose |
|---|---|---|---|---|
/api/public/hello | None | - | All | Public access demo |
/api/auth/login | None | - | All | JWT token generation |
/api/auth/info | Any | Any | All | Auth debugging |
/api/admin/secure | Any | ADMIN | All | Admin-only access |
/api/user/secure | Any | USER/ADMIN | All | User access demo |
/api/jdbc/users | JWT (JDBC-backed login) | USER/ADMIN | default, jdbc-only | JDBC auth demo |
/api/ldap/users | JWT (LDAP-backed login) | USER/ADMIN | default, ldap-only | LDAP auth demo |
/api/oauth2/profile | JWT (OAuth2User branch needs oauth2Login) | Authenticated | default, oauth2-only | OAuth2 profile |
🎯 Testing Strategies¶
Unit Testing Endpoints¶
@Test
@WithMockUser(roles = "ADMIN")
void adminEndpointWithAdminRole() throws Exception {
mockMvc.perform(get("/api/admin/secure"))
.andExpect(status().isOk())
.andExpect(jsonPath("$.message").value("Hello, Admin! (secured endpoint)"));
}
Integration Testing¶
@Test
void jwtAuthenticationFlow() {
// 1. Login to get JWT token
String token = getJwtToken("admin", "password");
// 2. Use token to access secured endpoint
given()
.header("Authorization", "Bearer " + token)
.when()
.get("/api/admin/secure")
.then()
.statusCode(200);
}
🚀 Next Steps¶
- Authentication Flow → - Understand authentication sequences
- Error Handling → - API error response patterns
- Security Configuration → - Security implementation details
- Testing Examples → - Comprehensive testing patterns
📋 This reference covers all REST endpoints with practical examples, authentication requirements, and educational insights for learning Spring Security patterns.