保护Web应用程序 - springboot guide中文文档

本指南将引导您创建一个简单的Web应用程序，其中的资源由Spring Security保护。

您将构建什么

您将构建一个 Spring MVC 应用程序，该应用程序通过由固定用户列表支持的表单登录来保护页面。

所需条件

大约 15 分钟
常用的文本编辑器或 IDE
Java 17 或更高版本
Gradle 7.5+ 或 Maven 3.5+
您也可以直接将代码导入到您的 IDE 中：

如何完成本指南

与大多数 Spring 入门指南一样，您可以从头开始并完成每个步骤，或者跳过您已经熟悉的基本设置步骤。无论哪种方式，您最终都会得到可运行的代码。

要从头开始，请继续阅读使用 Spring Initializr 开始。

要跳过基础部分，请执行以下操作：

下载并解压本指南的源码仓库，或使用Git克隆它：git clone https://github.com/spring-guides/gs-securing-web.git
进入 gs-securing-web/initial 目录
直接跳转到创建一个未受保护的Web应用。

当您完成后，您可以对照 gs-securing-web/complete 中的代码来检查您的结果。

从 Spring Initializr 开始

您可以使用这个预初始化项目并点击生成以下载一个 ZIP 文件。该项目已配置为适合本教程中的示例。

要手动初始化项目：

访问 https://start.spring.io。该服务会为您拉取应用程序所需的所有依赖项，并完成大部分设置工作。
选择 Gradle 或 Maven 以及您想要使用的语言。本指南假设您选择了 Java。
点击 Dependencies 并选择 Spring Web 和 Thymeleaf。
点击 Generate。
下载生成的 ZIP 文件，这是一个根据您的选择配置的 Web 应用程序存档。

如果您的 IDE 集成了 Spring Initializr，您可以直接在 IDE 中完成此过程。

您也可以从 Github 上 fork 该项目，并在您的 IDE 或其他编辑器中打开它。

创建一个未加密的 Web 应用程序

在您能够对 Web 应用程序应用安全性之前，您需要有一个需要保护的 Web 应用程序。本节将引导您创建一个简单的 Web 应用程序。然后，在下一节中，您将使用 Spring Security 对其进行保护。

该 Web 应用程序包含两个简单的视图：一个主页和一个“Hello, World”页面。主页面在以下 Thymeleaf 模板中定义（来自 src/main/resources/templates/home.html）：

<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml" xmlns:th="https://www.thymeleaf.org">
    <head>
        <title>Spring Security Example</title>
    </head>
    <body>
        <h1>Welcome!</h1>

        <p>Click <a th:href="@{/hello}">here</a> to see a greeting.</p>
    </body>
</html>

这个简单的视图包含一个指向 /hello 页面的链接，该页面在以下 Thymeleaf 模板中定义（位于 src/main/resources/templates/hello.html）：

<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml" xmlns:th="https://www.thymeleaf.org">
    <head>
        <title>Hello World!</title>
    </head>
    <body>
        <h1>Hello world!</h1>
    </body>
</html>

该 Web 应用程序基于 Spring MVC。因此，您需要配置 Spring MVC 并设置视图控制器来公开这些模板。以下代码清单（来自 src/main/java/com/example/securingweb/MvcConfig.java）展示了一个在应用程序中配置 Spring MVC 的类：

package com.example.securingweb;

import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ViewControllerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;

@Configuration
public class MvcConfig implements WebMvcConfigurer {

    public void addViewControllers(ViewControllerRegistry registry) {
        registry.addViewController("/home").setViewName("home");
        registry.addViewController("/").setViewName("home");
        registry.addViewController("/hello").setViewName("hello");
        registry.addViewController("/login").setViewName("login");
    }

}

addViewControllers() 方法（它重写了 WebMvcConfigurer 中的同名方法）添加了四个视图控制器。其中两个视图控制器引用了名为 home 的视图（在 home.html 中定义），另一个引用了名为 hello 的视图（在 hello.html 中定义）。第四个视图控制器引用了另一个名为 login 的视图。您将在下一节中创建该视图。

此时，您可以跳到“运行应用程序”并运行应用程序，而无需登录任何内容。

现在您已经拥有一个未受保护的 Web 应用程序，您可以为其添加安全性。

配置 Spring Security

假设您希望防止未经授权的用户查看 /hello 路径的问候页面。目前的情况是，如果访问者点击主页上的链接，他们将直接看到问候页面，没有任何障碍阻止他们。您需要添加一个屏障，强制访问者在查看该页面之前先登录。

您可以通过在应用程序中配置 Spring Security 来实现这一点。如果 Spring Security 存在于类路径中，Spring Boot 会自动使用“基本”认证保护所有 HTTP 端点。然而，您可以进一步自定义安全设置。首先，您需要将 Spring Security 添加到类路径中。

