Spring Boot 集成教程

本教程介绍如何使用 Spring Boot + Spring Security 通过 Authorization Code Flow 集成 Code Bird Cloud 进行用户认证。Spring Security 的 OAuth2 Client 模块提供了开箱即用的 OIDC 支持，只需少量配置即可完成集成。

前置条件

Java 17 或更高版本
Maven 或 Gradle 构建工具
Spring Boot 3.x
已在 Code Bird Cloud 管理后台创建 Traditional 类型的应用，并获取 Client ID 和 Client Secret
已配置 Redirect URI 为 http://localhost:8080/login/oauth2/code/codebird

Spring Security 默认的 Redirect URI 格式为 {baseUrl}/login/oauth2/code/{registrationId}，其中 registrationId 为配置中的注册名称。

Maven 依赖

xml

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

依赖包	说明
`spring-boot-starter-oauth2-client`	Spring Security OAuth2 客户端模块，支持 OIDC 自动发现
`spring-boot-starter-security`	Spring Security 核心模块
`spring-boot-starter-web`	Spring MVC Web 支持

application.yml 配置

yaml

spring:
  security:
    oauth2:
      client:
        registration:
          codebird:
            client-id: ${CLIENT_ID}
            client-secret: ${CLIENT_SECRET}
            scope:
              - openid
              - profile
              - email
              - offline_access
            authorization-grant-type: authorization_code
            redirect-uri: "{baseUrl}/login/oauth2/code/{registrationId}"
            client-name: Code Bird Cloud
        provider:
          codebird:
            issuer-uri: https://your-domain.com

Spring Security 会自动通过 issuer-uri 获取 OIDC 发现配置，无需手动指定各个端点地址。

Security 配置类

java

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.web.SecurityFilterChain;

@Configuration
@EnableWebSecurity
public class SecurityConfig {

    @Bean
    public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
        http
            .authorizeHttpRequests(authorize -> authorize
                .requestMatchers("/", "/public/**").permitAll()
                .anyRequest().authenticated()
            )
            .oauth2Login(oauth2 -> oauth2
                .defaultSuccessUrl("/dashboard", true)
            )
            .logout(logout -> logout
                .logoutSuccessUrl("/")
            );

        return http.build();
    }
}

配置说明：

/ 和 /public/** 路径无需认证，其他路径需要登录
登录成功后默认跳转到 /dashboard
登出后跳转回首页

Controller 示例

java

import org.springframework.security.core.annotation.AuthenticationPrincipal;
import org.springframework.security.oauth2.core.oidc.user.OidcUser;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

import java.util.Map;

@RestController
public class UserController {

    @GetMapping("/dashboard")
    public Map<String, Object> dashboard(@AuthenticationPrincipal OidcUser user) {
        return Map.of(
            "subject", user.getSubject(),
            "name", user.getFullName(),
            "email", user.getEmail(),
            "claims", user.getClaims()
        );
    }
}

说明：

@AuthenticationPrincipal OidcUser user 注入当前认证用户的 OIDC 信息
OidcUser 提供了 getSubject()、getFullName()、getEmail() 等便捷方法
getClaims() 返回 ID Token 中的所有 Claims

运行

bash

# 设置环境变量
export CLIENT_ID="your_client_id"
export CLIENT_SECRET="your_client_secret"

# 使用 Maven 运行
mvn spring-boot:run

# 或使用 Gradle
./gradlew bootRun

访问 http://localhost:8080/dashboard，未登录用户将被自动重定向到 Code Bird Cloud 的登录页面。

Spring Security 自动处理的事项

使用 Spring Security OAuth2 Client，以下流程由框架自动处理：

OIDC 发现端点调用
授权码流程的完整交互（重定向、回调、令牌交换）
ID Token 验证（签名、受众、过期时间）
用户信息获取
CSRF 防护
Session 管理

你只需关注业务逻辑的实现。

Spring Boot 集成教程 ​

前置条件 ​

Maven 依赖 ​

application.yml 配置 ​

Security 配置类 ​

Controller 示例 ​

运行 ​

Spring Security 自动处理的事项 ​

相关文档 ​