在企業(yè)級(jí)應(yīng)用開(kāi)發(fā)中，隨著系統(tǒng)數(shù)量增多，用戶在多系統(tǒng)間頻繁登錄的問(wèn)題日益凸顯。單點(diǎn)登錄（SSO，Single Sign-On）技術(shù)應(yīng)運(yùn)而生，而 CAS（Central Authentication Service，中央認(rèn)證服務(wù)）作為主流的 SSO 實(shí)現(xiàn)方案，被廣泛用于企業(yè)內(nèi)部系統(tǒng)的統(tǒng)一認(rèn)證。本文將詳細(xì)講解 SpringBoot 項(xiàng)目引入第三方 CAS-client jar 包的完整流程，包括兩種集成方式的深度實(shí)操、依賴沖突解決、打包配置優(yōu)化及常見(jiàn)問(wèn)題排查，幫助開(kāi)發(fā)者高效完成 SSO 對(duì)接。

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

在傳統(tǒng)多系統(tǒng)架構(gòu)中，用戶需在每個(gè)系統(tǒng)單獨(dú)注冊(cè)、登錄，不僅影響用戶體驗(yàn)，還增加了系統(tǒng)管理成本。CAS 作為一種開(kāi)源的 SSO 框架，通過(guò) “中央認(rèn)證服務(wù)器 + 客戶端” 的架構(gòu)，實(shí)現(xiàn) “一次登錄，多系統(tǒng)訪問(wèn)”：

• CAS 服務(wù)器：負(fù)責(zé)統(tǒng)一認(rèn)證，存儲(chǔ)用戶賬號(hào)密碼，生成認(rèn)證憑證（Ticket）；
• CAS-client：集成在業(yè)務(wù)系統(tǒng)（如 SpringBoot 項(xiàng)目）中，負(fù)責(zé)與 CAS 服務(wù)器通信，攔截未認(rèn)證請(qǐng)求，驗(yàn)證用戶憑證，完成登錄狀態(tài)同步。

本文場(chǎng)景為：某企業(yè)需將 SpringBoot 業(yè)務(wù)系統(tǒng)接入現(xiàn)有 CAS 認(rèn)證體系，需引入第三方提供的cas-client-core-3.2.1.jar（非 Maven 中央倉(cāng)庫(kù)可直接獲取的依賴），因此需通過(guò)自定義方式集成 jar 包。

二、SpringBoot 集成 CAS-client jar 包的兩種核心方式

針對(duì)非中央倉(cāng)庫(kù)的第三方 jar 包，SpringBoot 項(xiàng)目通常采用 “本地 Maven 倉(cāng)庫(kù)集成” 或 “項(xiàng)目?jī)?nèi) lib 目錄集成” 兩種方式，以下為詳細(xì)實(shí)操步驟及拓展說(shuō)明。

方式 1：本地 Maven 倉(cāng)庫(kù)集成（適合個(gè)人調(diào)試 / 單系統(tǒng)開(kāi)發(fā)）

將第三方 jar 包安裝到本地 Maven 倉(cāng)庫(kù)，再通過(guò)標(biāo)準(zhǔn)<dependency>標(biāo)簽引入，符合 Maven 依賴管理規(guī)范，適合個(gè)人開(kāi)發(fā)或獨(dú)立 demo 調(diào)試場(chǎng)景。

1.1 準(zhǔn)備工作

• 下載第三方cas-client-core-3.2.1.jar，存放路徑示例：D:\libs\cas-client-core-3.2.1.jar；
• 確認(rèn)本地 Maven 環(huán)境配置正常（執(zhí)行mvn -v可查看版本），若使用自定義 Maven 倉(cāng)庫(kù)（非默認(rèn).m2/repository），需提前配置settings.xml（路徑：Maven 安裝目錄 /conf/settings.xml）。

1.2 安裝 jar 包到本地倉(cāng)庫(kù)

通過(guò) Maven 命令行工具，執(zhí)行mvn install:install-file命令，將 jar 包安裝到指定倉(cāng)庫(kù)，命令格式及參數(shù)說(shuō)明如下：

