javax.security.auth.login
類別 LoginContext

java.lang.Object
  javax.security.auth.login.LoginContext

public class LoginContext
extends Object

LoginContext 類別描述用於驗證 Subjects 的基本方法和提供開發與底層驗證技術無關的應用程序的方法。Configuration 指定將與特定應用程序一起使用的驗證技術或 LoginModule。可以將不同的 LoginModules 插入到應用程序中而無需修改應用程序本身。

除了支持可插入 驗證之外，此類別還支持堆疊(stack)空間式 驗證的概念。可將應用程序配置為使用多於一個的 LoginModule。例如，可以在應用程序上配置 Kerberos LoginModule 和智能卡 LoginModule。

典型的調用者使用名稱 和 CallbackHandler 來實例化 LoginContext。LoginContext 使用名稱 作為 Configuration 中的索引，以確定應該使用哪些 LoginModules，並確定為了使整個驗證成功，哪些驗證是必須成功的。把 CallbackHandler 被傳遞給底層 LoginModules，因此它們可以與使用者通信和交互（例如，通過圖形使用者介面提示使用者名和密碼）。

一旦調用者已經實例化一個 LoginContext，則它會調用 login 方法對 Subject 進行驗證。login 方法調用配置的模組來執行它們各自型別的驗證（使用者名/密碼、智能卡 pin 碼驗證，等等）。注意，如果驗證失敗，則 LoginModules 不會嘗試重新進行驗證，也不會導致延遲。這類別任務屬於 LoginContext 調用者。

如果 login 方法返回而不是拋出一個異常，則整個驗證就獲得成功了。接著調用者可以通過調用 getSubject 方法來檢索新驗證的 Subject。與 Subject 關聯的 Principals 和 Credentials 可以通過分別調用 Subject 的 getPrincipals、getPublicCredentials 和 getPrivateCredentials 方法來進行檢索。

調用者可通過調用 logout 方法註銷 Subject。與對待 login 方法類似，此 logout 方法對已配置的模組調用 logout 方法。

LoginContext 不應該用於對一個以上的 Subject 進行驗證。單個 LoginContext 應該用於對每個不同的 Subject 進行驗證。

以下文檔適用於所有的 LoginContext 建構子：

1. Subject
   • 如果建構子有一個 Subject 輸入參數，則 LoginContext 使用調用者指定的 Subject 物件。

   • 如果調用者指定一個 null Subject，並且 null 值是允許的，則 LoginContext 將實例化一個新 Subject。

   • 如果建構子沒有 Subject 輸入參數，則 LoginContext 將實例化一個新 Subject。

2. Configuration
   • 如果建構子有一個 Configuration 輸入參數，並且調用者指定一個非 null Configuration，則 LoginContext 使用調用者指定的 Configuration。

     如果建構子沒有 Configuration 輸入參數，或者調用者指定一個 null Configuration 物件，則建構子使用以下調用來獲得已安裝的 Configuration：

           config = Configuration.getConfiguration();
      

     對於這兩種情況，提供給建構子的 name 參數被傳遞給 Configuration.getAppConfigurationEntry 方法。如果 Configuration 沒有用於指定 name 的條目，那麼 LoginContext 將使用名稱 "other"（預設條目名稱）調用 getAppConfigurationEntry。如果沒有用於 "other" 的條目，則拋出 LoginException。

   • 當 LoginContext 使用已安裝的 Configuration 時，調用者需要 createLoginContext.name 和 createLoginContext.other AuthPermissions（可能需要）。此外，LoginContext 將從 AccessController.doPrivileged 調用中調用已配置的模組，因此執行與安全有關的任務（例如連接到遠端主機和更新 Subject）的模組將需要各自的權限，但是 LoginContext 的調用者不需要這些權限。

   • 當 LoginContext 使用調用者指定的 Configuration 時，調用者不需要任何 createLoginContext AuthPermission。LoginContext 為調用者保存 AccessControlContext，並且從該上下文限制的 AccessController.doPrivileged 調用中調用已配置的模組。這意味著調用者上下文（在創建 LoginContext 時存儲的上下文）必須具有足夠的權限去執行該模組可以執行的任何與安全有關的任務。

