Skip to content

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.

GET /api/public/hello
Host: localhost:8080
"Hello, world! (public endpoint - no authentication required)"
curl http://localhost:8080/api/public/hello

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

POST /api/auth/login
Content-Type: application/x-www-form-urlencoded

username=admin&password=password
{
  "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..."
}
curl -X POST http://localhost:8080/api/auth/login \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "username=admin&password=password"

🎓 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_ADMIN
  • user / password → ROLE_USER
  • jdbcadmin / password → ROLE_ADMIN
  • ldapadmin / password → ROLE_ADMIN

GET /api/auth/info

Retrieve current authentication information.

GET /api/auth/info
Authorization: Bearer eyJhbGciOiJIUzUxMiJ9...
{
  "authenticated": true,
  "username": "admin",
  "authorities": [
    {
      "authority": "ROLE_ADMIN"
    }
  ],
  "authType": "JWT",
  "principalType": "UsernamePasswordAuthenticationToken"
}
curl -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  http://localhost:8080/api/auth/info

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

GET /api/admin/secure
Authorization: Bearer eyJhbGciOiJIUzUxMiJ9...
{
  "message": "Hello, Admin! (secured endpoint)",
  "user": "admin",
  "authorities": [
    {
      "authority": "ROLE_ADMIN"
    }
  ],
  "authType": "JWT"
}
curl -H "Authorization: Bearer YOUR_ADMIN_JWT_TOKEN" \
  http://localhost:8080/api/admin/secure

🎓 Learning Points:

  • Requires ROLE_ADMIN authority
  • 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.

GET /api/user/secure
Authorization: Bearer eyJhbGciOiJIUzUxMiJ9...
{
  "message": "Hello, User! (secured endpoint)",
  "user": "user",
  "authorities": [
    {
      "authority": "ROLE_USER"
    }
  ],
  "authType": "JWT"
}
curl -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  http://localhost:8080/api/user/secure

🎓 Learning Points:

  • Accepts both ROLE_USER and ROLE_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.

GET /api/jdbc/users
Authorization: Bearer <JWT from login as jdbcadmin>
{
  "message": "JDBC Authentication Demo",
  "user": "jdbcadmin",
  "credentials": {
    "jdbcadmin": "password (ROLE_ADMIN)",
    "jdbcuser": "password (ROLE_USER)"
  }
}
# Step 1: login through the JDBC provider
TOKEN=$(curl -s -X POST http://localhost:8080/api/auth/login \
  -d "username=jdbcadmin&password=password" | jq -r .token)

# Step 2: call the endpoint with the issued JWT
curl -H "Authorization: Bearer $TOKEN" \
  http://localhost:8080/api/jdbc/users

🎓 Learning Points:

  • The JDBC AuthenticationProvider validates credentials at /api/auth/login
  • The endpoint itself accepts a Bearer JWT — /api/** is stateless
  • Works in the default and jdbc-only profiles

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

GET /api/ldap/users
Authorization: Bearer <JWT from login as ldapadmin>
{
  "message": "LDAP Authentication Demo",
  "user": "ldapadmin",
  "credentials": {
    "ldapadmin": "password (ROLE_ADMIN)",
    "ldapuser": "password (ROLE_USER)"
  }
}
# 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 LdapAuthenticationProvider binds to the directory during login
  • The endpoint itself accepts a Bearer JWT — /api/** is stateless
  • LDAP provider active in default and ldap-only profiles; 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.

GET /api/oauth2/profile
Authorization: Bearer <JWT>
{
  "message": "OAuth2 Authentication Demo",
  "user": "john.doe@example.com",
  "email": "john.doe@example.com",
  "provider": "OAuth2",
  "attributes": {
    "sub": "12345",
    "name": "John Doe",
    "email": "john.doe@example.com",
    "picture": "https://avatar.url"
  }
}
{
  "message": "OAuth2 Authentication Demo",
  "user": "admin",
  "authorities": [
    {
      "authority": "ROLE_ADMIN"
    }
  ]
}
# /api/** is stateless — session cookies are not accepted here
curl -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  http://localhost:8080/api/oauth2/profile

🎓 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 OAuth2User branch requires a completed oauth2Login flow — 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-only profile chain exists; oauth2Login wiring 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


📋 This reference covers all REST endpoints with practical examples, authentication requirements, and educational insights for learning Spring Security patterns.