AdventureTube Backend Server

The AdventureTube backend server is a core component of the project, supporting the iOS app by enabling users to place YouTube stories on a map. It functions primarily as a Content Management System (CMS) and partially as a Customer Relationship Management (CRM) system, processing user-generated content and storing it in two databases:

  • RDBMS (PostgreSQL 15.2): Stores structured data such as user details and content metadata.
  • MongoDB 6.0: Handles mapping user content and enabling location-based interactions.

The backend ensures secure storage, access control, and authentication using:

  • Spring Boot 3.2 – Provides a modular and scalable microservices architecture.
  • Spring Security 6.2 – Manages authentication, authorization, and access control.
  • JWT (JSON Web Token) with RSA Encryption – Enables secure, stateless user authentication.

Using JWT for Stateless Authentication

The AdventureTube iOS application uses Google Sign-In to obtain an ID token from Google. This ID token securely represents the user’s identity, allowing it to be passed to the backend server for verification.

 * Access Google API from your app backend. will  allow AdventureTube Backend server  can make Google API calls on behalf of users while 

  user is offline and refresh token  if access token expires.

Authentication Process in Spring Boot Backend

  1. Receive the Google ID token from the client
  2. Get OAuth server client ID
    • The app needs to pass the identity of signed-in users to the backend server using an ID token and retrieve the OAuth server client ID.
  3. Verify the Google ID token
    • Ensure its authenticity using Google’s public keys.
  4. Generate your own JWT after successful verification
    • Create a JWT token with user details and roles.
  5. Use the JWT for subsequent API requests
    • Attach the JWT in the Authorization header for secure communication with other services.

Role and Responsibility: Gateway Service vs. Auth-Service Module

In the AdventureTube microservices architecture, the Gateway Service and the Auth-Service module work together to manage authentication and authorization efficiently.

Gateway Service (Spring Cloud Gateway)

  • Serves as the central entry point for all incoming requests to microservices.
  • Intercepts HTTP requests and enforces authentication and authorization policies.
  • Validates the presence of a JWT token before forwarding requests to other services.
  • Routes requests to the appropriate microservice after security checks.

Auth-Service Module (AdventureTube Microservices)

  • Handles user authentication using Google OAuth2.
  • Verifies the Google ID token and generates an AdventureTube JWT token.
  • Manages user roles and permissions within the system.
  • Issues access and refresh tokens for secure and continuous authentication.
  • Provides an endpoint for user role validation, used by the Gateway Service for role-based access control.

How They Work Together

  1. The Gateway Service intercepts all API requests and checks for a valid JWT token.
  2. If the token is missing or invalid, the request is rejected, and an authentication error is returned unless request url is public.
  3. If the token is valid, the Gateway forwards the request to the appropriate microservice.
  4. If additional role validation is required, the Gateway may call the Auth-Service to verify permissions before proceeding.
  5. The Auth-Service manages token renewal (refresh tokens) and updates user roles dynamically.

By centralizing security at the Gateway Service, the system ensures a unified security model, while the Auth-Service focuses on authentication, role management, and token issuance. This separation of responsibilities ensures scalability, flexibility, and maintainability across AdventureTube’s microservices architecture.

By leveraging these technologies, the system ensures that only authorized users can manage and interact with their content while maintaining a seamless and secure experience across the AdventureTube platform.

Spring Security for Authentication

Spring Security provides a robust authentication mechanism for securing applications. The authentication flow in AdventureTube’s auth-service module consists of several key components:

1. CustomUserDetailService (loadUserByUsername method)

  • Retrieves user details from the Member-Service via a REST API call.

  • Converts the fetched user data into a Spring Security UserDetails object.

  • Ensures the user exists and has valid credentials before authentication.

  • Throws:

    • UserNotFoundException if the user is not found.

    • BadCredentialsException if credentials are incomplete or incorrect.

2. CustomAuthenticationManager (authenticationManager.authenticate)

  • Authenticates users based on email and password.

  • Uses UserDetailsService (CustomUserDetailService) to fetch user details.

  • Compares the hashed password stored in the database with the provided password.

  • If the credentials match, authentication succeeds; otherwise, authentication fails with a BadCredentialsException.