mvn install:install-file 
  -Dfile=D:\libs\cas-client-core-3.2.1.jar  # jar包本地絕對(duì)路徑
  -DgroupId=org.jasig.cas.client            # 依賴的groupId（需與jar包內(nèi)pom一致）
  -DartifactId=cas-client-core              # 依賴的artifactId（需與jar包內(nèi)pom一致）
  -Dversion=3.2.1                           # 依賴版本（需與jar包版本一致）
  -Dpackaging=jar                           # 打包類型（jar/war）
  -DlocalRepositoryPath=E:\maven-repo       # 可選：指定安裝到的本地倉(cāng)庫(kù)路徑（多倉(cāng)庫(kù)場(chǎng)景必配）

• 參數(shù)說(shuō)明：若不指定-DlocalRepositoryPath，jar 包將默認(rèn)安裝到user.home/.m2/repository；多倉(cāng)庫(kù)場(chǎng)景下，需確保該路徑與項(xiàng)目使用的 Maven 倉(cāng)庫(kù)一致（可在 IDE 中查看項(xiàng)目 Maven 配置）。

1.3 項(xiàng)目 pom.xml 引入依賴

安裝完成后，在 SpringBoot 項(xiàng)目的pom.xml中添加標(biāo)準(zhǔn)依賴，無(wú)需額外配置路徑：

<!-- CAS-client依賴（本地倉(cāng)庫(kù)已存在） -->
<dependency>
    <groupId>org.jasig.cas.client</groupId>
    <artifactId>cas-client-core</artifactId>
    <version>3.2.1</version>
</dependency>

1.4 多 Maven 倉(cāng)庫(kù)場(chǎng)景配置補(bǔ)充

若項(xiàng)目同時(shí)配置了本地倉(cāng)庫(kù)、私有倉(cāng)庫(kù)（如 Nexus），需在pom.xml或settings.xml中指定倉(cāng)庫(kù)優(yōu)先級(jí)，避免依賴?yán)∈?。示例：?code>settings.xml中配置倉(cāng)庫(kù)順序：

<profiles>
    <profile>
        <id>maven-repo</id>
        <repositories>
            <!-- 優(yōu)先從自定義本地倉(cāng)庫(kù)拉取 -->
            <repository>
                <id>local-repo</id>
                <url>file://E:\maven-repo</url>
                <releases><enabled>true</enabled></releases>
                <snapshots><enabled>true</enabled></snapshots>
            </repository>
            <!-- 其次從私有倉(cāng)庫(kù)拉取 -->
            <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：項(xiàng)目?jī)?nèi) lib 目錄集成（適合團(tuán)隊(duì)協(xié)同開(kāi)發(fā)）

將 jar 包直接放在項(xiàng)目目錄下的lib文件夾中，通過(guò)system scope 指定路徑，避免團(tuán)隊(duì)成員重復(fù)安裝本地倉(cāng)庫(kù)，適合多人協(xié)同開(kāi)發(fā)場(chǎng)景。

2.1 新建項(xiàng)目 lib 目錄

在 SpringBoot 項(xiàng)目根目錄（與src、pom.xml同級(jí)）新建lib文件夾，將cas-client-core-3.2.1.jar復(fù)制到該目錄下，目錄結(jié)構(gòu)如下：

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

2.2 獲取依賴的 groupId/artifactId（關(guān)鍵步驟）

pom.xml中system scope 依賴需準(zhǔn)確配置groupId和artifactId，需從 jar 包內(nèi)的 pom 文件中獲取，步驟如下：

• 右鍵cas-client-core-3.2.1.jar，用壓縮軟件（如 WinRAR、7-Zip）打開(kāi)；
• 在 jar 包根目錄中找到pom.xml文件，解壓到本地；
• 打開(kāi)解壓后的pom.xml，查找以下配置（示例）：

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

復(fù)制上述groupId和artifactId，用于項(xiàng)目pom.xml配置。

2.3 pom.xml 配置 system scope 依賴

