Authentication with Spring Security

Configuring authentication with Spring Security.

Dependencies
Server Configuration
Login View
Protect Hilla Views
Logout
Implement Stateful Authentication
Appendix: Production Data Sources

Authentication may be configured to use Spring Security. Since the downloaded application is a Spring Boot project, the easiest way to enable authentication is by adding Spring Security.

Dependencies

Using Spring Security requires some dependencies. Add the following to your project Maven file:

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

After doing this, the application is protected with a default Spring login view. By default, it has a single user (i.e., 'user') and a random password. When you add logging.level.org.springframework.security = DEBUG to the application.properties file, the username and password are shown in the console when the application starts.

Server Configuration

To implement your own security configuration, create a new configuration class that extends the VaadinWebSecurity class. Then annotate it to enable security.

VaadinWebSecurity is a helper which provides default bean implementations for SecurityFilterChain and WebSecurityCustomizer. It takes care of the basic configuration for requests, so that you can concentrate on your application-specific configuration.

@EnableWebSecurity
@Configuration
public class SecurityConfig extends VaadinWebSecurity {

  private final RouteUtil routeUtil;

  public SecurityConfig(RouteUtil routeUtil) {
    this.routeUtil = routeUtil;
  }

  @Override
  protected void configure(HttpSecurity http) {
    // Set default security policy that permits Hilla internal requests and
    // denies all other
    http.authorizeHttpRequests(registry -> registry.requestMatchers(
            routeUtil::isRouteAllowed).permitAll());
    super.configure(http);
    // use a custom login view and redirect to root on logout
    setLoginView(http, "/login", "/");
  }

  @Bean
  public UserDetailsManager userDetailsService() {
    // Configure users and roles in memory
    return new InMemoryUserDetailsManager(
      // the {noop} prefix tells Spring that the password is not encoded
      User.withUsername("user").password("{noop}user").roles("USER").build(),
      User.withUsername("admin").password("{noop}admin").roles("ADMIN", "USER").build()
    );
  }
}

Warning

Never Hard-Coded Credentials

You should never hard-code credentials in an application. The Security documentation has examples of setting up LDAP or SQL-based user management.

Public Views & Resources

Public views need to be added to the configuration before calling super.configure(). Here’s an example of this:

  @Override
  protected void configure(HttpSecurity http) {
    http.authorizeHttpRequests(registry -> {
        registry.requestMatchers(new AntPathRequestMatcher("/public-view")).permitAll(); // custom matcher
    });
    super.configure(http);
  }

Public resources can be added by overriding configure(WebSecurity web) like so:

@Override
  public void configure(WebSecurity web) throws Exception {
      super.configure(web);
      web.ignoring().requestMatchers(new AntPathRequestMatcher("/images/**")); 
  }

Use the <vaadin-login-overlay> component to create the following login view, so that the autocomplete and password features of the browser are used.

import { html, LitElement } from 'lit';
import { customElement, state } from 'lit/decorators.js';
import type { LoginResult } from '@vaadin/hilla-frontend';
import { login } from './auth';
import type { AfterEnterObserver, RouterLocation } from '@vaadin/router';
import '@vaadin/login';

@customElement('login-view')
export class LoginView extends LitElement implements AfterEnterObserver {
  @state()
  private error = false;

  // the url to redirect to after a successful login
  private returnUrl?: string;

  render() {
    return html`
      <vaadin-login-overlay opened .error="${this.error}" @login="${this.login}">
      </vaadin-login-overlay>
    `;
  }

  async login(event: CustomEvent): Promise<LoginResult> {
    this.error = false;
    // use the login helper method from auth.ts, which in turn uses
    // Vaadin provided login helper method to obtain the LoginResult
    const result = await login(event.detail.username, event.detail.password, {
      navigate: (toPath: string) => {
        // Consider absolute path to be within the application context.
        const serverUrl = toPath.startsWith('/') ? new URL(`.${toPath}`, document.baseURI) : toPath;

        // If a login redirect was initiated by the client router, this.returnUrl contains the original destination.
        // Otherwise, use the URL provided by the server.
        // As we do not know if the target is a resource or a Hilla view or a Flow view, we cannot just use Router.go
        window.location.replace(this.returnUrl ?? serverUrl);
      },
    });
    this.error = result.error;

    return result;
  }

  onAfterEnter(location: RouterLocation) {
    this.returnUrl = location.redirectFrom;
  }
}

The authentication helper methods in the code examples are grouped in a separate TypeScript file, as shown in the following. It utilizes a Hilla login() helper method for authentication based on Spring Security.

