ドキュメント
フレームワーク
Spring
Spring Security

Spring Security

spring-boot-starter-security

  • 預設情況下會攔截所有請求。
  • 提供基於帳號密碼的登入頁面。
  • 核心路徑: POST /login
  flowchart TD
    UP[User/Password]
    OF1[其他過濾器 1]
    AF[UsernamePassword AuthenticationFilter]
    OF2[其他過濾器 2]

    UP ---> OF1 ---> AF ---> OF2

Custom Authentication Schema (自定義認證架構)

  • 資料庫 (InDatabase) / 記憶體 (InMemory)
  • OAuth2 / OIDC (Google, GitHub 登入)
  • LDAP
  • 自定義認證機制 …

為了整合這些來源 🔽

Authentication Provider (認證提供者)

負責具體的認證邏輯 (例如比對資料庫密碼)。

  flowchart TB
    subgraph Providers
    DAP[Dao Authentication Provider]
    OAP[OAuth2Login Authentication Provider]
    LDAP[Ldap Authentication Provider]
    other[...]
    end

Authentication Manager (認證管理器)

管理多個 Provider。它會遍歷所有 Provider，詢問哪一個支援當前的認證請求。 這是透過各個 Provider 實作的 supports 方法來達成的。

  flowchart TB
    subgraph Authentication_Manager
    PM[Provider Manager]
    end

    subgraph Providers
    DAP[Dao Authentication Provider]
    OAP[OAuth2Login Authentication Provider]
    LDAP[Ldap Authentication Provider]
    other[...]
    end

    prod[Production DB]
    local[Local DB]

    Authentication_Manager ==> Providers

    Providers ====>|Authentication Checks| prod
    Providers ====>|Authentication Checks| local

UserDetails Service

  • loadUserByUsername(): 從指定的資料源獲取用戶詳細資訊。
  flowchart TB
    subgraph UserDetailsService
    MemUDM[InMemory UserDetails Manager]
    JdbcUDM[JDBC UserDetails Manager]
    LdapUDM[LDAP UserDetails Manager]
    other[...]
    end

PasswordEncoder (密碼編碼器)

  • 嚴禁明文存儲: 密碼必須經過雜湊 (Hash) 處理。
  flowchart LR
    subgraph Encoder
    bc[BCrypt]
    ar2[Argon2]
    other[...]
    end

SecurityContextHolder

  • 認證成功後，Spring 會將 Authentication 物件存入 SecurityContext。
  • SecurityContextHolder 是一個包裝類別，用於在當前執行緒中存取 Context。
  flowchart LR
    subgraph SecurityContextHolder
        subgraph SecurityContext
        prin[Principle]
        end
    end

Flow Overview (流程總覽)

使用 Session (工作階段)

認證成功後，下一次請求時，SecurityContextHolderFilter 會嘗試從 Session 中加載用戶資訊。如果成功，則不需要重新認證。

  flowchart TB
    CI[Client Login]
    UP[User/Password]
    OF1[SecurityContextHolder Filter]
    UPAF[UsernamePassword AuthenticationFilter]
    OF2[Other Filter 2]

    subgraph Authentication_Token
    UPAT[Username Password Authentication Token]
    end

    subgraph Authentication_Manager
    PM[Provider Manager]
    end

    subgraph Encoder
    bc[BCrypt]
    ar2[Argon2]
    other[...]
    end

    subgraph Providers
    DAP[Dao Authentication Provider]
    OAP[OAuth2Login Authentication Provider]
    LDAP[Ldap Authentication Provider]
    other[...]
    end

    subgraph UserDetailsService
    UserDS[...]
    end

    CI --->|1.| UP --->|2.| OF1 --->|3.| UPAF --->|Done| OF2

    UPAF ---> UPAT ---> Authentication_Manager ----> Providers
    Encoder ---> Providers
    Providers ----> UserDetailsService
    Providers ---->|Return Authentication Object| Authentication_Manager
    Authentication_Manager ----> UPAF ---->|Store in Context| SecurityContext

使用 JWT (無狀態認證)

認證資訊封裝在 JWT Token 中。每次請求都需驗證簽名，具有良好的擴展性。

發生錯誤時的流程

  • 根據配置拋出異常，由 ExceptionTranslationFilter 處理。
  flowchart TB
    CI[Client Login]
    UP[User/Password]
    OF1[SecurityContextHolder Filter]
    UPAF[UsernamePassword AuthenticationFilter]
    EF[Exception TranslationFilter]

    CI ---> UP ---> OF1 ---> UPAF --->|Throw Exception| EF

Glossary (術語表)

  • Principal: 當前執行的用戶或系統實體。
  • Authentication (認證): 驗證用戶身份的真偽（你是誰？）。
  • Authorization (授權): 判定已認證用戶是否擁有執行特定操作的權限（你能做什麼？）。
  • GrantedAuthority: 授予 Principal 的特定權限（如 ROLE_ADMIN）。
  • SecurityContext: 存儲當前認證資訊的容器。
  • SecurityContextHolder: 提供對 SecurityContext 存取的入口。

OAuth 2.0 流程

OAuth 2.0 協議流程

Authorization Code Flow

Implicit Flow

OAuth 2.0 Playground 範例

以下是使用 OAuth 2.0 Playground 進行 Authorization Code Flow 的步驟：