3. CallbackHandler
   • 如果建構子有一個 CallbackHandler 輸入參數，則 LoginContext 將使用調用者指定的 CallbackHandler 物件。

   • 如果建構子沒有 CallbackHandler 輸入參數，或者調用者指定了一個 null CallbackHandler 物件（並且允許使用 null 值），則 LoginContext 將查詢 auth.login.defaultCallbackHandler 安全屬性來尋找預設處理程序實作的完全限定類別名稱。如果沒有設置安全屬性，則底層模組不會有一個用來與使用者通信的 CallbackHandler。調用者因此假定已配置的模組具有對使用者進行驗證的替代方法。

   • 當 LoginContext 使用安裝的 Configuration（而不是調用者指定的 Configuration，請參閱上文）時，此 LoginContext 必須在一個新 CallbackHandler 實作中包裹任何調用者指定的或預設的 CallbackHandler 實作，CallbackHandler 實作的 handle 方法的實作在由調用者的當前 AccessControlContext 限制的 java.security.AccessController.doPrivileged 調用中調用指定 CallbackHandler 的 handle 方法。

注意，Security Properties（比如 auth.login.defaultCallbackHandler）可以通過 java.security.Security 類別以程式的方式來進行設置，或者是在名為 <JAVA_HOME>/lib/security/java.security的 Java 安全屬性檔案中靜態設置的。<JAVA_HOME> 是指java.home 系統屬性的值並且指定安裝 JRE 的目錄）

另請參見：

Security, AuthPermission, Subject, CallbackHandler, Configuration, LoginModule

建構子摘要

LoginContext(String name)
使用 name 實例化一個新 LoginContext 物件。

LoginContext(String name, CallbackHandler callbackHandler)
使用 name 和 CallbackHandler 物件實例化一個新 LoginContext 物件。

LoginContext(String name, Subject subject)
使用 name 和 Subject 物件實例化一個新 LoginContext 物件。

LoginContext(String name, Subject subject, CallbackHandler callbackHandler)
使用 name、要進行驗證的 Subject 和 CallbackHandler 物件實例化一個新 LoginContext 物件。

LoginContext(String name, Subject subject, CallbackHandler callbackHandler, Configuration config)
使用 name、要進行驗證的 Subject、CallbackHandler 物件和登錄 Configuration 來實例化一個新 LoginContext 物件。

方法摘要

Subject	getSubject() 返回已進行驗證的 Subject。
void	login() 執行驗證。
void	logout() 註銷 Subject。

從類別 java.lang.Object 繼承的方法

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

建構子詳細資訊

LoginContext

public LoginContext(String name)
             throws LoginException

使用 name 實例化一個新 LoginContext 物件。

參數：

name - 用作為 Configuration 中的索引的名稱。

拋出：

LoginException - 如果調用者指定的 name 在 Configuration 中沒有出現，並且不存在用於 "other" 的 Configuration 條目，或者設置了 auth.login.defaultCallbackHandler 安全屬性，但是無法載入實作類別。

SecurityException - 如果設置了 SecurityManager，但調用者沒有 AuthPermission("createLoginContext.name") 權限，或者 name 的配置條目不存在，並且調用者沒有 AuthPermission("createLoginContext.other") 權限。

LoginContext

public LoginContext(String name,
                    Subject subject)
             throws LoginException

使用 name 和 Subject 物件實例化一個新 LoginContext 物件。

參數：

name - 用作為 Configuration 中的索引的名稱。

subject - 要進行驗證的 Subject。

拋出：

LoginException - 如果調用者指定的 name 在 Configuration 中沒有出現，並且不存在用於 "other" 的 Configuration 條目，如果調用者指定的 subject 為 null，或者設置了 auth.login.defaultCallbackHandler 安全屬性，但是不能載入實作類別。

SecurityException - 如果設置了 SecurityManager 但調用者沒有 AuthPermission("createLoginContext.name") 權限，或者 name 的配置條目不存在，並且調用者又沒有 AuthPermission("createLoginContext.other") 權限。

LoginContext

public LoginContext(String name,
                    CallbackHandler callbackHandler)
             throws LoginException

使用 name 和 CallbackHandler 物件實例化一個新 LoginContext 物件。

用作為 Configuration 中的索引的名稱。

參數：

callbackHandler - LoginModules 用來與使用者通信的 CallbackHandler 物件。

拋出：

LoginException - 如果調用者指定的 name 在 Configuration 中沒有出現，並且不存在用於 "other" 的 Configuration 條目，或者調用者指定的 callbackHandler 為 null。

SecurityException - 如果設置了 SecurityManager 但調用者沒有 AuthPermission("createLoginContext.name") 權限，或者 name 的配置條目不存在並且調用者又沒有 AuthPermission("createLoginContext.other") 權限。

LoginContext

public LoginContext(String name,
                    Subject subject,
                    CallbackHandler callbackHandler)
             throws LoginException

使用 name、要進行驗證的 Subject 和 CallbackHandler 物件實例化一個新 LoginContext 物件。