3. Security Filter Chain (apiFilterChain)

  • Configures authentication rules for auth-service endpoints:

    • Allows public access to /auth/register, /auth/login, /auth/refreshToken, /auth/logout.

    • Requires ADMIN role for other endpoints.

  • Adds JwtAuthFilter before UsernamePasswordAuthenticationFilter to:

    • Extract and validate JWT tokens from incoming requests.

    • Authenticate users based on the extracted JWT claims.

4. JWT Handling in JwtAuthFilter

  • Extracts the JWT token from the request.

  • Validates the token and sets authentication in SecurityContextHolder.

  • Ensures subsequent requests are processed with the correct authentication context.

5. Custom Authentication Provider (Optional)

  • Instead of relying solely on UserDetailsService, a CustomAuthenticationProvider can be implemented to:

    • Customize authentication logic beyond default user validation.

Handling Token Expiration: Client-Side Errors vs. Server-Side Token Renewal

When designing the refresh token process, one key decision is whether to return an error to the client when an access token expires or to renew the token immediately from the server. Below is a comparison of both approaches:

Returning Error to Client-Side

  • The server returns an error (e.g., HTTP 401 Unauthorized) when the access token expires.

  • The client then initiates a token renewal process using the refresh token.

  • This method provides explicit control and awareness to the client, allowing it to manage token renewal.

Immediate Token Renewal from Server-Side

  • The server automatically renews the access token upon detecting expiration, without returning an error.

  • This hides token expiration complexities from the client, offering a seamless user experience.

  • Clients are expected to always send both access and refresh tokens, ensuring continuous access.

Choosing the right approach depends on the specific needs of the system and the balance between client control and seamless authentication.

Exception Handling in AdventureTube Project

Dual Goals of Exception Handling in REST APIs

Exception handling in the AdventureTube microservices project serves two critical goals:

  1. Managing System Exceptions

    • Handle backend failures similar to traditional Java applications.
    • Ensure robust logging and debugging mechanisms.

  2. Providing Actionable Error Messages to API Consumers

    • Communicate meaningful, structured error messages.
    • Ensure errors are not just informational but also actionable, helping clients (such as the iOS app) resolve issues effectively.

Exception Handling Across Different Layers

Each backend layer has specific responsibilities when handling exceptions.

1. Repository Layer (Data Access Layer)

  • Handles database-specific exceptions such as constraint violations and query errors.
  • Wraps exceptions in domain-specific errors to provide meaningful context.
  • Logs errors to ensure visibility for auditing and debugging.

2. Service Layer (Business Logic Layer)

  • Catches repository-layer exceptions and provides contextual information for better traceability.
  • Wraps exceptions in service-specific errors when necessary.
  • Logs errors to monitor business logic failures and unexpected conditions.

3. Controller Layer (REST API Layer)

  • Handles exceptions thrown from the service layer and ensures they are converted into HTTP responses.
  • Uses centralized exception handling mechanisms for consistent error formatting.
  • Logs exceptions for API monitoring and analysis.

Avoiding RuntimeExceptions in the Controller Layer

  • Directly throwing unchecked runtime exceptions in the controller layer should be avoided.
  • Instead, structured exception handling and centralized error management should be used.
  • The primary role of the Controller Layer is to:
    • Deliver accurate and actionable error messages.
    • Ensure error responses are consistently formatted and meaningful.

Standard API Error Response Format

A consistent error response format ensures that API consumers (such as the iOS app) can handle errors predictably.

FieldDescription
timestampTime when the error occurred
statusHTTP status code (e.g., 400, 404, 500)
errorGeneral error category
messageHuman-readable error message
pathAPI endpoint where the error occurred
error_codeUnique error code for iOS error handling

 

References

For further development and implementation of Spring Security with Gateway, refer to the following resources:

  1. Authentication and Authorization with Spring Security
  2. Spring Cloud Gateway Security with JWT
  3. GitHub: Spring Cloud API Gateway JWT Implementation
  4. GitHub: Spring Cloud Security with JWT