SpringBoot项目集成第三方CAS-client jar包

在企业级应用开发中，随着系统数量增多，用户在多系统间频繁登录的问题日益凸显。单点登录（SSO，Single Sign-On）技术应运而生，而 CAS（Central Authentication Service，中央认证服务）作为主流的 SSO 实现方案，被广泛用于企业内部系统的统一认证。本文将详细讲解 SpringBoot 项目引入第三方 CAS-client jar 包的完整流程，包括两种集成方式的深度实操、依赖冲突解决、打包配置优化及常见问题排查，帮助开发者高效完成 SSO 对接。

一、背景：为什么需要 CAS-client？

在传统多系统架构中，用户需在每个系统单独注册、登录，不仅影响用户体验，还增加了系统管理成本。CAS 作为一种开源的 SSO 框架，通过 "中央认证服务器 + 客户端" 的架构，实现 "一次登录，多系统访问"：

CAS 服务器：负责统一认证，存储用户账号密码，生成认证凭证（Ticket）；
CAS-client：集成在业务系统（如 SpringBoot 项目）中，负责与 CAS 服务器通信，拦截未认证请求，验证用户凭证，完成登录状态同步。

本文场景为：某企业需将 SpringBoot 业务系统接入现有 CAS 认证体系，需引入第三方提供的cas-client-core-3.2.1.jar（非 Maven 中央仓库可直接获取的依赖），因此需通过自定义方式集成 jar 包。

二、SpringBoot 集成 CAS-client jar 包的两种核心方式

针对非中央仓库的第三方 jar 包，SpringBoot 项目通常采用 "本地 Maven 仓库集成" 或 "项目内 lib 目录集成" 两种方式，以下为详细实操步骤及拓展说明。

方式 1：本地 Maven 仓库集成（适合个人调试 / 单系统开发）

将第三方 jar 包安装到本地 Maven 仓库，再通过标准<dependency>标签引入，符合 Maven 依赖管理规范，适合个人开发或独立 demo 调试场景。

1.1 准备工作

下载第三方cas-client-core-3.2.1.jar，存放路径示例：D:\libs\cas-client-core-3.2.1.jar；
确认本地 Maven 环境配置正常（执行mvn -v可查看版本），若使用自定义 Maven 仓库（非默认.m2/repository），需提前配置settings.xml（路径：Maven 安装目录 /conf/settings.xml）。

1.2 安装 jar 包到本地仓库

通过 Maven 命令行工具，执行mvn install:install-file命令，将 jar 包安装到指定仓库，命令格式及参数说明如下：

bash 复制代码

mvn install:install-file 
  -Dfile=D:\libs\cas-client-core-3.2.1.jar  # jar包本地绝对路径
  -DgroupId=org.jasig.cas.client            # 依赖的groupId（需与jar包内pom一致）
  -DartifactId=cas-client-core              # 依赖的artifactId（需与jar包内pom一致）
  -Dversion=3.2.1                           # 依赖版本（需与jar包版本一致）
  -Dpackaging=jar                           # 打包类型（jar/war）
  -DlocalRepositoryPath=E:\maven-repo       # 可选：指定安装到的本地仓库路径（多仓库场景必配）

参数说明 ：若不指定-DlocalRepositoryPath，jar 包将默认安装到user.home/.m2/repository；多仓库场景下，需确保该路径与项目使用的 Maven 仓库一致（可在 IDE 中查看项目 Maven 配置）。

1.3 项目 pom.xml 引入依赖

安装完成后，在 SpringBoot 项目的pom.xml中添加标准依赖，无需额外配置路径：

xml 复制代码

<!-- CAS-client依赖（本地仓库已存在） -->
<dependency>
    <groupId>org.jasig.cas.client</groupId>
    <artifactId>cas-client-core</artifactId>
    <version>3.2.1</version>
</dependency>

1.4 多 Maven 仓库场景配置补充

若项目同时配置了本地仓库、私有仓库（如 Nexus），需在pom.xml或settings.xml中指定仓库优先级，避免依赖拉取失败。示例：在settings.xml中配置仓库顺序：

xml 复制代码

<profiles>
    <profile>
        <id>maven-repo</id>
        <repositories>
            <!-- 优先从自定义本地仓库拉取 -->
            <repository>
                <id>local-repo</id>
                <url>file://E:\maven-repo</url>
                <releases><enabled>true</enabled></releases>
                <snapshots><enabled>true</enabled></snapshots>
            </repository>
            <!-- 其次从私有仓库拉取 -->
            <repository>
                <id>nexus-repo</id>
                <url>http://192.168.1.100:8081/repository/maven-public/</url>
            </repository>
        </repositories>
    </profile>
</profiles>
<!-- 激活配置 -->
<activeProfiles>
    <activeProfile>maven-repo</activeProfile>
</activeProfiles>

方式 2：项目内 lib 目录集成（适合团队协同开发）

将 jar 包直接放在项目目录下的lib文件夹中，通过system scope 指定路径，避免团队成员重复安装本地仓库，适合多人协同开发场景。

2.1 新建项目 lib 目录

