From 5ca98df7caebf56990e26aa83a1a2b626ba16660 Mon Sep 17 00:00:00 2001
From: Kamal Wickramanayake <kamal@inbox.lk>
Date: Mon, 6 Jul 2026 06:32:08 +0530
Subject: Microservices: Documentation improved

---
 .../security/UserRestController.java               | 47 ++++++++++++++++++----
 1 file changed, 40 insertions(+), 7 deletions(-)

(limited to 'microservices/03-resource-server/src/main/java/com')

diff --git a/microservices/03-resource-server/src/main/java/com/example/resourceserver/security/UserRestController.java b/microservices/03-resource-server/src/main/java/com/example/resourceserver/security/UserRestController.java
index 1b0598d..c7844a0 100644
--- a/microservices/03-resource-server/src/main/java/com/example/resourceserver/security/UserRestController.java
+++ b/microservices/03-resource-server/src/main/java/com/example/resourceserver/security/UserRestController.java
@@ -3,11 +3,8 @@ package com.example.resourceserver.security;
 import java.security.Principal;
 import java.util.Collection;
 import java.util.Map;
-import java.util.Optional;
-import java.util.Set;
 import java.util.stream.Collectors;
 
-import org.springframework.http.ResponseEntity;
 import org.springframework.security.core.Authentication;
 import org.springframework.security.core.GrantedAuthority;
 import org.springframework.security.core.annotation.AuthenticationPrincipal;
@@ -26,17 +23,41 @@ public class UserRestController {
         this.userService = userService;
     }
 
+    /**
+     * What is in Principal?
+     * 
+     * Note that we are returning the details just for testing (here and in some
+     * other methods below). But what is typically done is not returning such
+     * details but use the details within the method itself to determine who is the
+     * calling user and the roles of that user.
+     * 
+     * @param principal
+     * @return
+     */
     @GetMapping("/test")
     public String test(Principal principal) {
         return principal.toString();
     }
 
+    /**
+     * principal.getName() returns the OAuth2 authenticated user name. Can be
+     * trusted within this method.
+     * 
+     * @param principal
+     * @return
+     */
     @GetMapping("/test-username")
     public String testName(Principal principal) {
         return principal.getName();
     }
 
-    // Get roles using the Authentication object
+    /**
+     * Roles returned by authentication.getAuthorities() may not always have custom
+     * roles.
+     * 
+     * @param authentication
+     * @return
+     */
     @GetMapping("/test-roles-auth")
     public Collection<String> getRoles(Authentication authentication) {
         return authentication.getAuthorities().stream()
@@ -44,16 +65,28 @@ public class UserRestController {
                 .collect(Collectors.toList());
     }
 
-    // Inspect raw JWT claims directly
+    /**
+     * Inspect raw JWT claims directly.
+     * 
+     * @param jwt
+     * @return
+     */
     @GetMapping("/test-roles-jwt")
     public Map<String, Object> getClaims(@AuthenticationPrincipal Jwt jwt) {
         return jwt.getClaims(); // Extract custom JSON fields containing roles
     }
 
-    /* Not very secure because unverifiable headers can be introduced by unwanted parties */
+    /**
+     * Within a method, use the X-User-Roles HTTP header to determine the user
+     * roles.
+     * 
+     * Not very secure because unverifiable headers may be introduced by attackers.
+     * So to trust the roles so received, this service should have been
+     * deployed in an access restricted network environment.
+     */
     @GetMapping("/test-roles-headers")
     public String getRolesFromHeaders(@RequestHeader("X-User-Name") String username,
             @RequestHeader("X-User-Roles") String roles) {
-        return "Roles: " + roles + ", username: " + username ;
+        return "Roles: " + roles + ", username: " + username;
     }
 }
-- 
cgit v1.2.3