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 殼。

• login(String, String, String)：authenticate → 互動式登入資格 → 登入政策 → 代行合併 → 簽發 access + opaque refresh
• refreshSession(String)：驗 server-side Session family → 重載當前權限重鑄（非 claim 複製）
• logout(String,String)：撤銷 Refresh Session，並短效 blacklist 目前 access family

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

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

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static final record	LoginService.LoginResult	登入結果（引擎級——wire DTO 由消費端殼自 principal／acting 組裝）
static final record	LoginService.RefreshResult	Refresh 成功後的引擎結果；replacement credential 由 HTTP 殼寫入 Cookie，不放入 wire body。

Constructor Summary

Constructors

Constructor	Description
LoginService(org.springframework.security.authentication.AuthenticationManager authenticationManager, JwtTokenProvider jwtTokenProvider, AuthPrincipalLookup principalLookup, TokenBlacklistStore tokenBlacklistStore, Optional<LoginActingContributor> actingContributor, Optional<LoginPolicy> loginPolicy)	建構子（全部參數皆可由 Spring 建構子注入解析）
LoginService(org.springframework.security.authentication.AuthenticationManager authenticationManager, JwtTokenProvider jwtTokenProvider, AuthPrincipalLookup principalLookup, TokenBlacklistStore tokenBlacklistStore, Optional<LoginActingContributor> actingContributor, Optional<LoginPolicy> loginPolicy, RefreshSessionStore refreshSessionStore, RefreshCredentialCodec refreshCredentialCodec, Clock clock, SessionOptions defaultSessionOptions)	建立使用 server-side Refresh Session 的登入引擎。
LoginService(org.springframework.security.authentication.AuthenticationManager authenticationManager, JwtTokenProvider jwtTokenProvider, AuthPrincipalLookup principalLookup, TokenBlacklistStore tokenBlacklistStore, Optional<LoginActingContributor> actingContributor, Optional<LoginPolicy> loginPolicy, RefreshSessionStore refreshSessionStore, RefreshCredentialCodec refreshCredentialCodec, Clock clock, SessionOptions defaultSessionOptions, RefreshSessionRotationMode refreshSessionRotationMode)	建立可明示 Refresh Credential 使用協定的 server-side Refresh Session 登入引擎。
LoginService(org.springframework.security.authentication.AuthenticationManager authenticationManager, JwtTokenProvider jwtTokenProvider, AuthPrincipalLookup principalLookup, TokenBlacklistStore tokenBlacklistStore, Optional<LoginActingContributor> actingContributor, Optional<LoginPolicy> loginPolicy, RefreshSessionStore refreshSessionStore, RefreshCredentialCodec refreshCredentialCodec, Clock clock, SessionOptions defaultSessionOptions, RefreshSessionRotationMode refreshSessionRotationMode, Optional<SessionEligibilityPolicy> sessionEligibilityPolicy)	建立具 refresh-time 應用政策重新驗證的登入引擎。
LoginService(org.springframework.security.authentication.AuthenticationManager authenticationManager, JwtTokenProvider jwtTokenProvider, AuthPrincipalLookup principalLookup, TokenBlacklistStore tokenBlacklistStore, Optional<LoginActingContributor> actingContributor, Optional<LoginPolicy> loginPolicy, RefreshSessionStore refreshSessionStore, RefreshCredentialCodec refreshCredentialCodec, Clock clock, SessionOptions defaultSessionOptions, RefreshSessionRotationMode rotationMode, Optional<SessionEligibilityPolicy> eligibilityPolicy, Optional<SessionContextPolicy> contextPolicy)	可選的憑證環境綁定；舊建構子保留單一入口語意。
LoginService(org.springframework.security.authentication.AuthenticationManager manager, JwtTokenProvider provider, AuthPrincipalLookup lookup, TokenBlacklistStore blacklist, Optional<LoginActingContributor> acting, Optional<LoginPolicy> policy, RefreshSessionStore store, RefreshCredentialCodec codec, Clock clock, SessionOptions defaults, RefreshSessionRotationMode rotation, Optional<SessionEligibilityPolicy> eligibility, Optional<SessionContextPolicy> context, SessionFamilyProfile profile, SessionPrincipalRegistry principals)	opt-in 的 bounded profile；引擎、resource filter 必須共用 profile／store／Clock。