在pom.xml中添加依賴，通過(guò)${basedir}變量（表示項(xiàng)目根目錄）指定systemPath，避免硬編碼路徑：

<!-- CAS-client依賴（項(xiàng)目lib目錄） -->
<dependency>
    <groupId>org.jasig.cas.client</groupId>
    <artifactId>cas-client-core</artifactId>
    <version>3.2.1</version>
    <scope>system</scope>  <!-- 系統(tǒng)級(jí)依賴，需指定本地路徑 -->
    <!-- 路徑：項(xiàng)目根目錄/lib/cas-client-core-3.2.1.jar -->
    <systemPath>${basedir}/lib/cas-client-core-3.2.1.jar</systemPath>
</dependency>

• 路徑說(shuō)明：若lib目錄放在src/main/resources下，systemPath需改為${basedir}/src/main/resources/lib/cas-client-core-3.2.1.jar，需根據(jù)實(shí)際目錄調(diào)整。

三、依賴沖突深度解決（不止于 Shiro-CAS）

實(shí)際開(kāi)發(fā)中還可能遇到版本不一致、重復(fù)引入等問(wèn)題，需系統(tǒng)化排查與解決。

3.1 查看依賴樹(shù)，定位沖突來(lái)源

通過(guò) Maven 命令查看項(xiàng)目完整依賴樹(shù)，找到引入cas-client-core的所有依賴：

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

執(zhí)行后會(huì)輸出類似結(jié)果：

[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      # 我們引入的版本

可見(jiàn)shiro-cas默認(rèn)引入了3.1.10版本，與我們需要的3.2.1沖突。

3.2 排除沖突依賴

在引入沖突依賴（如shiro-cas）時(shí)，通過(guò)<exclusions>標(biāo)簽排除其自帶的cas-client-core：

<!-- Shiro-CAS依賴，排除內(nèi)置的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>

• 拓展場(chǎng)景：若多個(gè)依賴均引入cas-client-core，需在所有沖突依賴中排除，確保項(xiàng)目?jī)H使用我們指定的版本。

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

Maven 默認(rèn)不打包system scope 的依賴，需在打包插件中配置includeSystemScope=true，否則項(xiàng)目部署后會(huì)出現(xiàn)ClassNotFoundException。以下為兩種主流打包插件的配置方案。

4.1 SpringBoot 默認(rèn)打包插件（spring-boot-maven-plugin）

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

<plugin>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-maven-plugin</artifactId>
    <version>2.7.0</version>  <!-- 與項(xiàng)目SpringBoot版本一致 -->
    <configuration>
        <!-- 關(guān)鍵配置：包含system scope的依賴 -->
        <includeSystemScope>true</includeSystemScope>
        <!-- 可選：指定主啟動(dòng)類 -->
        <mainClass>com.example.SpringBootSsoApplication</mainClass>
    </configuration>
    <executions>
        <execution>
            <goals>
                <goal>repackage</goal>  <!-- 重新打包成可執(zhí)行jar -->
            </goals>
        </execution>
    </executions>
</plugin>

4.2 Maven Assembly 插件（適合多模塊打包）

若項(xiàng)目為多模塊架構(gòu)，或需自定義打包結(jié)構(gòu)，可使用maven-assembly-plugin，配置如下：

<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>  <!-- 主啟動(dòng)類 -->
            </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>

五、常見(jiàn)問(wèn)題排查與解決方案

5.1 問(wèn)題 1：?jiǎn)?dòng)報(bào)錯(cuò) ClassNotFoundException: org.jasig.cas.client.authentication.AuthenticationFilter

可能原因：

• systemPath路徑配置錯(cuò)誤；
• 打包時(shí)未配置includeSystemScope=true；
• jar 包損壞或版本不匹配。

排查步驟：

• 驗(yàn)證systemPath正確性：在 IDE 中點(diǎn)擊${basedir}/lib/cas-client-core-3.2.1.jar，查看是否能跳轉(zhuǎn)至 jar 包；
• 檢查打包后的 jar：用壓縮軟件打開(kāi)目標(biāo) jar，查看BOOT-INF/lib下是否包含cas-client-core-3.2.1.jar；
• 重新下載 jar 包：若 jar 包損壞，替換為正常版本。

