Skip to main content

JWT Validation

How LibreApps Desktop ensures the integrity and authenticity of user requests.

Overview​

Every request from LibreApps Desktop frontend to the backend must include a JSON Web Token (JWT) in the Authorization header. The backend services validate this token to ensure it was issued by Keycloak and has not been tampered with.

Token Structure​

A JWT consists of three parts:

  1. Header: Contains the algorithm used for signing (e.g., RS256).
  2. Payload: Contains claims about the user (e.g., sub, preferred_username, realm_access.roles).
  3. Signature: Used to verify that the sender of the JWT is who it says it is and to ensure that the message wasn't changed along the way.

Validation Process​

The LibreApps Gateway (or a microservice) performs the following checks:

  1. Signature Verification: Uses Keycloak's public key to verify the token's signature.
  2. Expiration Check: Ensures the exp claim is in the future.
  3. Issuer Check: Verifies that the iss claim matches the expected Keycloak realm URL.
  4. Audience Check: (Optional) Verifies that the aud claim matches the expected client ID.

Implementation in Spring Boot​

LibreApps Desktop uses the spring-boot-starter-oauth2-resource-server to handle JWT validation automatically.

@Configuration
@EnableWebSecurity
public class SecurityConfig extends WebSecurityConfigurerAdapter {
    @Override
    protected void configure(HttpSecurity http) throws Exception {
        http
            .authorizeRequests()
            .anyRequest().authenticated()
            .and()
            .oauth2ResourceServer()
            .jwt();
    }
}

Best Practices​

  • ✅ Do this: Use a library like Spring Security to handle JWT validation; don't implement it manually.
  • ✅ Do this: Regularly rotate your Keycloak signing keys.
  • ❌ Don't do this: Trust any information in the JWT payload without first verifying the signature.