Method Summary

Modifier and Type	Method	Description
LoginService.RefreshResult	activateSession(String credential, String context, String app)	只接受 pending credential；重複／錯入口／錯 app 不得進入 refresh replay 撤銷路徑。 應用須在同一 transaction 包住 activation 與 refresh，政策拒絕時一起 rollback。
SessionMetadata	describe(LoginService.LoginResult issued)
SessionMetadata	describe(LoginService.RefreshResult refreshed)
LoginService.LoginResult	exitImpersonation(String currentRefreshCredential, AuthPrincipal actor, String app)	結束 impersonation，沿用目前 family 的 remember/idle policy 換回 actor。
LoginService.LoginResult	exitImpersonation(String currentRefreshCredential, AuthPrincipal actor, String app, SessionPolicyBinding targetBinding)
LoginService.LoginResult	issue(AuthPrincipal principal, String app)	為已由外部協定驗證完成的主體建立 app session。
LoginService.LoginResult	issue(AuthPrincipal principal, String app, SessionOptions sessionOptions)
LoginService.LoginResult	issue(AuthPrincipal principal, String app, SessionOptions options, SessionPolicyBinding binding)
LoginService.LoginResult	issue(AuthPrincipal principal, String app, SessionOptions options, SessionPolicyBinding binding, SessionIssuanceContext issuanceContext)
LoginService.LoginResult	login(String username, String password, String app)	登入：authenticate → 互動式登入資格 → 登入政策 → 代行合併 → 簽發
LoginService.LoginResult	login(String username, String password, String app, SessionOptions sessionOptions)
LoginService.LoginResult	login(org.springframework.security.core.Authentication authenticationRequest, String app)	以應用建立的 credential token 登入。
LoginService.LoginResult	login(org.springframework.security.core.Authentication authenticationRequest, String app, SessionOptions sessionOptions)
LoginService.LoginResult	login(org.springframework.security.core.Authentication request, String app, SessionOptions options, SessionPolicyBinding binding)
LoginService.LoginResult	login(org.springframework.security.core.Authentication request, String app, SessionOptions options, SessionPolicyBinding binding, SessionIssuanceContext issuanceContext)	HTTP 殼須在同一 store transaction 內執行發行及 replacement，commit 後才寫 Cookie。
void	logout(String token)	登出：把 token 的 session 加入黑名單（同時失效 access 與 refresh token）並清除 context
void	logout(String accessToken, String refreshCredential)	登出並撤銷 server-side Session family；Access Token blacklist 只保留即時撤銷用途。
void	logout(String accessToken, String credential, UUID expectedFamilyId)	fence 檢查失敗不碰 Cookie／family；HTTP 殼僅在成功或明確 401 時依契約清 Cookie。
String	refresh(String refreshToken)	Deprecated.
LoginService.RefreshResult	refreshSession(String refreshCredential)	以 opaque credential 驗證 Refresh Session，並依目前 principal 重鑄 Access Token。
LoginService.RefreshResult	refreshSession(String refreshCredential, UUID expectedFamilyId)
int	revokeSessionsByPolicy(String policy, String reference, String reason)	依應用政策識別主動撤銷所有相符 family，並立即 blacklist 其 Access Token family。
int	revokeSessionsByPrincipal(String subject, String reason)	受保護的帳號管理 orchestration；subject 必須先由應用映射為 immutable account ID。
LoginService.LoginResult	switchToImpersonation(String currentRefreshCredential, AuthPrincipal target, String actorSubject, String app)	以目前 Session policy 切換到純 impersonation Session family。 current family 必須屬於 actor，且不可已在 impersonation 中。
LoginService.LoginResult	switchToImpersonation(String currentRefreshCredential, AuthPrincipal target, String actorSubject, String app, SessionOptions sessionOptions, SessionPolicyBinding policyBinding)	以明確 Session policy 與產品政策綁定切換到純 impersonation family。
LoginService.LoginResult	switchToImpersonation(String currentRefreshCredential, AuthPrincipal target, String actorSubject, String app, SessionPolicyBinding policyBinding)	沿用目前 family 的 remember／idle policy，並綁定 refresh-time 應用政策。

