MACRO NEPAL
Scalable User Management: Integrating Amazon Cognito User Pools with Java Applications
awiskar acharya
November 21, 2025
2:19 pm

Amazon Cognito User Pools provide a secure, scalable user directory that handles user registration, authentication, and account recovery. For Java applications, Cognito offers a robust alternative to building custom authentication systems, with built-in support for multi-factor authentication, social identity providers, and compliance standards. Let's explore how to integrate Cognito User Pools into Java applications.

Why Cognito User Pools for Java Applications?

Benefits for Java developers:

  • Managed Service - No server infrastructure to maintain
  • Security Best Practices - Built-in password policies, MFA, and encryption
  • Scalability - Handles millions of users automatically
  • Standards Compliance - OAuth 2.0, OpenID Connect, SAML 2.0
  • Cost-Effective - Pay-per-use pricing model
  • Rich Features - Custom attributes, Lambda triggers, advanced security

AWS SDK Dependencies

1. Maven Configuration

<!-- pom.xml --> <dependencies> <dependency> <groupId>software.amazon.awssdk</groupId> <artifactId>cognitoidentityprovider</artifactId> <version>2.20.0</version> </dependency> <dependency> <groupId>software.amazon.awssdk</groupId> <artifactId>auth</artifactId> <version>2.20.0</version> </dependency> <dependency> <groupId>com.nimbusds</groupId> <artifactId>nimbus-jose-jwt</artifactId> <version>9.31</version> </dependency> </dependencies>

Cognito Configuration Service

1. AWS Client Configuration

@Configuration @ConfigurationProperties(prefix = "aws.cognito") @Data public class CognitoConfig { private String userPoolId; private String clientId; private String clientSecret; private String region; private String issuer; @Bean public CognitoIdentityProviderClient cognitoClient() { return CognitoIdentityProviderClient.builder() .region(Region.of(region)) .credentialsProvider(DefaultCredentialsProvider.create()) .build(); } public String getIssuerUrl() { return String.format("https://cognito-idp.%s.amazonaws.com/%s", region, userPoolId); } }

2. Application Properties

# application.yml aws: cognito: user-pool-id: us-east-1_XXXXXXXXX client-id: XXXXXXXXX client-secret: XXXXXXXXX region: us-east-1 issuer: https://cognito-idp.us-east-1.amazonaws.com/us-east-1_XXXXXXXXX

User Management Service

1. Comprehensive Cognito Service