在 SpringBoot 项目根目录（与src、pom.xml同级）新建lib文件夹，将cas-client-core-3.2.1.jar复制到该目录下，目录结构如下：

Plain 复制代码

your-springboot-project/
├─ src/
├─ lib/
│  └─ cas-client-core-3.2.1.jar  # 第三方CAS-client jar包
├─ pom.xml
└─ .mvn/

2.2 获取依赖的 groupId/artifactId（关键步骤）

pom.xml中system scope 依赖需准确配置groupId和artifactId，需从 jar 包内的 pom 文件中获取，步骤如下：

右键cas-client-core-3.2.1.jar，用压缩软件（如 WinRAR、7-Zip）打开；
在 jar 包根目录中找到pom.xml文件，解压到本地；
打开解压后的pom.xml，查找以下配置（示例）：

xml 复制代码

<modelVersion>4.0.0</modelVersion>
<groupId>org.jasig.cas.client</groupId>  <!-- 需复制的groupId -->
<artifactId>cas-client-core</artifactId>  <!-- 需复制的artifactId -->
<version>3.2.1</version>
<packaging>jar</packaging>
<name>Jasig CAS Client for Java - Core</name>

复制上述groupId和artifactId，用于项目pom.xml配置。

2.3 pom.xml 配置 system scope 依赖

在pom.xml中添加依赖，通过${basedir}变量（表示项目根目录）指定systemPath，避免硬编码路径：

xml 复制代码

<!-- CAS-client依赖（项目lib目录） -->
<dependency>
    <groupId>org.jasig.cas.client</groupId>
    <artifactId>cas-client-core</artifactId>
    <version>3.2.1</version>
    <scope>system</scope>  <!-- 系统级依赖，需指定本地路径 -->
    <!-- 路径：项目根目录/lib/cas-client-core-3.2.1.jar -->
    <systemPath>${basedir}/lib/cas-client-core-3.2.1.jar</systemPath>
</dependency>

路径说明 ：若lib目录放在src/main/resources下，systemPath需改为${basedir}/src/main/resources/lib/cas-client-core-3.2.1.jar，需根据实际目录调整。

三、依赖冲突深度解决（不止于 Shiro-CAS）

实际开发中还可能遇到版本不一致、重复引入等问题，需系统化排查与解决。

3.1 查看依赖树，定位冲突来源

通过 Maven 命令查看项目完整依赖树，找到引入cas-client-core的所有依赖：

bash 复制代码

mvn dependency:tree -Dincludes=org.jasig.cas.client:cas-client-core

执行后会输出类似结果：

Plain 复制代码

[INFO] com.example:springboot-sso:jar:1.0.0
[INFO] +- org.apache.shiro:shiro-cas:jar:1.7.1:compile
[INFO] |  \- org.jasig.cas.client:cas-client-core:jar:3.1.10:compile  # 冲突版本
[INFO] \- org.jasig.cas.client:cas-client-core:jar:3.2.1:system      # 我们引入的版本

可见shiro-cas默认引入了3.1.10版本，与我们需要的3.2.1冲突。

3.2 排除冲突依赖

在引入冲突依赖（如shiro-cas）时，通过<exclusions>标签排除其自带的cas-client-core：

xml 复制代码

<!-- Shiro-CAS依赖，排除内置的cas-client-core -->
<dependency>
    <groupId>org.apache.shiro</groupId>
    <artifactId>shiro-cas</artifactId>
    <version>1.7.1</version>
    <exclusions>
        <!-- 排除冲突的cas-client-core版本 -->
        <exclusion>
            <groupId>org.jasig.cas.client</groupId>
            <artifactId>cas-client-core</artifactId>
        </exclusion>
    </exclusions>
</dependency>

拓展场景 ：若多个依赖均引入cas-client-core，需在所有冲突依赖中排除，确保项目仅使用我们指定的版本。

四、打包配置：确保第三方 jar 包被包含（多插件支持）

Maven 默认不打包system scope 的依赖，需在打包插件中配置includeSystemScope=true，否则项目部署后会出现ClassNotFoundException。以下为两种主流打包插件的配置方案。

4.1 SpringBoot 默认打包插件（spring-boot-maven-plugin）

配置如下（需放在pom.xml的<build><plugins>中）：

xml 复制代码

<plugin>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-maven-plugin</artifactId>
    <version>2.7.0</version>  <!-- 与项目SpringBoot版本一致 -->
    <configuration>
        <!-- 关键配置：包含system scope的依赖 -->
        <includeSystemScope>true</includeSystemScope>
        <!-- 可选：指定主启动类 -->
        <mainClass>com.example.SpringBootSsoApplication</mainClass>
    </configuration>
    <executions>
        <execution>
            <goals>
                <goal>repackage</goal>  <!-- 重新打包成可执行jar -->
            </goals>
        </execution>
    </executions>
</plugin>

4.2 Maven Assembly 插件（适合多模块打包）

若项目为多模块架构，或需自定义打包结构，可使用maven-assembly-plugin，配置如下：