Methods inherited from class Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

LoginService

@Autowired
public LoginService(org.springframework.security.authentication.AuthenticationManager authenticationManager,
 JwtTokenProvider jwtTokenProvider,
 AuthPrincipalLookup principalLookup,
 TokenBlacklistStore tokenBlacklistStore,
 Optional<LoginActingContributor> actingContributor,
 Optional<LoginPolicy> loginPolicy)

建構子（全部參數皆可由 Spring 建構子注入解析）

Parameters:

authenticationManager - 帳密認證（消費端組裝，含鎖定等 provider 堆疊）

jwtTokenProvider - token 簽發與解析

principalLookup - 主體查找 SPI

tokenBlacklistStore - session 黑名單儲存

actingContributor - 代行貢獻點；無 bean 時 empty

loginPolicy - 登入把關政策；無 bean 時 empty ＝ 放行

LoginService

public LoginService(org.springframework.security.authentication.AuthenticationManager authenticationManager,
 JwtTokenProvider jwtTokenProvider,
 AuthPrincipalLookup principalLookup,
 TokenBlacklistStore tokenBlacklistStore,
 Optional<LoginActingContributor> actingContributor,
 Optional<LoginPolicy> loginPolicy,
 RefreshSessionStore refreshSessionStore,
 RefreshCredentialCodec refreshCredentialCodec,
 Clock clock,
 SessionOptions defaultSessionOptions)

建立使用 server-side Refresh Session 的登入引擎。

Parameters:

refreshSessionStore - 持久化 Session family 的 app-owned adapter

refreshCredentialCodec - opaque credential 產生／雜湊 primitive

clock - 可測試的應用時鐘

defaultSessionOptions - 舊簽章入口未明示 policy 時使用的產品預設

LoginService

public LoginService(org.springframework.security.authentication.AuthenticationManager authenticationManager,
 JwtTokenProvider jwtTokenProvider,
 AuthPrincipalLookup principalLookup,
 TokenBlacklistStore tokenBlacklistStore,
 Optional<LoginActingContributor> actingContributor,
 Optional<LoginPolicy> loginPolicy,
 RefreshSessionStore refreshSessionStore,
 RefreshCredentialCodec refreshCredentialCodec,
 Clock clock,
 SessionOptions defaultSessionOptions,
 RefreshSessionRotationMode refreshSessionRotationMode)

建立可明示 Refresh Credential 使用協定的 server-side Refresh Session 登入引擎。

RefreshSessionRotationMode.REUSABLE 只應由消費端在開發環境明確啟用；框架本身不推測 部署環境，production-safe 驗證由擁有環境設定的 app 組裝層負責。

LoginService

public LoginService(org.springframework.security.authentication.AuthenticationManager authenticationManager,
 JwtTokenProvider jwtTokenProvider,
 AuthPrincipalLookup principalLookup,
 TokenBlacklistStore tokenBlacklistStore,
 Optional<LoginActingContributor> actingContributor,
 Optional<LoginPolicy> loginPolicy,
 RefreshSessionStore refreshSessionStore,
 RefreshCredentialCodec refreshCredentialCodec,
 Clock clock,
 SessionOptions defaultSessionOptions,
 RefreshSessionRotationMode refreshSessionRotationMode,
 Optional<SessionEligibilityPolicy> sessionEligibilityPolicy)

