Docs

Docs

Securing Spring Boot Applications

Enable and configure security in a Vaadin Flow application using built-in security helpers with Spring Boot.

Vaadin Flow is fully compatible with the most-popular security solutions in the Java ecosystem, including but not limited to Spring Security, Java Authentication and Authorization Service (JAAS), and Apache Shiro.

Although you can choose the security framework you want, Vaadin Flow comes with built-in security helpers that are most conveniently implemented with Spring Security. Using these built-in helpers with Spring Security makes it easier, faster, and safer to secure your Vaadin applications compared to using the Spring Security framework directly — or with any other security framework.

This page focuses on enabling security using the built-in helpers in combination with Spring Boot and Spring Security. For instructions on using the built-in helpers in non-Spring projects, see the Securing Plain Java Applications documentation page.

Introduction

In a Spring Boot application, Vaadin Flow’s built-in security helpers enable a view-based access control mechanism with minimum Spring Security configuration. This mechanism allows you to secure view flexibly in Vaadin Flow applications, based on different access level annotations. Specifically, the view-based access control mechanism uses the @AnonymousAllowed, @PermitAll, @RolesAllowed, and @DenyAll annotations on view classes to define the access control rules.

To enable the mechanism in a Vaadin Flow Spring Boot application without any security, be sure to add the following to your project:

  • Login view;

  • Spring Security dependencies;

  • Log-out capability;

  • Security configuration class that extends VaadinWebSecurity; and

  • One of these annotations on each view class: @AnonymousAllowed, @PermitAll, or @RolesAllowed.

A complete example project, including the source code from this document, is available at github.com/vaadin/flow-crm-tutorial.

Log-in View

A log-in view is a basic requirement of many authentication and authorization mechanisms. It allows you to redirect anonymous users to that page, before allowing them to view any protected resources. The log-in view should always be accessible by anonymous users.

@Route("login")
@PageTitle("Login")
@AnonymousAllowed
public class LoginView extends VerticalLayout implements BeforeEnterObserver {

    private LoginForm login = new LoginForm();

    public LoginView() {
        addClassName("login-view");
        setSizeFull();

        setJustifyContentMode(JustifyContentMode.CENTER);
        setAlignItems(Alignment.CENTER);

        login.setAction("login");

        add(new H1("Test Application"), login);
    }

    @Override
    public void beforeEnter(BeforeEnterEvent beforeEnterEvent) {
        if(beforeEnterEvent.getLocation()
            .getQueryParameters()
            .getParameters()
            .containsKey("error")) {
            login.setError(true);
        }
    }
}

This example uses Vaadin’s Login Form component for brevity in this implementation. However, there’s no requirement to use it. Use whatever log-in view you prefer.

Spring Security Dependencies

To enable Spring Security, certain dependencies should be added to the project. Since the examples on this page are based on Spring Boot, you would add the following dependency:

<dependencies>
    <!-- other dependencies -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-security</artifactId>
    </dependency>
    <!-- other dependencies -->
</dependencies>

Log-Out Capability

To initiate logging out of a web applications, you would typically provide a log-out button. Here is a basic implementation of a log-out button shown on the header of the main layout:

public class MainLayout extends AppLayout {

    private SecurityService securityService;

    public MainLayout(@Autowired SecurityService securityService) {
        this.securityService = securityService;

        H1 logo = new H1("Vaadin CRM");
        logo.addClassName("logo");
        HorizontalLayout header;
        if (securityService.getAuthenticatedUser() != null) {
            Button logout = new Button("Logout", click ->
                    securityService.logout());
            header = new HorizontalLayout(logo, logout);
        } else {
            header = new HorizontalLayout(logo);
        }

        // Other page components omitted.

        addToNavbar(header);
    }
}

The method of getting the authenticated user and logging them out may vary from one application to another. Here’s a basic example of this with the Spring Security API:

@Component
public class SecurityService {

    private static final String LOGOUT_SUCCESS_URL = "/";

    public UserDetails getAuthenticatedUser() {
        SecurityContext context = SecurityContextHolder.getContext();
        Object principal = context.getAuthentication().getPrincipal();
        if (principal instanceof UserDetails) {
            return (UserDetails) context.getAuthentication().getPrincipal();
        }
        // Anonymous or no authentication.
        return null;
    }

    public void logout() {
        UI.getCurrent().getPage().setLocation(LOGOUT_SUCCESS_URL);
        SecurityContextLogoutHandler logoutHandler = new SecurityContextLogoutHandler();
        logoutHandler.logout(
                VaadinServletRequest.getCurrent().getHttpServletRequest(), null,
                null);
    }
}

Security Utilities

To access authenticated user details and to simplify the handling of logout, Vaadin provides an AuthenticationContext component — which is strictly integrated with Spring Security — that can be injected into views and services.

