Class LoginService

java.lang.Object
io.leandev.appfuse.security.auth.LoginService
public class LoginService extends Object

登入引擎 capability（ADR-023）

login／refresh／logout 三操作的 orchestration。對帳號的全部需求以 AuthPrincipal 契約 ＋ AuthPrincipalLookup SPI 表達，不假設任何帳號結構；wire 面（HTTP mapping、DTO 形狀、例外 → RFC 7807 映射、使用者資訊查詢）歸消費端的 HTTP 殼。

預期的 credential rejection 以保留實際原因的 AuthenticationException 家族表達；HTTP 揭露程度由消費端最後的 response policy 決定，基礎設施例外不得偽裝成 Session 失效。租戶 claim 經 TenantAwareUserDetails 探詢——principal 未實作即無租戶 claim。

組合：jar 不做 autoconfiguration（ADR-014），由消費端的組態（參考實作為 AuthInfrastructureConfig）以 @Bean 建立本類；全部依賴皆可由 Spring 建構子注入解析 （Optional<T> 依賴無 bean 時為 empty）。

  • Constructor Details

  • Method Details

    • login

      public LoginService.LoginResult login(String username, String password, String app)
      登入：authenticate → 互動式登入資格 → 登入政策 → 代行合併 → 簽發
      Parameters:
      username - 登入身分識別子
      password - 密碼
      app - 來源前端識別（登入政策用；可為 null）
      Throws:
      org.springframework.security.core.AuthenticationException - 認證、資格或政策拒絕；實際原因原樣傳播至 response policy

    • login

      public LoginService.LoginResult login(String username, String password, String app, SessionOptions sessionOptions)

    • login

      public LoginService.LoginResult login(org.springframework.security.core.Authentication authenticationRequest, String app)

      以應用建立的 credential token 登入。

      應用的 wire model 若需要額外範圍（例如 tenant + username），應先解析成自己的 Authentication request，再交給本方法；登入引擎因此不需要認識 tenant 或 DTO。

    • login

      public LoginService.LoginResult login(org.springframework.security.core.Authentication authenticationRequest, String app, SessionOptions sessionOptions)

    • issue

      public LoginService.LoginResult issue(AuthPrincipal principal, String app)

      為已由外部協定驗證完成的主體建立 app session。

      OIDC callback 先驗證 IdP response、完成 ExternalIdentity → Account 映射，再以本方法 簽發與 local login 完全相同的 app access token／opaque Refresh Credential。 主 API 因而只需信任 app JWT。

    • issue

      public LoginService.LoginResult issue(AuthPrincipal principal, String app, SessionOptions sessionOptions)

    • switchToImpersonation

      public LoginService.LoginResult switchToImpersonation(String currentRefreshCredential, AuthPrincipal target, String actorSubject, String app)
      以目前 Session policy 切換到純 impersonation Session family。 current family 必須屬於 actor，且不可已在 impersonation 中。

    • switchToImpersonation

      public LoginService.LoginResult switchToImpersonation(String currentRefreshCredential, AuthPrincipal target, String actorSubject, String app, SessionPolicyBinding policyBinding)
      沿用目前 family 的 remember／idle policy，並綁定 refresh-time 應用政策。

    • switchToImpersonation

      public LoginService.LoginResult switchToImpersonation(String currentRefreshCredential, AuthPrincipal target, String actorSubject, String app, SessionOptions sessionOptions, SessionPolicyBinding policyBinding)

      以明確 Session policy 與產品政策綁定切換到純 impersonation family。

      sessionOptions 可把 break-glass family 限縮為短效 non-remembered Session； policyBinding 會隨 family 保存並於每次 refresh 重新驗證。

    • exitImpersonation

      public LoginService.LoginResult exitImpersonation(String currentRefreshCredential, AuthPrincipal actor, String app)
      結束 impersonation，沿用目前 family 的 remember/idle policy 換回 actor。

    • refreshSession

      public LoginService.RefreshResult refreshSession(String refreshCredential)

      以 opaque credential 驗證 Refresh Session，並依目前 principal 重鑄 Access Token。

      STRICT 成功回應輪替 credential；client 必須先以同源跨分頁鎖序列化 refresh。秘密 selector 讓舊 verifier 仍能定位 family，atomic compare-and-rotate 衝突即視為 replay 並 撤銷 family。REUSABLE 不輪替 credential，改以原子 credential-use 滑動 idle window，供 開發環境中無法共用 Web Lock 的 localhost origins 使用。Store／lookup 的基礎設施例外 原樣傳播，只有明確 Session rejection 轉為 BadCredentialsException。

    • revokeSessionsByPolicy

      public int revokeSessionsByPolicy(String policy, String reference, String reason)
      依應用政策識別主動撤銷所有相符 family，並立即 blacklist 其 Access Token family。

    • refresh

      @Deprecated public String refresh(String refreshToken)
      Deprecated.
      刷新 access token：驗證 → 黑名單檢查 → 重載當前權限重鑄
      Returns:
      新的 access token（帶最新 authorities）
      Throws:
      org.springframework.security.authentication.BadCredentialsException - session 已撤銷（Session has been revoked）
      RefreshSessionRejectedException - token subject 查無或主體不符合 refresh 資格；訊息保留實際原因 其他底層例外原樣上拋，消費端不得映為 credential rejection

    • logout

      public void logout(String token)
      登出：把 token 的 session 加入黑名單（同時失效 access 與 refresh token）並清除 context
      Parameters:
      token - 存取 token；null 表示呼叫端未附 token（僅清 context）

    • logout

      public void logout(String accessToken, String refreshCredential)
      登出並撤銷 server-side Session family；Access Token blacklist 只保留即時撤銷用途。
      Parameters:
      accessToken - 目前 access token，可為 null
      refreshCredential - opaque refresh credential，可為 null；缺 access token 時可據此找 family