建立具 refresh-time 應用政策重新驗證的登入引擎。

LoginService

public LoginService(org.springframework.security.authentication.AuthenticationManager authenticationManager,
 JwtTokenProvider jwtTokenProvider,
 AuthPrincipalLookup principalLookup,
 TokenBlacklistStore tokenBlacklistStore,
 Optional<LoginActingContributor> actingContributor,
 Optional<LoginPolicy> loginPolicy,
 RefreshSessionStore refreshSessionStore,
 RefreshCredentialCodec refreshCredentialCodec,
 Clock clock,
 SessionOptions defaultSessionOptions,
 RefreshSessionRotationMode rotationMode,
 Optional<SessionEligibilityPolicy> eligibilityPolicy,
 Optional<SessionContextPolicy> contextPolicy)

可選的憑證環境綁定；舊建構子保留單一入口語意。

LoginService

public LoginService(org.springframework.security.authentication.AuthenticationManager manager,
 JwtTokenProvider provider,
 AuthPrincipalLookup lookup,
 TokenBlacklistStore blacklist,
 Optional<LoginActingContributor> acting,
 Optional<LoginPolicy> policy,
 RefreshSessionStore store,
 RefreshCredentialCodec codec,
 Clock clock,
 SessionOptions defaults,
 RefreshSessionRotationMode rotation,
 Optional<SessionEligibilityPolicy> eligibility,
 Optional<SessionContextPolicy> context,
 SessionFamilyProfile profile,
 SessionPrincipalRegistry principals)

opt-in 的 bounded profile；引擎、resource filter 必須共用 profile／store／Clock。

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)

login

public LoginService.LoginResult login(org.springframework.security.core.Authentication request,
 String app,
 SessionOptions options,
 SessionPolicyBinding binding)

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)

login

public LoginService.LoginResult login(org.springframework.security.core.Authentication request,
 String app,
 SessionOptions options,
 SessionPolicyBinding binding,
 SessionIssuanceContext issuanceContext)

HTTP 殼須在同一 store transaction 內執行發行及 replacement，commit 後才寫 Cookie。

issue

public LoginService.LoginResult issue(AuthPrincipal principal,
 String app,
 SessionOptions options,
 SessionPolicyBinding binding,
 SessionIssuanceContext issuanceContext)

issue

public LoginService.LoginResult issue(AuthPrincipal principal,
 String app,
 SessionOptions options,
 SessionPolicyBinding binding)

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。

exitImpersonation

public LoginService.LoginResult exitImpersonation(String currentRefreshCredential,
 AuthPrincipal actor,
 String app,
 SessionPolicyBinding targetBinding)

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。

refreshSession

public LoginService.RefreshResult refreshSession(String refreshCredential,
 UUID expectedFamilyId)

activateSession

public LoginService.RefreshResult activateSession(String credential,
 String context,
 String app)

只接受 pending credential；重複／錯入口／錯 app 不得進入 refresh replay 撤銷路徑。 應用須在同一 transaction 包住 activation 與 refresh，政策拒絕時一起 rollback。

revokeSessionsByPolicy

public int revokeSessionsByPolicy(String policy,
 String reference,
 String reason)

依應用政策識別主動撤銷所有相符 family，並立即 blacklist 其 Access Token family。

revokeSessionsByPrincipal

public int revokeSessionsByPrincipal(String subject,
 String reason)

受保護的帳號管理 orchestration；subject 必須先由應用映射為 immutable account ID。

describe

public SessionMetadata describe(LoginService.LoginResult issued)

describe

public SessionMetadata describe(LoginService.RefreshResult refreshed)

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

logout

public void logout(String accessToken,
 String credential,
 UUID expectedFamilyId)

fence 檢查失敗不碰 Cookie／family；HTTP 殼僅在成功或明確 401 時依契約清 Cookie。