The AuthenticationContext by design does not implement java.io.Serializable. Vaadin view fields referencing this object must be defined transient. The class exposes the following utility methods:

  • isAuthenticated() checks if a user is currently logged in. The Spring Anonymous user is considered not authenticated.

  • getAuthenticatedUser(Class<U> userType) gets user details. If userType doesn’t match the actual user implementation, the method throws a ClassCastException.

  • getGrantedRoles() gets the roles assigned to the user, stripping the role prefix (e.g. ROLE_USER is returned as USER).

  • hasRole(String role), hasAnyRole(String…​ roles), hasAllRoles(String…​ roles) check if the user is assigned to given roles. Roles should be provided without role prefix.

  • getGrantedAuthorities() gets the authorities that have been granted to the user.

  • hasAuthority(String authority), hasAnyAuthority(String…​ authorities), hasAllAuthorities(String…​ authorities) check if the user has been granted certain authorities.

  • logout initiates the Spring Security logout process and redirects the user to the configured logout URL.

Here’s an implementation of a log-out button shown on the header of the main layout that uses the AuthenticationContext component:

public class MainLayout extends AppLayout {

    private final transient AuthenticationContext authContext;

    public MainLayout(AuthenticationContext authContext) {
        this.authContext = authContext;

        H1 logo = new H1("Vaadin CRM");
        logo.addClassName("logo");
        HorizontalLayout
        header =
        authContext.getAuthenticatedUser(UserDetails.class)
                .map(user -> {
                    Button logout = new Button("Logout", click ->
                            this.authContext.logout());
                    Span loggedUser = new Span("Welcome " + user.getUsername());
                    return new HorizontalLayout(logo, loggedUser, logout);
                }).orElseGet(() -> new HorizontalLayout(logo));

        // Other page components omitted.

        addToNavbar(header);
    }
}

Security Configuration Class

The next step is to have a Spring Security class that extends VaadinWebSecurity. There’s no convention for naming this class, so here it’s named SecurityConfiguration. However, take care with Spring Security annotations.

This is a minimal implementation of such a class:

@EnableWebSecurity 1
@Configuration
public class SecurityConfiguration
                extends VaadinWebSecurity { 2

    @Override
    protected void configure(HttpSecurity http) throws Exception {
        // Delegating the responsibility of general configurations
        // of http security to the super class. It's configuring
        // the followings: Vaadin's CSRF protection by ignoring
        // framework's internal requests, default request cache,
        // ignoring public views annotated with @AnonymousAllowed,
        // restricting access to other views/endpoints, and enabling
        // NavigationAccessControl authorization.
        // You can add any possible extra configurations of your own
        // here (the following is just an example):

        // http.rememberMe().alwaysRemember(false);

        // Configure your static resources with public access before calling
        // super.configure(HttpSecurity) as it adds final anyRequest matcher
        http.authorizeHttpRequests(auth -> auth.requestMatchers(new AntPathRequestMatcher("/public/**"))
            .permitAll());

        super.configure(http); 3

        // This is important to register your login view to the
        // navigation access control mechanism:
        setLoginView(http, LoginView.class); 4
    }

    @Override
    public void configure(WebSecurity web) throws Exception {
        // Customize your WebSecurity configuration.
        super.configure(web);
    }

    /**
     * Demo UserDetailsManager which only provides two hardcoded
     * in memory users and their roles.
     * NOTE: This shouldn't be used in real world applications.
     */
    @Bean
    public UserDetailsManager userDetailsService() {
        UserDetails user =
                User.withUsername("user")
                        .password("{noop}user")
                        .roles("USER")
                        .build();
        UserDetails admin =
                User.withUsername("admin")
                        .password("{noop}admin")
                        .roles("ADMIN")
                        .build();
        return new InMemoryUserDetailsManager(user, admin);
    }
}

Notice the including of @EnableWebSecurity and @Configuration annotations on top of the above class. As their names imply, they instruct Spring to enable its security features.

VaadinWebSecurity is a helper class that configures the common Vaadin-related Spring Security settings. By extending it, the view-based access control mechanism is enabled automatically, and no further configuration is needed.

The default implementation of the configure methods handles all of the Vaadin-related configuration. For example, it ignores static resources, or enables CSRF checking, while ignoring unnecessary checking for Vaadin internal requests.

The log-in view can be configured via the provided setLoginView() method.

Warning
Never Use Hard-Coded Credentials in Production
The implementation of the userDetailsService() method is just an in-memory implementation for the sake of brevity in this documentation. In a normal application, you can change the Spring Security configuration to use an authentication provider for Lightweight Directory Access Protocol (LDAP), JAAS, and other real-world sources. See Spring Security authentication providers to read more about them.

