How to Fix H2 Console Not Showing in Browser With Spring Boot

1. Overview

The H2 console serves as a Graphical User Interface (GUI) client for the H2 database, allowing us to query the database through a web page. However, we may encounter an issue where the console displays a blank page, particularly when a Spring Security dependency is present in our classpath.

In this tutorial, we’ll simulate this issue and learn how to resolve it by configuring the X-Frame-Options header in Spring Security.

2. Understanding and Simulating the Error

The H2 database helps with fast prototyping as it shares the attributes of most production-grade SQL servers. However, when using the H2 database with Spring Security, access to the H2 console in the browser is automatically restricted.

This occurs because the H2 console is rendered within an <iframe>, which Spring Security disables by default to prevent cyberattacks such as clickjacking.

In clickjacking, a malicious website embeds or overlays a target website under clickable elements such as frames or buttons, deceiving users into interacting with malicious content. Secure websites implement configurations to prevent content from being rendered in frames.

Let’s simulate this error by setting up a simple Spring Boot project with a Spring Security dependency.

2.1. Maven Dependencies

First, let’s add the spring-boot-starter-web and spring-boot-starter-security dependencies to the pom.xml file:

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
    <version>3.4.4</version>
</dependency>

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-security</artifactId>
    <version>3.4.4</version>
</dependency>

The spring-boot-starter-web dependency, with an embedded server, enables us to create a web application.

Also, the spring-boot-starter-security dependency helps to authenticate and authorize endpoints in a typical Spring Boot application. When no custom user details are defined, it generates login credentials by default at application startup:

• Username – user
• Password – A random value printed in the console

Next, let’s add the H2 database dependency to pom.xml:

<dependency>
    <groupId>com.h2database</groupId>
    <artifactId>h2</artifactId>
    <version>2.3.232</version>
</dependency>

The H2 dependency provides an embedded database ideal for rapid prototyping.

2.2. Database Configuration

Moving on, let’s configure the database connection in the application.properties file:

spring.datasource.url=jdbc:h2:mem:testdb
spring.datasource.driverClassName=org.h2.Driver
spring.datasource.username=sa
spring.datasource.password=password
spring.jpa.database-platform=org.hibernate.dialect.H2Dialect
spring.h2.console.enabled=true

Although Spring Boot automatically configures the database, we define our configuration to override the default for greater control.

By default, the spring.h2.console.enable property is false. We set it to true to enable the H2 web console.

2.3. Viewing the Console

With Spring Security enabled, all endpoints, including “/h2-console/**“, require authentication by default. However, let’s define a class named SecurityConfig for custom configuration:

@Configuration
class SecurityConfig {
    @Bean
    SecurityFilterChain configure(HttpSecurity http) throws Exception {
        http.csrf(csrf -> csrf.ignoringRequestMatchers("/h2-console/**"))
          .authorizeHttpRequests(auth -> auth
            .anyRequest().authenticated())
          .formLogin(withDefaults());

        return http.build();
    }
}

In the configuration above, we maintain the default authentication and form login behavior but disable CSRF protection for “/h2-console/**” to avoid an HTTP 403 error.

Next, let’s execute our application and check http://localhost:8080/h2-console. It redirects us to Spring Security’s login page, where we use the default generated credentials.

After logging in, we’re redirected to the H2 console’s database login page:

However, when we try to log in, we get a blank page:

This error is caused because the H2 console is rendered using the <iframe> tag, which Spring Security blocks by default through the X-Frame-Options header.

3. Fixing the Error by Disabling X-Frame-Options

The page fails to load the important component after signing in to the console. We can resolve this by either disabling the X-Frame-Options header or allowing frames only from the same origin.

3.1. Globally Disabling Frame Protection With frameOptions()

If the application isn’t intended for production use, we can disable X-Frame-Options using frameOptions():

@Bean
SecurityFilterChain configure(HttpSecurity http) throws Exception {
    http.csrf(csrf -> csrf.ignoringRequestMatchers("/h2-console/**"))
      .headers(headers -> headers.frameOptions(HeadersConfigurer.FrameOptionsConfig::disable))
      .authorizeHttpRequests(auth -> auth
        .anyRequest().authenticated())
      .formLogin(withDefaults());

    return http.build();
}

Here, we use the headers() method on the http instance to allow frames to load.

Let’s see the page now:

This method solves the problem, but it disables X-Frame-Options at a global level.

3.2. Configuring Frame Options for Same-Origin Access

While the previous solution works, disabling the X-Frame-Options header globally isn’t ideal because it exposes the application to a potential clickjacking attack. Instead, we can allow frames only from the same origin:

@Bean
SecurityFilterChain configure(HttpSecurity http) throws Exception {
    http.csrf(csrf -> csrf.ignoringRequestMatchers("/h2-console/**"))
      .headers(headers -> headers.frameOptions(HeadersConfigurer.FrameOptionsConfig::sameOrigin))
      .authorizeHttpRequests(auth -> auth
        .anyRequest().authenticated())
      .formLogin(withDefaults());

    return http.build();
}

Here, we change the frameOptions() to permit only the same-origin application.

Adjusting security configurations like this, to allow framing only within the same origin, reduces the risk of clickjacking.

4. Conclusion

In this article, we simulated the blank page error when accessing the H2 console in a browser and resolved it by configuring the frameOptions() setting in Spring Security. Also, we saw how to disable the X-Frame-Options globally for development and restrict it to the same origin for better security.