// Uses the Vaadin provided login an logout helper methods
import {
  login as loginImpl,
  type LoginOptions,
  type LoginResult,
  logout as logoutImpl,
  type LogoutOptions,
} from '@vaadin/hilla-frontend';
import { UserInfoService } from 'Frontend/generated/endpoints';
import type UserInfo from 'Frontend/generated/com/vaadin/demo/fusion/security/authentication/UserInfo';

interface Authentication {
  user: UserInfo;
  timestamp: number;
}

let authentication: Authentication | undefined;

const AUTHENTICATION_KEY = 'authentication';
const THIRTY_DAYS_MS = 30 * 24 * 60 * 60 * 1000;
/**
 * Forces the session to expire and removes user information stored in
 * `localStorage`.
 */
export function setSessionExpired() {
  authentication = undefined;

  // Delete the authentication from the local storage
  localStorage.removeItem(AUTHENTICATION_KEY);
}


// Get authentication from local storage
const storedAuthenticationJson = localStorage.getItem(AUTHENTICATION_KEY);
if (storedAuthenticationJson !== null) {
  const storedAuthentication = JSON.parse(storedAuthenticationJson) as Authentication;
  // Check that the stored timestamp is not older than 30 days
  const hasRecentAuthenticationTimestamp =
    new Date().getTime() - storedAuthentication.timestamp < THIRTY_DAYS_MS;
  if (hasRecentAuthenticationTimestamp) {
    // Use loaded authentication
    authentication = storedAuthentication;
  } else {
    // Delete expired stored authentication
    setSessionExpired();
  }
}

/**
 * Login wrapper method that retrieves user information.
 *
 * Uses `localStorage` for offline support.
 */
export async function login(
  username: string,
  password: string,
  options: LoginOptions = {}
): Promise<LoginResult> {
  return await loginImpl(username, password, {
    ...options,
    async onSuccess() {
      // Get user info from endpoint
      const user = await UserInfoService.getUserInfo();
      authentication = {
        user,
        timestamp: new Date().getTime(),
      };

      // Save the authentication to local storage
      localStorage.setItem(AUTHENTICATION_KEY, JSON.stringify(authentication));
    },
  });
}

/**
 * Login wrapper method that retrieves user information.
 *
 * Uses `localStorage` for offline support.
 */
export async function logout(options: LogoutOptions = {}) {
  return await logoutImpl({
    ...options,
    onSuccess() {
      setSessionExpired();
    },
  });
}

/**
 * Checks if the user is logged in.
 */
export function isLoggedIn() {
  return !!authentication;
}

/**
 * Checks if the user has the role.
 */
export function isUserInRole(role: string) {
  if (!authentication) {
    return false;
  }

  return authentication.user.authorities.includes(`ROLE_${role}`);
}

After the login view is defined, you should define a route for it in the routes.ts file. Don’t forget to import the login-view component, otherwise the login view won’t be visible.

import './login-view';
// ...
const routes = [
  {
    path: '/login',
    component: 'login-view'
  },
  // more routes
]

Update the SecurityConfig to use the setLogin() helper, which sets up everything needed for a Hilla-based login view:

@Override
  protected void configure(HttpSecurity http) throws Exception {
    super.configure(http);
    setLoginView(http, "/login");
  }

Note, the path for the login view in routes.ts must match the one defined in SecurityConfig.

Protect Hilla Views

Access control for Hilla views cannot be based on URL filtering. The Hilla view templates are always in the bundle and can be accessed by anyone. Therefore, it’s important not to store any sensitive data in the view template.

The data should go to endpoints, and the endpoints should be protected instead. Read Configuring Security on protecting endpoints to learn more about this.

You can still achieve a better user experience by redirecting unauthenticated requests to the login view with the route action.

Below is an example using the route action:

import { Commands, Context, Route } from '@vaadin/router';
import './my-view';
// ...
const routes = [
  // ...
  {
    path: '/my-view',
    action: (_: Context, commands: Commands) => {
      if (!isLoggedIn()) {
        return commands.redirect('/login');
      }
      return undefined;
    },
    component: 'my-view'
  }
  // ...
]

You can also add the route action to the parent layout, so that all child views are protected. In this case, the login component should be outside of the main layout — that is, not a child of the main layout in the route configuration.

import { Commands, Context, Route } from '@vaadin/router';
import './login-view';
// ...
const routes = [
  // ...
  {
    path: '/login',
    component: 'login-view'
  },
  {
    path: '/',
    action: (_: Context, commands: Commands) => {
      if (!isLoggedIn()) {
        return commands.redirect('/login');
      }
      return undefined;
    },
    component: 'main-layout',
    children: [
      // ...
    ]
  }
  // ...
]