@Service @Slf4j public class CognitoUserService { private final CognitoIdentityProviderClient cognitoClient; private final CognitoConfig cognitoConfig; private final ObjectMapper objectMapper; public CognitoUserService(CognitoIdentityProviderClient cognitoClient, CognitoConfig cognitoConfig) { this.cognitoClient = cognitoClient; this.cognitoConfig = cognitoConfig; this.objectMapper = new ObjectMapper(); } // User Registration public SignUpResult signUp(UserSignUpRequest request) { try { String secretHash = calculateSecretHash(request.getEmail()); SignUpRequest signUpRequest = SignUpRequest.builder() .clientId(cognitoConfig.getClientId()) .username(request.getEmail()) .password(request.getPassword()) .userAttributes( AttributeType.builder() .name("email") .value(request.getEmail()) .build(), AttributeType.builder() .name("given_name") .value(request.getFirstName()) .build(), AttributeType.builder() .name("family_name") .value(request.getLastName()) .build(), AttributeType.builder() .name("email_verified") .value("true") .build() ) .secretHash(secretHash) .build(); SignUpResponse response = cognitoClient.signUp(signUpRequest); return SignUpResult.builder() .success(true) .userSub(response.userSub()) .userConfirmed(response.userConfirmed()) .codeDeliveryDetails(response.codeDeliveryDetails()) .build(); } catch (Exception e) { log.error("User registration failed for email: {}", request.getEmail(), e); return SignUpResult.builder() .success(false) .errorMessage(e.getMessage()) .build(); } } // User Confirmation public boolean confirmSignUp(String email, String confirmationCode) { try { String secretHash = calculateSecretHash(email); ConfirmSignUpRequest confirmRequest = ConfirmSignUpRequest.builder() .clientId(cognitoConfig.getClientId()) .username(email) .confirmationCode(confirmationCode) .secretHash(secretHash) .build(); cognitoClient.confirmSignUp(confirmRequest); return true; } catch (Exception e) { log.error("User confirmation failed for email: {}", email, e); return false; } } // User Authentication public AuthenticationResult authenticate(UserLoginRequest request) { try { String secretHash = calculateSecretHash(request.getUsername()); Map<String, String> authParams = new HashMap<>(); authParams.put("USERNAME", request.getUsername()); authParams.put("PASSWORD", request.getPassword()); authParams.put("SECRET_HASH", secretHash); InitiateAuthRequest authRequest = InitiateAuthRequest.builder() .authFlow(AuthFlowType.USER_PASSWORD_AUTH) .clientId(cognitoConfig.getClientId()) .authParameters(authParams) .build(); InitiateAuthResponse authResponse = cognitoClient.initiateAuth(authRequest); AuthenticationResultType authResult = authResponse.authenticationResult(); return AuthenticationResult.builder() .success(true) .accessToken(authResult.accessToken()) .refreshToken(authResult.refreshToken()) .idToken(authResult.idToken()) .expiresIn(authResult.expiresIn()) .tokenType(authResult.tokenType()) .build(); } catch (NotAuthorizedException e) { log.warn("Authentication failed for user: {}", request.getUsername()); return AuthenticationResult.builder() .success(false) .errorMessage("Invalid credentials") .build(); } catch (Exception e) { log.error("Authentication error for user: {}", request.getUsername(), e); return AuthenticationResult.builder() .success(false) .errorMessage("Authentication failed") .build(); } } // Refresh Token public AuthenticationResult refreshTokens(String username, String refreshToken) { try { String secretHash = calculateSecretHash(username); Map<String, String> authParams = new HashMap<>(); authParams.put("REFRESH_TOKEN", refreshToken); authParams.put("SECRET_HASH", secretHash); InitiateAuthRequest authRequest = InitiateAuthRequest.builder() .authFlow(AuthFlowType.REFRESH_TOKEN_AUTH) .clientId(cognitoConfig.getClientId()) .authParameters(authParams) .build(); InitiateAuthResponse authResponse = cognitoClient.initiateAuth(authRequest); AuthenticationResultType authResult = authResponse.authenticationResult(); return AuthenticationResult.builder() .success(true) .accessToken(authResult.accessToken()) .idToken(authResult.idToken()) .expiresIn(authResult.expiresIn()) .build(); } catch (Exception e) { log.error("Token refresh failed for user: {}", username, e); return AuthenticationResult.builder() .success(false) .errorMessage("Token refresh failed") .build(); } } // Get User Information public UserProfile getUserProfile(String accessToken) { try { GetUserRequest getUserRequest = GetUserRequest.builder() .accessToken(accessToken) .build(); GetUserResponse getUserResponse = cognitoClient.getUser(getUserRequest); UserProfile profile = new UserProfile(); profile.setUsername(getUserResponse.username()); profile.setUserAttributes(extractUserAttributes(getUserResponse.userAttributes())); return profile; } catch (Exception e) { log.error("Failed to get user profile", e); throw new UserProfileException("Failed to retrieve user profile", e); } } // Update User Attributes public boolean updateUserAttributes(String accessToken, Map<String, String> attributes) { try { List<AttributeType> attributeTypes = attributes.entrySet().stream() .map(entry -> AttributeType.builder() .name(entry.getKey()) .value(entry.getValue()) .build()) .collect(Collectors.toList()); UpdateUserAttributesRequest updateRequest = UpdateUserAttributesRequest.builder() .accessToken(accessToken) .userAttributes(attributeTypes) .build(); cognitoClient.updateUserAttributes(updateRequest); return true; } catch (Exception e) { log.error("Failed to update user attributes", e); return false; } } // Change Password public boolean changePassword(String accessToken, String oldPassword, String newPassword) { try { ChangePasswordRequest changePasswordRequest = ChangePasswordRequest.builder() .accessToken(accessToken) .previousPassword(oldPassword) .proposedPassword(newPassword) .build(); cognitoClient.changePassword(changePasswordRequest); return true; } catch (Exception e) { log.error("Password change failed", e); return false; } } // Forgot Password public boolean initiateForgotPassword(String email) { try { String secretHash = calculateSecretHash(email); ForgotPasswordRequest forgotPasswordRequest = ForgotPasswordRequest.builder() .clientId(cognitoConfig.getClientId()) .username(email) .secretHash(secretHash) .build(); cognitoClient.forgotPassword(forgotPasswordRequest); return true; } catch (Exception e) { log.error("Forgot password initiation failed for email: {}", email, e); return false; } } // Confirm Forgot Password public boolean confirmForgotPassword(String email, String confirmationCode, String newPassword) { try { String secretHash = calculateSecretHash(email); ConfirmForgotPasswordRequest confirmRequest = ConfirmForgotPasswordRequest.builder() .clientId(cognitoConfig.getClientId()) .username(email) .confirmationCode(confirmationCode) .password(newPassword) .secretHash(secretHash) .build(); cognitoClient.confirmForgotPassword(confirmRequest); return true; } catch (Exception e) { log.error("Password reset confirmation failed for email: {}", email, e); return false; } } // Admin Operations public boolean adminDisableUser(String username) { try { AdminDisableUserRequest disableRequest = AdminDisableUserRequest.builder() .userPoolId(cognitoConfig.getUserPoolId()) .username(username) .build(); cognitoClient.adminDisableUser(disableRequest); return true; } catch (Exception e) { log.error("Failed to disable user: {}", username, e); return false; } } public boolean adminDeleteUser(String username) { try { AdminDeleteUserRequest deleteRequest = AdminDeleteUserRequest.builder() .userPoolId(cognitoConfig.getUserPoolId()) .username(username) .build(); cognitoClient.adminDeleteUser(deleteRequest); return true; } catch (Exception e) { log.error("Failed to delete user: {}", username, e); return false; } } // Helper Methods private String calculateSecretHash(String username) { try { SecretHashCalculator calculator = SecretHashCalculator.builder() .clientId(cognitoConfig.getClientId()) .clientSecret(cognitoConfig.getClientSecret()) .build(); return calculator.calculateSecretHash(username); } catch (Exception e) { throw new CognitoException("Failed to calculate secret hash", e); } } private Map<String, String> extractUserAttributes(List<AttributeType> attributes) { return attributes.stream() .collect(Collectors.toMap( AttributeType::name, AttributeType::value )); } // DTOs @Data @Builder public static class UserSignUpRequest { private String email; private String password; private String firstName; private String lastName; private String phoneNumber; } @Data @Builder public static class SignUpResult { private boolean success; private String userSub; private boolean userConfirmed; private CodeDeliveryDetailsType codeDeliveryDetails; private String errorMessage; } @Data @Builder public static class UserLoginRequest { private String username; private String password; } @Data @Builder public static class AuthenticationResult { private boolean success; private String accessToken; private String refreshToken; private String idToken; private Integer expiresIn; private String tokenType; private String errorMessage; } @Data public static class UserProfile { private String username; private Map<String, String> userAttributes; public String getEmail() { return userAttributes != null ? userAttributes.get("email") : null; } public String getFirstName() { return userAttributes != null ? userAttributes.get("given_name") : null; } public String getLastName() { return userAttributes != null ? userAttributes.get("family_name") : null; } } }

JWT Token Validation

1. Cognito JWT Validator

@Component public class CognitoJwtValidator { private final CognitoConfig cognitoConfig; private final JWTProcessor<SecurityContext> jwtProcessor; public CognitoJwtValidator(CognitoConfig cognitoConfig) { this.cognitoConfig = cognitoConfig; this.jwtProcessor = createJWTProcessor(); } public CognitoJwt validateToken(String token) { try { JWTClaimsSet claimsSet = jwtProcessor.process(token, null); CognitoJwt jwt = new CognitoJwt(); jwt.setValid(true); jwt.setUsername(claimsSet.getStringClaim("cognito:username")); jwt.setEmail(claimsSet.getStringClaim("email")); jwt.setGroups(claimsSet.getStringListClaim("cognito:groups")); jwt.setIssuer(claimsSet.getIssuer()); jwt.setExpirationTime(claimsSet.getExpirationTime()); jwt.setClaims(claimsSet.getClaims()); return jwt; } catch (Exception e) { log.error("JWT validation failed", e); return CognitoJwt.invalid(e.getMessage()); } } private JWTProcessor<SecurityContext> createJWTProcessor() { try { String jwksUrl = cognitoConfig.getIssuerUrl() + "/.well-known/jwks.json"; JWKSource<SecurityContext> keySource = new RemoteJWKSet<>(new URL(jwksUrl)); ConfigurableJWTProcessor<SecurityContext> jwtProcessor = new DefaultJWTProcessor<>(); jwtProcessor.setJWSKeySelector(new JWSVerificationKeySelector<>( JWSAlgorithm.RS256, keySource)); jwtProcessor.setJWTClaimsSetVerifier(new DefaultJWTClaimsVerifier<>( new JWTClaimsSet.Builder() .issuer(cognitoConfig.getIssuerUrl()) .build(), new HashSet<>(Arrays.asList("sub", "aud", "exp", "iss", "token_use")))); return jwtProcessor; } catch (Exception e) { throw new CognitoException("Failed to create JWT processor", e); } } @Data public static class CognitoJwt { private boolean valid; private String username; private String email; private List<String> groups; private String issuer; private Date expirationTime; private Map<String, Object> claims; private String error; public static CognitoJwt invalid(String error) { CognitoJwt jwt = new CognitoJwt(); jwt.setValid(false); jwt.setError(error); return jwt; } public boolean isExpired() { return expirationTime != null && expirationTime.before(new Date()); } public boolean hasGroup(String group) { return groups != null && groups.contains(group); } public boolean hasAnyGroup(String... groups) { return this.groups != null && Arrays.stream(groups) .anyMatch(this.groups::contains); } } }

Spring Security Integration

1. Cognito Authentication Filter

@Component public class CognitoAuthenticationFilter extends OncePerRequestFilter { private final CognitoJwtValidator jwtValidator; public CognitoAuthenticationFilter(CognitoJwtValidator jwtValidator) { this.jwtValidator = jwtValidator; } @Override protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response, FilterChain filterChain) throws ServletException, IOException { String authHeader = request.getHeader("Authorization"); if (authHeader != null && authHeader.startsWith("Bearer ")) { String token = authHeader.substring(7); try { CognitoJwtValidator.CognitoJwt jwt = jwtValidator.validateToken(token); if (jwt.isValid() && !jwt.isExpired()) { UsernamePasswordAuthenticationToken authentication = createAuthentication(jwt); SecurityContextHolder.getContext().setAuthentication(authentication); } else { handleInvalidToken(response, jwt); return; } } catch (Exception e) { handleValidationError(response, e); return; } } filterChain.doFilter(request, response); } private UsernamePasswordAuthenticationToken createAuthentication( CognitoJwtValidator.CognitoJwt jwt) { List<GrantedAuthority> authorities = new ArrayList<>(); // Add groups as authorities if (jwt.getGroups() != null) { jwt.getGroups().forEach(group -> authorities.add(new SimpleGrantedAuthority("ROLE_" + group))); } CognitoUser principal = new CognitoUser( jwt.getUsername(), jwt.getEmail(), jwt.getClaims() ); return new UsernamePasswordAuthenticationToken(principal, null, authorities); } private void handleInvalidToken(HttpServletResponse response, CognitoJwtValidator.CognitoJwt jwt) throws IOException { response.setStatus(HttpStatus.UNAUTHORIZED.value()); response.setContentType(MediaType.APPLICATION_JSON_VALUE); Map<String, String> errorResponse = new HashMap<>(); errorResponse.put("error", "invalid_token"); errorResponse.put("message", jwt.getError()); objectMapper.writeValue(response.getWriter(), errorResponse); } private void handleValidationError(HttpServletResponse response, Exception e) throws IOException { log.error("Token validation error", e); response.setStatus(HttpStatus.UNAUTHORIZED.value()); response.setContentType(MediaType.APPLICATION_JSON_VALUE); Map<String, String> errorResponse = new HashMap<>(); errorResponse.put("error", "token_validation_failed"); errorResponse.put("message", "Token validation failed"); objectMapper.writeValue(response.getWriter(), errorResponse); } @Data public static class CognitoUser { private final String username; private final String email; private final Map<String, Object> claims; public String getFirstName() { return claims != null ? (String) claims.get("given_name") : null; } public String getLastName() { return claims != null ? (String) claims.get("family_name") : null; } } }

2. Security Configuration

@Configuration @EnableWebSecurity @EnableGlobalMethodSecurity(prePostEnabled = true) public class SecurityConfig { private final CognitoAuthenticationFilter cognitoAuthenticationFilter; public SecurityConfig(CognitoAuthenticationFilter cognitoAuthenticationFilter) { this.cognitoAuthenticationFilter = cognitoAuthenticationFilter; } @Bean public SecurityFilterChain filterChain(HttpSecurity http) throws Exception { return http .csrf(csrf -> csrf.disable()) .sessionManagement(session -> session .sessionCreationPolicy(SessionCreationPolicy.STATELESS) ) .authorizeHttpRequests(authz -> authz .requestMatchers("/api/auth/**").permitAll() .requestMatchers("/api/public/**").permitAll() .requestMatchers("/api/admin/**").hasRole("ADMIN") .anyRequest().authenticated() ) .addFilterBefore(cognitoAuthenticationFilter, UsernamePasswordAuthenticationFilter.class) .exceptionHandling(exceptions -> exceptions .authenticationEntryPoint(new HttpStatusEntryPoint(HttpStatus.UNAUTHORIZED)) ) .build(); } }

REST Controller

1. Authentication Controller

@RestController @RequestMapping("/api/auth") @Slf4j public class AuthController { private final CognitoUserService cognitoUserService; public AuthController(CognitoUserService cognitoUserService) { this.cognitoUserService = cognitoUserService; } @PostMapping("/signup") public ResponseEntity<?> signUp(@Valid @RequestBody SignUpRequest request) { CognitoUserService.SignUpResult result = cognitoUserService.signUp(request); if (result.isSuccess()) { return ResponseEntity.ok(Map.of( "message", "User registered successfully", "userConfirmed", result.isUserConfirmed(), "userSub", result.getUserSub() )); } else { return ResponseEntity.badRequest().body(Map.of( "error", "Registration failed", "message", result.getErrorMessage() )); } } @PostMapping("/confirm") public ResponseEntity<?> confirmSignUp(@RequestBody ConfirmRequest request) { boolean success = cognitoUserService.confirmSignUp( request.getEmail(), request.getConfirmationCode()); if (success) { return ResponseEntity.ok(Map.of("message", "User confirmed successfully")); } else { return ResponseEntity.badRequest().body(Map.of( "error", "Confirmation failed" )); } } @PostMapping("/login") public ResponseEntity<?> login(@Valid @RequestBody LoginRequest request) { CognitoUserService.AuthenticationResult result = cognitoUserService.authenticate(request); if (result.isSuccess()) { return ResponseEntity.ok(Map.of( "accessToken", result.getAccessToken(), "refreshToken", result.getRefreshToken(), "idToken", result.getIdToken(), "expiresIn", result.getExpiresIn(), "tokenType", result.getTokenType() )); } else { return ResponseEntity.status(HttpStatus.UNAUTHORIZED).body(Map.of( "error", "Authentication failed", "message", result.getErrorMessage() )); } } @PostMapping("/refresh") public ResponseEntity<?> refreshTokens(@RequestBody RefreshRequest request) { CognitoUserService.AuthenticationResult result = cognitoUserService.refreshTokens(request.getUsername(), request.getRefreshToken()); if (result.isSuccess()) { return ResponseEntity.ok(Map.of( "accessToken", result.getAccessToken(), "idToken", result.getIdToken(), "expiresIn", result.getExpiresIn() )); } else { return ResponseEntity.status(HttpStatus.UNAUTHORIZED).body(Map.of( "error", "Token refresh failed" )); } } @PostMapping("/forgot-password") public ResponseEntity<?> forgotPassword(@RequestBody ForgotPasswordRequest request) { boolean success = cognitoUserService.initiateForgotPassword(request.getEmail()); if (success) { return ResponseEntity.ok(Map.of( "message", "Password reset code sent" )); } else { return ResponseEntity.badRequest().body(Map.of( "error", "Password reset initiation failed" )); } } @PostMapping("/reset-password") public ResponseEntity<?> resetPassword(@RequestBody ResetPasswordRequest request) { boolean success = cognitoUserService.confirmForgotPassword( request.getEmail(), request.getConfirmationCode(), request.getNewPassword()); if (success) { return ResponseEntity.ok(Map.of( "message", "Password reset successfully" )); } else { return ResponseEntity.badRequest().body(Map.of( "error", "Password reset failed" )); } } // DTOs for requests @Data public static class SignUpRequest { @Email private String email; @Size(min = 8) private String password; private String firstName; private String lastName; } @Data public static class ConfirmRequest { private String email; private String confirmationCode; } @Data public static class LoginRequest { private String username; private String password; } @Data public static class RefreshRequest { private String username; private String refreshToken; } @Data public static class ForgotPasswordRequest { private String email; } @Data public static class ResetPasswordRequest { private String email; private String confirmationCode; private String newPassword; } }

Testing Cognito Integration

1. Unit Tests

@ExtendWith(MockitoExtension.class) class CognitoUserServiceTest { @Mock private CognitoIdentityProviderClient cognitoClient; @Mock private CognitoConfig cognitoConfig; @InjectMocks private CognitoUserService cognitoUserService; @Test void shouldSignUpUserSuccessfully() { // Given UserSignUpRequest request = UserSignUpRequest.builder() .email("[email protected]") .password("Password123!") .firstName("John") .lastName("Doe") .build(); when(cognitoConfig.getClientId()).thenReturn("test-client-id"); when(cognitoConfig.getClientSecret()).thenReturn("test-secret"); SignUpResponse mockResponse = SignUpResponse.builder() .userSub("user-sub-123") .userConfirmed(true) .build(); when(cognitoClient.signUp(any(SignUpRequest.class))).thenReturn(mockResponse); // When SignUpResult result = cognitoUserService.signUp(request); // Then assertTrue(result.isSuccess()); assertEquals("user-sub-123", result.getUserSub()); assertTrue(result.isUserConfirmed()); } @Test void shouldHandleAuthenticationFailure() { // Given UserLoginRequest request = new UserLoginRequest("[email protected]", "wrong-password"); when(cognitoConfig.getClientId()).thenReturn("test-client-id"); when(cognitoConfig.getClientSecret()).thenReturn("test-secret"); when(cognitoClient.initiateAuth(any(InitiateAuthRequest.class))) .thenThrow(NotAuthorizedException.builder().message("Invalid credentials").build()); // When AuthenticationResult result = cognitoUserService.authenticate(request); // Then assertFalse(result.isSuccess()); assertEquals("Invalid credentials", result.getErrorMessage()); } }

Best Practices for Cognito Integration