xml 复制代码

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-assembly-plugin</artifactId>
    <version>3.4.2</version>
    <configuration>
        <descriptorRefs>
            <descriptorRef>jar-with-dependencies</descriptorRef>  <!-- 打包所有依赖 -->
        </descriptorRefs>
        <archive>
            <manifest>
                <mainClass>com.example.SpringBootSsoApplication</mainClass>  <!-- 主启动类 -->
            </manifest>
        </archive>
        <!-- 包含system scope依赖 -->
        <includeSystemScope>true</includeSystemScope>
    </configuration>
    <executions>
        <execution>
            <id>make-assembly</id>
            <phase>package</phase>
            <goals>
                <goal>single</goal>
            </goals>
        </execution>
    </executions>
</plugin>

五、常见问题排查与解决方案

5.1 问题 1：启动报错 ClassNotFoundException: org.jasig.cas.client.authentication.AuthenticationFilter

可能原因：

systemPath路径配置错误；
打包时未配置includeSystemScope=true；
jar 包损坏或版本不匹配。

排查步骤：

验证systemPath正确性：在 IDE 中点击${basedir}/lib/cas-client-core-3.2.1.jar，查看是否能跳转至 jar 包；
检查打包后的 jar：用压缩软件打开目标 jar，查看BOOT-INF/lib下是否包含cas-client-core-3.2.1.jar；
重新下载 jar 包：若 jar 包损坏，替换为正常版本。

5.2 问题 2：Maven 仓库安装后，项目仍无法拉取依赖

可能原因：

安装路径与项目使用的 Maven 仓库不一致；
groupId/artifactId/version与安装命令不一致。

排查步骤：

查看项目 Maven 配置：在 IDE（如 IDEA）中，进入File > Settings > Build, Execution, Deployment > Build Tools > Maven，确认Local repository路径与安装命令中的-DlocalRepositoryPath一致；
核对依赖坐标：确保pom.xml中的groupId、artifactId、version与mvn install命令中的参数完全一致（大小写敏感）。

六、CAS-client 初步配置与使用（拓展实操）

引入 jar 包后，需简单配置 CAS-client 才能实现 SSO 功能，以下为 SpringBoot 中的基础配置（application.yml）：

yaml 复制代码

# CAS服务器配置
cas:
  server-url-prefix: http://cas.example.com/cas  # CAS服务器地址前缀
  server-login-url: http://cas.example.com/cas/login  # CAS登录页面地址
  client-host-url: http://localhost:8080  # 当前SpringBoot项目地址（回调地址基础）

# CAS-client过滤器配置（SpringBoot方式）
spring:
  servlet:
    filter:
      cas:
        authentication-filter:
          enabled: true
          url-pattern: /*  # 拦截所有请求
        validation-filter:
          enabled: true
          url-pattern: /*
        ticket-validation-filter:
          enabled: true
          url-pattern: /*

同时，需在启动类中注册 CAS 相关过滤器（示例）：

java 复制代码

@SpringBootApplication
public class SpringBootSsoApplication {
    public static void main(String[] args) {
        SpringApplication.run(SpringBootSsoApplication.class, args);
    }

    // 注册CAS认证过滤器
    @Bean
    public FilterRegistrationBean<AuthenticationFilter> authenticationFilter() {
        FilterRegistrationBean<AuthenticationFilter> registrationBean = new FilterRegistrationBean<>();
        registrationBean.setFilter(new AuthenticationFilter());
        registrationBean.addUrlPatterns("/*");
        Map<String, String> initParams = new HashMap<>();
        initParams.put("casServerLoginUrl", "${cas.server-login-url}");
        initParams.put("serverName", "${cas.client-host-url}");
        registrationBean.setInitParameters(initParams);
        return registrationBean;
    }
}

七、两种集成方式对比与选型建议

对比维度	方式 1：本地 Maven 仓库	方式 2：项目内 lib 目录
适用场景	个人开发、demo 调试	团队协同开发、多人共享依赖
操作复杂度	需执行命令安装，首次配置稍复杂	直接复制 jar 包，配置简单
依赖管理	符合 Maven 规范，便于版本控制	依赖脱离 Maven 仓库，需手动维护版本
团队协作	成员需重复安装到本地仓库，效率低	提交 lib 目录到 Git，成员拉取即可使用
选型建议：

个人开发或短期 demo：优先选择方式 1，减少项目目录冗余；
团队协同或长期项目：优先选择方式 2，或进阶方案 ------ 搭建私有 Maven 仓库（如 Nexus），将第三方 jar 包上传至私有仓库，团队成员通过标准依赖引入，兼顾规范与协作效率。

八、总结

本文详细讲解了 SpringBoot 项目集成第三方 CAS-client jar 包的两种核心方式，从背景原理到实操步骤，再到冲突解决、打包配置及问题排查，覆盖了企业级开发中的关键场景。在实际项目中，需根据团队协作模式和项目需求选择合适的集成方式，同时注重依赖管理的规范性，避免版本冲突和部署问题。后续可进一步学习 CAS 的高级功能（如单点登出、多因素认证），为企业应用构建更安全、更完善的统一认证体系。