The isLoggedIn() method in these code examples uses a lastLoginTimestamp variable stored in the localStorage to check if the user is logged in. The lastLoginTimestamp variable needs to be reset when logging out.

Using localStorage permits navigation to sub-views without having to check authentication from the backend on every navigation. In this way, the authentication check can work offline.

Logout

To handle logging out, you can use the logout() helper defined earlier in auth.ts. You typically would use a button to handle logout, instead of navigation and a route. This is to avoid timing problems between rendering views and logging out. For example, you can do the following:

<vaadin-button @click="${() => logout()}">Logout</vaadin-button>

Configuration Helper Alternatives

VaadinWebSecurity.configure(http) configures HTTP security to bypass framework internal resources. If you prefer to make your own configuration, instead of using the helper, the matcher for these resources can be retrieved with VaadinWebSecurity.getDefaultHttpSecurityPermitMatcher().

For example, VaadinWebSecurity.configure(http) requires all requests to be authenticated, except the Hilla internal ones. If you want to allow public access to certain views, you can configure it as follows:

public static void configure(HttpSecurity http) throws Exception {
    http.authorizeRequests()
        .requestMatchers(
          VaadinWebSecurity.getDefaultHttpSecurityPermitMatcher()
        ).permitAll()
        .requestMatchers("/public-view").permitAll() // custom matcher
        .anyRequest().authenticated();
        ...
}

Similarly, the matcher for static resources to be ignored is available as VaadinWebSecurity.getDefaultWebSecurityIgnoreMatcher():

public static void configure(WebSecurity web) throws Exception {
    web.ignoring()
       .requestMatchers(
         VaadinWebSecurity.getDefaultWebSecurityIgnoreMatcher())
       .requestMatchers(antMatcher("static/**")) // custom matcher
       ...
}

Implement Stateful Authentication

Vaadin applications that have both Hilla and Flow views, can be configured to use stateful authentication. This requires some basic steps for Hilla and steps for Flow. An example project that demonstrates the stateful authentication for the hybrid case can be found in GitHub.

For this example, you’d add Spring Security dependency and then set up Security Configuration.

The browser page needs to be reloaded after login and, if you want to exclude the LoginView from the automatically generated menu, you need to set:

export const config: ViewConfig = {
    menu: { exclude: true}
}

The next step is to protect the views with login and roles. Add the annotations to the server-side views, as described in Annotating View Classes. Add the ViewConfig object to the client-side views, as shown below:

export const config: ViewConfig = {
    loginRequired: true,
    rolesAllowed: ['ROLE_USER'],
};

Use createMenuItems function to create a main layout, that filters out protected views and shows the only allowed views for an authenticated user.

import { createMenuItems } from '@vaadin/hilla-file-router/runtime.js';
import { AppLayout, SideNav } from '@vaadin/react-components';
import { Outlet, useLocation, useNavigate } from 'react-router-dom';

// inside layout component:
const navigate = useNavigate();
const location = useLocation();
// ...
<AppLayout>
    // ...
    // SideNav Vaadin component inside <AppLayout>
    <SideNav
        onNavigate={({ path }) => navigate(path!)}
        location={location}>
        {
            createMenuItems().map(({ to, title }) => (
                <SideNavItem path={to} key={to}>{title}</SideNavItem>
            ))
        }
    </SideNav>
</AppLayout>

As an alternative, add the menu items manually and specify the access options:

import { AppLayout } from '@vaadin/react-components/AppLayout.js';
import { Button } from '@vaadin/react-components/Button.js';
import { DrawerToggle } from '@vaadin/react-components/DrawerToggle.js';
import { Suspense } from 'react';
import { NavLink, Outlet } from 'react-router-dom';
import { useRouteMetadata } from './routing';
import { useAuth } from './auth';

const navLinkClasses = ({ isActive }: any) =>
  `block rounded-m p-s ${isActive ? 'bg-primary-10 text-primary' : 'text-body'}`;

