Authentication

Authentication Routes and Flow

Custom Routes

• GET: /api/auth/validate - Verifies whether the user is authenticated based on cookies stored in the browser.
• GET: /api/auth/logout - Logs out the user by invalidating the session and removing cookies from the browser. It automatically returns back to the frontend with either:
  • /login?success=false&message=This is the failure message.
  • /login?success=true&message=This is the success message!
  • These should be handled on the frontend route.

Spring OAuth Routes

• OAuth Initiation: GET: /api/auth/flow/{provider} - Begins the OAuth authentication process for a specific provider. (Example: /api/auth/flow/discord starts the Discord OAuth flow.)
• OAuth Callback:GET: /api/auth/flow/callback/{provider} - Handles the callback process after the OAuth provider returns data to authenticate the user. (Example: /api/auth/flow/callback/discord processes the callback from Discord OAuth.)
  • If successful, the user is automatically redirected to /dashboard.
  • If failed, the user is automatically redirected to /login?success=false&message=This is the failure message.
    • This should be handled on the frontend route.

Security Details

• CSRF Protection - Automatically managed by Spring Security, so no additional configuration is required.
• Auth Validator / Session Token Cookie Setter - Managed by the CustomAuthenticationSuccessHandler.
  • Cookie Settings:
    • Name: session_token
    • Max Age: 30 days (configurable via a private variable).

Backend Objects

• Protector.java is used to validate whether the user is logged in or not. It automatically handles unauthorized requests (and any other ResponseStatusException) via ControllerExceptionHandler.java

• Protected.java can be applied to a controller method as an annotation. You can find an example inside of the file's Javadoc.

  • AuthController.java contains examples of using Protector.java to protect endpoints.

• GlobalExceptionHandler.java manages exception handling for unauthorized requests

• SecurityConfig.java holds the OAuth provider

  • CustomAuthenticationSuccessHandler.java actually handles the process of authenticating the user once they have been successfully redirected from the OAuth provider back to our server

Examples

Annotation

You may use the Protected annotation to validate requests manually like so:

@RestController
@RequestMapping("/api")
public class ApiController {

    @PostMapping("/any-user")
    public ResponseEntity<ApiResponder<Empty>> apiAnyUser(@Protected final AuthenticationObject authenticationObject) {
        User user = authenticationObject.getUser(); // guaranteed for user to exist at this line.
    }

    @PostMapping("/admin-only")
    public ResponseEntity<ApiResponder<Empty>> apiForAdmins(@Protected(admin = true) final AuthenticationObject authenticationObject) {
        User user = authenticationObject.getUser(); // guaranteed for an admin user to exist at this line.
    }
}

Imperative

You may use the Protector class to validate requests manually like so:

@RestController
@RequestMapping("/api")
public class ApiController {

    private final Protector protector;

    public AdminController(final Protector protector) {
        this.protector = protector;
    }

    @PostMapping("/any-user")
    public ResponseEntity<ApiResponder<Empty>> apiAnyUser(final HttpServletRequest request) {
        AuthenticationObject authenticationObject = protector.validateSession(request);
        User user = authenticationObject.getUser(); // guaranteed for user to exist at this line.
    }

    @PostMapping("/admin-only")
    public ResponseEntity<ApiResponder<Empty>> apiForAdmins(final HttpServletRequest request) {
        AuthenticationObject authenticationObject = protector.validateAdminSession(request);
        User user = authenticationObject.getUser(); // guaranteed for an admin user to exist at this line.
    }
}