  1. Secure Configuration - Store client secrets in AWS Secrets Manager
  2. Error Handling - Implement comprehensive error handling and logging
  3. Token Management - Use appropriate token expiration and refresh strategies
  4. Input Validation - Validate all user inputs before sending to Cognito
  5. Monitoring - Set up CloudWatch alarms for authentication failures
  6. Security - Implement proper CORS policies and HTTPS enforcement
  7. Testing - Create comprehensive unit and integration tests

Conclusion

Integrating Amazon Cognito User Pools with Java applications provides a robust, scalable, and secure user management solution. By leveraging Cognito's managed service, Java developers can:

  • Focus on Business Logic - Avoid building and maintaining custom authentication systems
  • Ensure Security - Benefit from AWS security best practices and compliance
  • Scale Effortlessly - Handle user growth without infrastructure concerns
  • Reduce Costs - Pay only for active users with no upfront costs
  • Enable Advanced Features - MFA, social login, custom workflows via Lambda triggers

The combination of AWS SDK for Java, Spring Security integration, and proper JWT validation creates a comprehensive authentication solution suitable for enterprise Java applications. By implementing the patterns shown here, Java teams can deliver secure, feature-rich user authentication while maintaining development velocity and operational excellence.

Category : JAVA

Leave a Reply

Your email address will not be published. Required fields are marked *


Macro Nepal Helper