使用 Gradle，您需要在 build.gradle 文件的 dependencies 闭包中添加三行代码（一行用于应用程序，一行用于 Thymeleaf 和 Spring Security 的集成，一行用于测试），如下面的代码清单所示：

implementation 'org.springframework.boot:spring-boot-starter-security'
//  Temporary explicit version to fix Thymeleaf bug
implementation 'org.thymeleaf.extras:thymeleaf-extras-springsecurity6:3.1.2.RELEASE'
testImplementation 'org.springframework.security:spring-security-test'

以下清单展示了最终的 build.gradle 文件：

plugins {
    id 'java'
    id 'org.springframework.boot' version '3.3.0'
}

apply plugin: 'io.spring.dependency-management'

group = 'com.example'
version = '0.0.1-SNAPSHOT'
sourceCompatibility = '17'

repositories {
    mavenCentral()
}

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-web'
    implementation 'org.springframework.boot:spring-boot-starter-thymeleaf'
    implementation 'org.springframework.boot:spring-boot-starter-security'
    //  Temporary explicit version to fix Thymeleaf bug
    implementation 'org.thymeleaf.extras:thymeleaf-extras-springsecurity6:3.1.2.RELEASE'
    testImplementation 'org.springframework.security:spring-security-test'
    testImplementation 'org.springframework.boot:spring-boot-starter-test'
}

test {
    useJUnitPlatform()
}

使用 Maven 时，您需要在 pom.xml 中的 <dependencies> 元素中添加两个额外的条目（一个用于应用程序，一个用于测试），如下面的清单所示：

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-security</artifactId>
</dependency>
<dependency>
    <groupId>org.thymeleaf.extras</groupId>
    <artifactId>thymeleaf-extras-springsecurity6</artifactId>
    <!-- Temporary explicit version to fix Thymeleaf bug -->
    <version>3.1.1.RELEASE</version>
</dependency>
<dependency>
    <groupId>org.springframework.security</groupId>
    <artifactId>spring-security-test</artifactId>
    <scope>test</scope>
</dependency>

以下清单展示了完整的 pom.xml 文件：

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>3.3.0</version>
        <relativePath/> <!-- lookup parent from repository -->
    </parent>
    <groupId>com.example</groupId>
    <artifactId>securing-web-complete</artifactId>
    <version>0.0.1-SNAPSHOT</version>
    <name>securing-web-complete</name>
    <description>Demo project for Spring Boot</description>

    <properties>
        <java.version>17</java.version>
    </properties>

    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-thymeleaf</artifactId>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-security</artifactId>
        </dependency>
        <dependency>
            <groupId>org.thymeleaf.extras</groupId>
            <artifactId>thymeleaf-extras-springsecurity6</artifactId>
            <!-- Temporary explicit version to fix Thymeleaf bug -->
            <version>3.1.1.RELEASE</version>
        </dependency>
        <dependency>
            <groupId>org.springframework.security</groupId>
            <artifactId>spring-security-test</artifactId>
            <scope>test</scope>
        </dependency>

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>
    </dependencies>

</project>

以下安全配置（来自 src/main/java/com/example/securingweb/WebSecurityConfig.java）确保只有经过身份验证的用户才能看到秘密问候：

package com.example.securingweb;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity;
import org.springframework.security.core.userdetails.User;
import org.springframework.security.core.userdetails.UserDetails;
import org.springframework.security.core.userdetails.UserDetailsService;
import org.springframework.security.provisioning.InMemoryUserDetailsManager;
import org.springframework.security.web.SecurityFilterChain;

@Configuration
@EnableWebSecurity
public class WebSecurityConfig {

    @Bean
    public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
        http
            .authorizeHttpRequests((requests) -> requests
                .requestMatchers("/", "/home").permitAll()
                .anyRequest().authenticated()
            )
            .formLogin((form) -> form
                .loginPage("/login")
                .permitAll()
            )
            .logout((logout) -> logout.permitAll());

        return http.build();
    }

    @Bean
    public UserDetailsService userDetailsService() {
        UserDetails user =
             User.withDefaultPasswordEncoder()
                .username("user")
                .password("password")
                .roles("USER")
                .build();

        return new InMemoryUserDetailsManager(user);
    }
}

WebSecurityConfig 类通过 @EnableWebSecurity 注解启用了 Spring Security 的 Web 安全支持，并提供了 Spring MVC 的集成。它还暴露了两个 Bean 来为 Web 安全配置设置一些细节：

SecurityFilterChain Bean 定义了哪些 URL 路径需要被保护，哪些不需要。具体来说，/ 和 /home 路径被配置为不需要任何身份验证，而所有其他路径都必须经过身份验证。

当用户成功登录后，他们会被重定向到之前请求的需要身份验证的页面。有一个自定义的 /login 页面（通过 loginPage() 指定），并且所有人都被允许查看该页面。

