Java 整合 JCIFS 實現 AD 域單點登錄（SSO）完整指南

背景與動機

Active Directory（AD）域認證已成企業級內網系統（ERP、OA、CRM）安全整合的標準配置。單點登錄（SSO）讓使用者一次登錄即可訪問所有互信應用，是當前企業業務整合的主流方案。本文示範如何利用 JCIFS 庫在 Java Web 應用中實現基於 NTLM 的 AD 域透明認證。

核心依賴

下載 jcifs-1.3.15.jar（或更新版本）並放入 Tomcat 的 webapps/你的項目/WEB-INF/lib 目錄。

web.xml 過濾器配置

在 web.xml 中註冊 NtlmHttpFilter，關鍵參數說明：

<filter>
    <filter-name>NtlmHttpFilter</filter-name>
    <filter-class>jcifs.http.NtlmHttpFilter</filter-class>
    <init-param>
        <param-name>jcifs.http.domainController</param-name>
        <param-value>10.10.2.153</param-value> <!-- 域控制器 IP -->
    </init-param>
    <init-param>
        <param-name>jcifs.util.loglevel</param-name>
        <param-value>3</param-value> <!-- 日誌級別 -->
    </init-param>
    <!-- 可選：指定用於驗證的域帳號/密碼，若省略則嘗試使用運行進程的身份 -->
    <init-param>
        <param-name>jcifs.smb.client.username</param-name>
        <param-value>domain_user</param-value>
    </init-param>
    <init-param>
        <param-name>jcifs.smb.client.password</param-name>
        <param-value>password</param-value>
    </init-param>
</filter>
<filter-mapping>
    <filter-name>NtlmHttpFilter</filter-name>
    <url-pattern>/*</url-pattern>
</filter-mapping>

工作原理

1. 用戶首次訪問受保護資源，瀏覽器發起無憑證請求。
2. Filter 返回 401 Unauthorized 並攜帶 WWW-Authenticate: NTLM 標頭。
3. 瀏覽器自動回應含 NTLM 憑證的請求（無感知彈窗）。
4. Filter 向域控制器驗證憑證，成功後將遠程用戶名（DOMAIN\\user）綁定到 HttpServletRequest.getRemoteUser()。
5. 後續請求複用已建立的 NTLM 會話，無需重複握手。

獲取登錄用戶身份

在 Controller 或 Service 中即可透過標準 API 獲取域帳號：

String domainUser = request.getRemoteUser(); // 格式：DOMAIN\\username
String username = domainUser.contains("\\") ? domainUser.split("\\\\")[1] : domainUser;

常見坑點與建議

• 域控制器可達性：應用服務器必須能通過 TCP 139/445 端口訪問 DC。
• 時間同步：Kerberos/NTLM 對時間偏移極敏感，確保 NTP 同步。
• 瀏覽器支援：IE/Edge/Chrome 需將站點加入「本地內部網路」或「受信任站點」區域才會自動發送 NTLM 憑證。
• 集群環境：多節點部署時，確保所有節點均配置正確的 DC IP，或使用 DNS 轮詢。
• 升級提示：JCIFS 1.3.x 已停止維護，新專案建議改用 Jespa（商業）或 Spring Security Kerberos/SPNEGO 方案，支援更現代的 Kerberos 委派與 AES 加密。

進階：整合 Spring Security

若專案已使用 Spring Security，可直接引入 spring-security-kerberos 模組，配置 SpnegoAuthenticationProcessingFilter 替代 JCIFS Filter，獲得更豐富的授權擴展點與 Session 管理。