The most important configuration in the previous example is the call to setLoginView(http, LoginView.class) inside the first configure method. This is how the view-based access control mechanism knows where to redirect users when they try to navigate to a protected view.

The log-in view should always be accessible by anonymous users, so it should have the @AnonymousAllowed annotation. This is especially important when using the variant of the setLoginView method where you provide the route path — although this signature is meant to be used with Hilla views, not with Flow views.

For additional information about navigation access control, consult the related documentation.

Note
Component-Based Security Configuration
Spring Security 5.7.0 deprecates the WebSecurityConfigurerAdapter. Migrate to a component-based security configuration.

VaadinWebSecurityConfigurerAdapter is still available for Vaadin 23.2 users, although it’s recommended to use component-based security configuration as in SecurityConfiguration example here. Read more about updating from WebSecurityConfigurerAdapter to component-based security configuration.

Once the LoginView is ready, and you’ve set it as the log-in view in the security configuration, you’re ready to move ahead and see how the security annotations work on the views.

Annotating View Classes

Before providing some usage examples of access annotations, it would be good to have a closer look at the annotations and their meaning when applied to a view:

  • @AnonymousAllowed permits anyone to navigate to a view without any authentication or authorization.

  • @PermitAll allows any authenticated user to navigate to a view.

  • @RolesAllowed grants access to users having the roles specified in the annotation value.

  • @DenyAll disallows everyone from navigating to a view. This is the default; if a view isn’t annotated, the @DenyAll logic is applied.

When the security configuration class extends from VaadinWebSecurity, Vaadin’s SpringSecurityAutoConfiguration comes into play and enables the navigation access control mechanism with view-based security. Therefore, none of the views are accessible until one of these annotations is applied to them — except @DenyAll.

Below is an example using @AnonymousAllowed to enable all users to navigate to this view:

@Route(value = "", layout = MainView.class)
@PageTitle("Public View")
@AnonymousAllowed
public class PublicView extends VerticalLayout {
    // ...
}

This next example is using @PermitAll to allow only authenticated users — with any role — to navigate to this view:

@Route(value = "private", layout = MainView.class)
@PageTitle("Private View")
@PermitAll
public class PrivateView extends VerticalLayout {
    // ...
}

This example is using @RolesAllowed to enable only the users with ADMIN role to navigate to this view:

@Route(value = "admin", layout = MainView.class)
@PageTitle("Admin View")
@RolesAllowed("ADMIN") // <- Should match one of the user's roles (case-sensitive)
public class AdminView extends VerticalLayout {
    // ...
}

Annotation Inheritance & Overrides

As shown in the example here, the security annotations are inherited from the closest parent class that has them. Annotating a child class overrides any inherited annotations. Interfaces aren’t checked for annotations, only classes.

@RolesAllowed("ADMIN")
public abstract class AbstractAdminView extends VerticalLayout {
    // ...
}

@Route(value = "user-listing", layout = MainView.class)
@PageTitle("User Listing")
public class UserListingView extends AbstractAdminView {
    // ...
}

By design, the annotations aren’t read from parent layouts or parent views. This would make it unnecessarily complex to determine which security level should be applied. If multiple annotations are specified on a single view class, the following rules are applied:

  • DenyAll overrides other annotations;

  • AnonymousAllowed overrides RolesAllowed, as well as PermitAll; and

  • RolesAllowed overrides PermitAll.

Specifying more than one of the above access annotations on a view class isn’t recommended. Besides the fact that there’s probably no logical reason to do so, it would be confusing.

Authenticated User Information

To access the authenticated user’s information (e.g., name, email and roles), Vaadin Flow provides the AuthenticationContext class that can be used to retrieve this information. AuthenticationContext is a Spring bean that can be injected as a view constructor argument. And AuthenticationContext can be useful for rendering the UI differently based on the user’s roles.

The following example shows how to use AuthenticationContext to retrieve the authenticated user’s information and render a button only if the user has the ADMIN role:

import com.vaadin.flow.component.button.Button;
import com.vaadin.flow.component.html.H2;;
import com.vaadin.flow.component.orderedlayout.VerticalLayout;
import com.vaadin.flow.router.Route;
import com.vaadin.flow.server.auth.AnonymousAllowed;
import com.vaadin.flow.spring.security.AuthenticationContext;
import org.springframework.security.core.userdetails.UserDetails;

@Route(value = "my-view")
@AnonymousAllowed
public class MyView extends VerticalLayout {