export default function MainLayout() {
  const currentTitle = useRouteMetadata()?.title ?? 'My App';
  const { state, logout } = useAuth();

  return (
    <AppLayout primarySection="drawer">
      <div slot="drawer" className="flex flex-col justify-between h-full p-m">
        <header className="flex flex-col gap-m">
          <h1 className="text-l m-0">My App</h1>
          <nav>
            {state.user ? (
              <NavLink className={navLinkClasses} to="/">
                Hello World
              </NavLink>
            ) : null}
            {state.user ? (
              <NavLink className={navLinkClasses} to="/about">
                About
              </NavLink>
            ) : null}
          </nav>
        </header>
        <footer className="flex flex-col gap-s">
          {state.user ? (
            <>
              <div className="flex items-center gap-s">{state.user.name}</div>
              <Button onClick={async () => logout()}>Sign out</Button>
            </>
          ) : (
            <a href="/login">Sign in</a>
          )}
        </footer>
      </div>

      <DrawerToggle slot="navbar" aria-label="Menu toggle"></DrawerToggle>
      <h2 slot="navbar" className="text-l m-0">
        {currentTitle}
      </h2>

      <Suspense>
        <Outlet />
      </Suspense>
    </AppLayout>
  );
}

Then you can add a custom configuration for routes — this is optional. Routes configuration is usually present in routes.tsx file, which is generated by Vaadin. This should be enough for common cases:

import { RouterConfigurationBuilder } from '@vaadin/hilla-file-router/runtime.js';
import Flow from 'Frontend/generated/flow/Flow';
import fileRoutes from 'Frontend/generated/file-routes.js';

export const { router, routes } = new RouterConfigurationBuilder()
    .withFileRoutes(fileRoutes)
    .withFallback(Flow)
    .protect()
    .build();

Note that the client-side views are protected by default with a protect() function. If a custom routing is desired, the generated file Frontend/generated/routes.tsx should be copied to Frontend/routes.tsx and modified.

For example, you may want to change the login URL:

new RouterConfigurationBuilder().protect('/custom-login-url')

Add specific React route objects with withReactRoutes function:

new RouterConfigurationBuilder().withReactRoutes(
    [
      {
        element: <MainLayout />,
        handle: { title: 'Main' },
        children: [
            { path: '/hilla', element: <HillaView />, handle: { title: 'Hilla' } }
        ],
      },
      { path: '/login', element: <Login />, handle: { title: 'Login' } }
    ]
)

Disable server-side views or add a fallback component with a withFallback function. For example, 404 page that will be shown if no client-side view is found for a given URL.

    new RouterConfigurationBuilder().withFallback(PageNotFoundReactComponent)

Appendix: Production Data Sources

The example given here of managing users in memory is valid for test applications. However, Spring Security offers other implementations for production scenarios.

SQL Authentication

The following example demonstrates how to access an SQL database with tables for users and authorities.

@EnableWebSecurity
@Configuration
public class SecurityConfig extends VaadinWebSecurity {
  //...

  @Autowired
  private DataSource dataSource;

  @Override
  protected void configure(AuthenticationManagerBuilder auth) throws Exception {
    // Configure users and roles in a JDBC database
    auth.jdbcAuthentication()
      .dataSource(dataSource)
      .usersByUsernameQuery(
          "SELECT username, password, enabled FROM users WHERE username=?")
      .authoritiesByUsernameQuery(
          "SELECT username, authority FROM from authorities WHERE username=?")
      .passwordEncoder(new BCryptPasswordEncoder());
  }
}

LDAP Authentication

This next example shows how to configure authentication by using an LDAP repository:

@EnableWebSecurity
@Configuration
public class SecurityConfig extends VaadinWebSecurity {
  //...

  @Override
  protected void configure(AuthenticationManagerBuilder auth) throws Exception {
    // Obtain users and roles from an LDAP service
    auth.ldapAuthentication()
      .userDnPatterns("uid={0},ou=people")
      .userSearchBase("ou=people")
      .groupSearchBase("ou=groups")
      .contextSource()
      .url("ldap://localhost:8389/dc=example,dc=com")
      .and()
      .passwordCompare()
      .passwordAttribute("userPassword");
  }
}

Remember to add the corresponding LDAP client dependency to the project:

<dependency>
    <groupId>org.springframework.security</groupId>
    <artifactId>spring-security-ldap</artifactId>
    <version>5.2.0.RELEASE</version>
</dependency>

Documentation

Documentation

Authentication with Spring Security

Dependencies

Server Configuration

Public Views & Resources

Protect Hilla Views

Logout

Configuration Helper Alternatives

Implement Stateful Authentication

Appendix: Production Data Sources

SQL Authentication

LDAP Authentication

Documentation

Dependencies

Server Configuration

Public Views & Resources

Login View

Protect Hilla Views

Logout

Configuration Helper Alternatives

Implement Stateful Authentication

Appendix: Production Data Sources

SQL Authentication

LDAP Authentication