UserDetailsService Bean 设置了一个内存用户存储，其中包含一个用户。该用户的用户名为 user，密码为 password，角色为 USER。

现在您需要创建登录页面。已经有一个用于 login 视图的视图控制器，因此您只需要创建登录视图本身，如下面的代码（来自 src/main/resources/templates/login.html）所示：

<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml" xmlns:th="https://www.thymeleaf.org">
    <head>
        <title>Spring Security Example </title>
    </head>
    <body>
        <div th:if="${param.error}">
            Invalid username and password.
        </div>
        <div th:if="${param.logout}">
            You have been logged out.
        </div>
        <form th:action="@{/login}" method="post">
            <div><label> User Name : <input type="text" name="username"/> </label></div>
            <div><label> Password: <input type="password" name="password"/> </label></div>
            <div><input type="submit" value="Sign In"/></div>
        </form>
    </body>
</html>

这个 Thymeleaf 模板展示了一个用于捕获用户名和密码并将其提交到 /login 的表单。按照配置，Spring Security 提供了一个过滤器来拦截该请求并对用户进行身份验证。如果用户验证失败，页面将重定向到 /login?error，并且您的页面会显示相应的错误信息。在成功注销后，应用程序将被重定向到 /login?logout，并且您的页面会显示相应的成功信息。

最后，您需要为访问者提供一种显示当前用户名并注销的方式。为此，更新 hello.html 以向当前用户问好，并包含一个 Sign Out 表单，如下面的代码清单所示（来自 src/main/resources/templates/hello.html）：

<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml" xmlns:th="https://www.thymeleaf.org"
      xmlns:sec="https://www.thymeleaf.org/thymeleaf-extras-springsecurity6">
    <head>
        <title>Hello World!</title>
    </head>
    <body>
        <h1 th:inline="text">Hello <span th:remove="tag" sec:authentication="name">thymeleaf</span>!</h1>
        <form th:action="@{/logout}" method="post">
            <input type="submit" value="Sign Out"/>
        </form>
    </body>
</html>

我们通过使用 Thymeleaf 与 Spring Security 的集成来显示用户名。“退出登录”表单会向 /logout 提交 POST 请求。在成功退出登录后，系统会将用户重定向到 /login?logout。

Thymeleaf 3.1 不再提供对 HttpServletRequest 的访问，因此无法使用 HttpServletRequest#getRemoteUser() 来获取当前认证的用户。

运行应用程序

Spring Initializr 为您创建了一个应用程序类。在这种情况下，您无需修改该类。以下代码清单（来自 src/main/java/com/example/securingweb/SecuringWebApplication.java）展示了该应用程序类：

package com.example.securingweb;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class SecuringWebApplication {

    public static void main(String[] args) throws Throwable {
        SpringApplication.run(SecuringWebApplication.class, args);
    }

}

构建可执行的 JAR 文件

您可以通过 Gradle 或 Maven 从命令行运行应用程序。您还可以构建一个包含所有必要依赖项、类和资源的单一可执行 JAR 文件并运行它。构建可执行 JAR 文件可以方便地在整个开发生命周期中、跨不同环境等场景下进行服务的交付、版本管理和部署。

如果您使用 Gradle，可以通过 ./gradlew bootRun 来运行应用程序。或者，您可以使用 ./gradlew build 构建 JAR 文件，然后按以下方式运行该 JAR 文件：

java -jar build/libs/gs-securing-web-0.1.0.jar

如果您使用 Maven，可以通过 ./mvnw spring-boot:run 来运行应用程序。或者，您也可以使用 ./mvnw clean package 构建 JAR 文件，然后如下所示运行该 JAR 文件：

java -jar target/gs-securing-web-0.1.0.jar

这里描述的步骤将创建一个可运行的 JAR 文件。您也可以构建一个经典的 WAR 文件。

应用程序启动后，将浏览器指向 http://localhost:8080。您应该会看到主页，如下图所示：

应用程序主页

当您点击链接时，它会尝试将您带到 /hello 的问候页面。然而，由于该页面是受保护的，而您尚未登录，它会将您带到登录页面，如下图所示：

登录页面

如果您跳转到这里的未受保护版本，您将看不到登录页面。您应该返回并编写其余基于安全的代码。

在登录页面，通过分别输入 user 和 password 作为用户名和密码字段，以测试用户身份登录。提交登录表单后，您将完成身份验证，然后跳转到欢迎页面，如下图所示：

受保护的欢迎页面

如果您点击 Sign Out 按钮，您的身份验证将被撤销，您将返回到登录页面，并显示一条消息，表明您已注销。

总结

恭喜！您已经开发了一个使用 Spring Security 进行安全保护的简单 Web 应用程序。

另请参阅

以下指南也可能会有帮助：