參數：

name - 用作為 Configuration 中的索引的名稱。

subject - 要進行驗證的 Subject。

callbackHandler - LoginModules 用來與使用者通信的 CallbackHandler 物件。

拋出：

LoginException - 如果調用者指定的 name 在 Configuration 中沒有出現，並且不存在用於 "other" 的 Configuration 條目，或調用者指定的 subject 為 null，或調用者指定的 callbackHandler 為 null。

SecurityException - 如果設置了 SecurityManager 但調用者沒有 AuthPermission("createLoginContext.name") 權限，或者 name 的配置條目不存在並且調用者又沒有 AuthPermission("createLoginContext.other") 權限。

LoginContext

public LoginContext(String name,
                    Subject subject,
                    CallbackHandler callbackHandler,
                    Configuration config)
             throws LoginException

使用 name、要進行驗證的 Subject、CallbackHandler 物件和登錄 Configuration 來實例化一個新 LoginContext 物件。

參數：

name - 用作為調用者指定的 Configuration 中的索引的名稱。

subject - 要進行驗證的 Subject 或 null。

callbackHandler - LoginModules 用來與使用者通信的 CallbackHandler 物件，或者為 null。

config - 列出將被調用來執行驗證的登錄模組的 Configuration，或者為 null。

拋出：

LoginException - 如果調用者指定的 name 在 Configuration 中沒有出現，並且不存在用於 "other" 的 Configuration 條目。

SecurityException - 如果設置了 SecurityManager，config 為 null，且任一個調用者都沒有 AuthPermission("createLoginContext.name") 權限，或者 name 的配置條目不存在，並且調用者又沒有 AuthPermission("createLoginContext.other") 權限。

從以下版本開始：

1.5

方法詳細資訊

login

public void login()
           throws LoginException

執行驗證。

此方法對為指定給 LoginContext 建構子的 name 配置的每個 LoginModule 調用 login 方法，由登錄 Configuration 確定。每個 LoginModule 執行各自型別的驗證（使用者名/密碼、智能卡 pin 碼驗證，等等）。

此方法完成由兩個階段組成的驗證過程，如果整個驗證成功（相關的 REQUIRED、REQUISITE、SUFFICIENT 和 OPTIONAL LoginModules 獲得成功），通過調用每個已配置的 LoginModule 的 commit 方法來完成驗證過程；如果整個驗證失敗，通過調用每個配置的 LoginModule 的 abort 方法來完成驗證過程。如果驗證成功，每個成功的 LoginModule 的 commit 方法會將相關的 Principals 和 Credentials 與 Subject 聯繫起來。如果驗證失敗，則每個 LoginModule 的 abort 方法都移除/銷毀任何以前存儲的狀態。

如果驗證過程的 commit 階段失敗，則整個驗證失敗，且此方法對每個已配置的 LoginModule 調用 abort 方法。

如果因為某種原因導致 abort 階段失敗，此方法將傳播在 login 階段或 commit 階段拋出的原始異常。在上述任何一種情況下，整個驗證都將失敗。

在多個 LoginModules 失敗的情況下，此方法傳播由第一個失敗的 LoginModule 引起的異常。

注意，如果此方法進入 abort 階段（login 或 commit 階段失敗），不管它們各自的 Configuration flag 參數如何，此方法都將調用為應用程序配置的所有 LoginModules。這實質上意味著在 abort 階段忽略 Requisite 和 Sufficient 語義。這保證能發生正確的清除和狀態恢復。

拋出：

LoginException - 如果驗證失敗。

logout

public void logout()
            throws LoginException

註銷 Subject。

此方法對為此 LoginContext 配置的每個 LoginModule 調用 logout 方法。每個 LoginModule 執行各自的註銷過程，包括移除/銷毀 Subject 的 Principal 和 Credential 資訊以及狀態清除。

注意，不管 LoginModules 的 Configuration flag 參數如何，此方法都將調用為應用程序配置的所有 LoginModules。這實質上意味著忽略此方法的 Requisite 和 Sufficient 語義。這保證能發生正確的清除和狀態恢復。

拋出：

LoginException - 如果註銷失敗。

getSubject

public Subject getSubject()

返回已進行驗證的 Subject。

返回：

已進行驗證的 Subject。如果調用者為此 LoginContext 的建構子指定一個 Subject，則此方法將返回調用者指定的 Subject。如果沒有指定 Subject 並且驗證成功，則此方法將返回由此 LoginContext 實例化且用於驗證的 Subject。如果沒有指定 Subject，並且驗證失敗或沒有試圖進行驗證，則此方法返回 null。