    public MyView(AuthenticationContext authContext) {

        add(new H2("Everyone can see this"));

        // Ensure that the class used by getAuthenticatedUser() matches the object type created
        // by the authentication providers used in Spring Security.
        authContext.getAuthenticatedUser(UserDetails.class).ifPresent(user -> {
            boolean isAdmin = user.getAuthorities().stream()
                    .anyMatch(grantedAuthority -> "ROLE_ADMIN".equals(grantedAuthority.getAuthority()));
            if (isAdmin) {
                add(new Button("Admin button"));
            } else {
                add(new H2("You are not an admin"));
            }
        });
    }
}

Error Messages for Unauthorized Views

If the user is already authenticated and tries to navigate to a view for which they don’t have permission, an error message is displayed. The message depends on the application mode.

In development mode, Vaadin shows the RouteAccessDeniedError view, which shows an Access Denied message with a list of available routes. In production mode, Vaadin shows the RouteAccessDeniedError view, which shows by default a message that reads, Could Not Navigate to 'RequestedRouteName'. As a security precaution, the message won’t say whether the navigation target exists.

The RouteAccessDeniedError is not by default a view, but a reroute to the RouteNotFoundError view for better backwards compatibility.

Custom Error Messages for Unauthorized Views

Vaadin shows by default the RouteAccessDeniedError view for unauthorized views. This can be customized in the following ways:

  • Providing custom implementation by overriding RouteAccessDeniedError class;

  • Providing custom implementation by implementing HasErrorParameter<AccessDeniedException> interface; and

  • Rerouting to a different error type with @AccessDeniedErrorRouter annotation.

The following is one example of this approach, using a custom error by overriding a class:

public class CustomAccessDeniedError extends RouteAccessDeniedError {
    @Override
    public int setErrorParameter(BeforeEnterEvent event,
            ErrorParameter<AccessDeniedException> parameter) {
        getElement().setText("Nothing to see here, please move on");
        return HttpStatusCode.UNAUTHORIZED.getCode();
    }
}

This next example provides a custom error by implementing an interface:

@Tag(Tag.DIV)
@PermitAll
public static class CustomAccessDeniedError extends Component
        implements HasErrorParameter<AccessDeniedException> {
    @Override
    public int setErrorParameter(BeforeEnterEvent event,
            ErrorParameter<AccessDeniedException> parameter) {
        getElement().setText("Access denied.");
        return HttpStatusCode.UNAUTHORIZED.getCode();
    }
}

HasErrorParameter error view needs an access control annotation, so that Vaadin allows navigation to it. The example above uses @PermitAll, but @RolesAllowed can also be used. @AnonymousAllowed isn’t recommended, as it exposes information about access restrictions to the anonymous users.

If you want to reroute to a different error type, you would do something like the following example. It reroutes unauthorized administrative views to the RouteNotFoundError view, which is the default view for NotFoundException type.

@Route(value = "admin", layout = MainView.class)
@PageTitle("Admin View")
@RolesAllowed("ADMIN")
@AccessDeniedErrorRouter(rerouteToError = NotFoundException.class)
public class AdminView extends VerticalLayout {
    // ...
}

AccessDeniedErrorRouter annotation redirects by default to AccessDeniedException, if not changed. Annotation is to be used together with @Route, or if present, together with access annotation: @AnonymousAllowed, @PermitAll, @RolesAllowed, or @DenyAll.

The Navigation Access Control feature allows mixing any of the view access annotations with Spring’s URL-pattern-based HTTP security — which possibly exists in older Vaadin Spring Boot applications. However, it may result in extra configuration, since the security annotation on the views and the URL-pattern-based rules must be consistent.

URL-based security can be enabled by activating the RoutePathAccessChecker component provided by Flow. To activate it, you need to define a NavigationAccessControlConfigurer bean in your Spring configuration, creating a new instance of that class and calling the withRoutePathAccessChecker() method.

@Bean
NavigationAccessControlConfigurer navigationAccessControlConfigurer() {
    return new NavigationAccessControlConfigurer()
            .withAnnotatedViewAccessChecker() 1
            .withRoutePathAccessChecker();    2
}

  1. Activation of annotation base view access checker.

  2. Activation of Spring URL-pattern-based checker.

Important
 If you add the bean definition method in a configuration class extending VaadinWebSecurity, the method must be declared static, to prevent bootstrap errors because of circular dependencies in bean definitions.

You can also activate only the RoutePathAccessChecker, if you prefer to centralize the authorization configuration by only using the Spring Security URL-pattern-based security feature.

@Bean
NavigationAccessControlConfigurer navigationAccessControlConfigurer() {
    return new NavigationAccessControlConfigurer()
            .withRoutePathAccessChecker();
}

For more information about navigation access control consult the related documentation.

Vaadin strongly recommends not to mix Spring’s URL-pattern-based HTTP security and this view-based access control mechanism targeting the same views. Doing so might cause unwanted access configurations, and would be an unnecessary complication in the authorization of views.

4C8D835D-4E6E-4D81-BEA1-A865FEB17BAD