5.2 問(wèn)題 2：Maven 倉(cāng)庫(kù)安裝后，項(xiàng)目仍無(wú)法拉取依賴

可能原因：

• 安裝路徑與項(xiàng)目使用的 Maven 倉(cāng)庫(kù)不一致；
• groupId/artifactId/version與安裝命令不一致。

排查步驟：

• 查看項(xiàng)目 Maven 配置：在 IDE（如 IDEA）中，進(jìn)入File > Settings > Build, Execution, Deployment > Build Tools > Maven，確認(rèn)Local repository路徑與安裝命令中的-DlocalRepositoryPath一致；
• 核對(duì)依賴坐標(biāo)：確保pom.xml中的groupId、artifactId、version與mvn install命令中的參數(shù)完全一致（大小寫敏感）。

六、CAS-client 初步配置與使用（拓展實(shí)操）

引入 jar 包后，需簡(jiǎn)單配置 CAS-client 才能實(shí)現(xiàn) SSO 功能，以下為 SpringBoot 中的基礎(chǔ)配置（application.yml）：

# CAS服務(wù)器配置
cas:
  server-url-prefix: http://cas.example.com/cas  # CAS服務(wù)器地址前綴
  server-login-url: http://cas.example.com/cas/login  # CAS登錄頁(yè)面地址
  client-host-url: http://localhost:8080  # 當(dāng)前SpringBoot項(xiàng)目地址（回調(diào)地址基礎(chǔ)）
# CAS-client過(guò)濾器配置（SpringBoot方式）
spring:
  servlet:
    filter:
      cas:
        authentication-filter:
          enabled: true
          url-pattern: /*  # 攔截所有請(qǐng)求
        validation-filter:
          enabled: true
          url-pattern: /*
        ticket-validation-filter:
          enabled: true
          url-pattern: /*

同時(shí)，需在啟動(dòng)類中注冊(cè) CAS 相關(guān)過(guò)濾器（示例）：

@SpringBootApplication
public class SpringBootSsoApplication {
    public static void main(String[] args) {
        SpringApplication.run(SpringBootSsoApplication.class, args);
    }
    // 注冊(cè)CAS認(rèn)證過(guò)濾器
    @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;
    }
}

七、兩種集成方式對(duì)比與選型建議

• 個(gè)人開(kāi)發(fā)或短期 demo：優(yōu)先選擇方式 1，減少項(xiàng)目目錄冗余；
• 團(tuán)隊(duì)協(xié)同或長(zhǎng)期項(xiàng)目：優(yōu)先選擇方式 2，或進(jìn)階方案 —— 搭建私有 Maven 倉(cāng)庫(kù)（如 Nexus），將第三方 jar 包上傳至私有倉(cāng)庫(kù)，團(tuán)隊(duì)成員通過(guò)標(biāo)準(zhǔn)依賴引入，兼顧規(guī)范與協(xié)作效率。

八、總結(jié)

本文詳細(xì)講解了 SpringBoot 項(xiàng)目集成第三方 CAS-client jar 包的兩種核心方式，從背景原理到實(shí)操步驟，再到?jīng)_突解決、打包配置及問(wèn)題排查，覆蓋了企業(yè)級(jí)開(kāi)發(fā)中的關(guān)鍵場(chǎng)景。在實(shí)際項(xiàng)目中，需根據(jù)團(tuán)隊(duì)協(xié)作模式和項(xiàng)目需求選擇合適的集成方式，同時(shí)注重依賴管理的規(guī)范性，避免版本沖突和部署問(wèn)題。后續(xù)可進(jìn)一步學(xué)習(xí) CAS 的高級(jí)功能（如單點(diǎn)登出、多因素認(rèn)證），為企業(yè)應(yīng)用構(gòu)建更安全、更完善的統(tǒng)一認(rèn)證體系。

最新評(píng)論