模块 java.base

包 javax.security.auth.login

类 LoginContext

java.lang.Object

javax.security.auth.login.LoginContext

public class LoginContext extends Object 
      

LoginContext 类描述了用于对 Subject 进行身份验证的基本方法，并提供了一种开发独立于底层身份验证技术的应用程序的方法。 Configuration 指定要与特定应用程序一起使用的身份验证技术或 LoginModule 。可以在应用程序下插入不同的登录模块，而无需对应用程序本身进行任何修改。

除了支持可插拔身份验证，此类还支持的概念堆叠的验证。应用程序可以配置为使用多个 LoginModule。例如，可以在应用程序下同时配置 Kerberos LoginModule 和智能卡 LoginModule。

一个典型的调用者用一个实例化一个 LoginContextname和一个 CallbackHandler 。 LoginContext 使用name作为 Configuration 的索引，以确定应使用哪些 LoginModule，以及哪些必须成功才能使整体身份验证成功。 CallbackHandler 被传递给底层的登录模块，因此它们可以与用户进行通信和交互（例如，通过图形用户界面提示输入用户名和密码）。

一旦调用者实例化了 LoginContext，它就会调用 login 方法来验证 Subject。 login 方法调用配置的模块来执行它们各自类型的身份验证（用户名/密码、智能卡密码验证等）。请注意，如果身份验证失败，LoginModule 将不会尝试重试身份验证，也不会引入延迟。此类任务属于 LoginContext 调用方。

如果login方法没有抛出异常返回，则整体认证成功。然后，调用者可以通过调用 getSubject 方法来检索新认证的 Subject。可以通过调用主题各自的 getPrincipals 、 getPublicCredentials 和 getPrivateCredentials 方法来检索与主题关联的主体和凭证。

要注销 Subject，调用者调用 logout 方法。与 login 方法一样，此 logout 方法为配置的模块调用 logout 方法。

一个 LoginContext 不应该用于验证多个 Subject。应该使用单独的LoginContext 来验证每个不同的主题。

以下文档适用于所有 LoginContext 构造方法：

1. Subject
   • 如果构造方法具有 Subject 输入参数，则 LoginContext 使用调用者指定的 Subject 对象。
   • 如果调用者指定 null Subject 并且允许使用 null 值，则 LoginContext 实例化一个新的 Subject。
   • 如果构造方法确实not有一个 Subject 输入参数，LoginContext 实例化一个新的 Subject。
2. Configuration
   • 如果构造方法有一个 Configuration 输入参数并且调用者指定了一个非 null Configuration，则 LoginContext 使用调用者指定的 Configuration。

     如果构造方法确实not有一个 Configuration 输入参数，或者如果调用者指定一个 null Configuration 对象，则构造函数使用以下调用来获取已安装的 Configuration：

        config = Configuration.getConfiguration();
      

     对于这两种情况，name给构造函数的参数传递给Configuration.getAppConfigurationEntry方法。如果配置没有指定的条目name，然后 LoginContext 以名称调用 getAppConfigurationEntry，“其他"（默认条目名称）。如果没有条目“其他"，然后抛出一个 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 对象。
   • 如果构造方法确实not有一个 CallbackHandler 输入参数，或者如果调用者指定了一个 nullCallbackHandler 对象（并且允许一个 null 值），则 LoginContext 查询 auth.login.defaultCallbackHandler 安全属性以获取默认处理程序实现的完全限定类名。如果未设置安全属性，则底层模块将没有用于与用户通信的 CallbackHandler。因此，调用者假定配置的模块具有用于验证用户的替代方法。
   • 当 LoginContext 使用已安装的 Configuration（而不是调用者指定的 Configuration，见上文）时，此 LoginContext 必须将任何调用者指定的或默认的 CallbackHandler 实现包装在新的 CallbackHandler 实现中，其 handle 方法实现调用指定的 CallbackHandler 的 handle 方法java.security.AccessController.doPrivileged 呼叫受呼叫者当前 AccessControlContext 限制。

自从：

1.4

参见：

• Security
• AuthPermission
• Subject
• CallbackHandler
• Configuration
• LoginModule
• security properties

构造方法总结

构造方法

构造方法	描述
LoginContext(String name)	使用名称实例化一个新的 LoginContext 对象。
LoginContext(String name, CallbackHandler callbackHandler)	使用名称和 CallbackHandler 对象实例化一个新的 LoginContext 对象。
LoginContext(String name, Subject subject)	使用名称和 Subject 对象实例化一个新的 LoginContext 对象。
LoginContext(String name, Subject subject, CallbackHandler callbackHandler)	实例化一个新的 LoginContext 对象，其中包含一个名称、一个要进行身份验证的 Subject 和一个 CallbackHandler 对象。
LoginContext(String name, Subject subject, CallbackHandler callbackHandler, Configuration config)	使用名称、要验证的 Subject、CallbackHandler 对象和登录名 Configuration 实例化一个新的 LoginContext 对象。

方法总结

修饰符和类型	方法	描述
Subject	getSubject()	返回经过身份验证的主题。
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 
            

使用名称实例化一个新的 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 
            

使用名称和 Subject 对象实例化一个新的 LoginContext 对象。

参数：

name - 用作 Configuration 索引的名称。

subject - Subject 进行身份验证。

抛出：

LoginException - 如果调用者指定的 name 没有出现在 Configuration 中并且没有 Configuration 条目“其他"，如果调用者指定的 subject 是 null ，或者如果auth.login.defaultCallbackHandler设置了安全属性，但无法加载实现类。

SecurityException - 如果设置了 SecurityManager 并且调用者没有 AuthPermission("createLoginContext.name“），或者如果一个配置条目name不存在并且调用者没有额外的 AuthPermission("createLoginContext.other")

LoginContext

public LoginContext(String  name, CallbackHandler  callbackHandler) throws LoginException 
            

使用名称和 CallbackHandler 对象实例化一个新的 LoginContext 对象。

参数：

name - 用作 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 
            

实例化一个新的 LoginContext 对象，其中包含一个名称、一个要进行身份验证的 Subject 和一个 CallbackHandler 对象。

参数：

name - 用作 Configuration 索引的名称。

subject - Subject 进行身份验证。

callbackHandler - LoginModules 用来与用户通信的 CallbackHandler 对象。

抛出：

LoginException - 如果调用者指定的 name 没有出现在 Configuration 中并且没有 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 
            

使用名称、要验证的 Subject、CallbackHandler 对象和登录名 Configuration 实例化一个新的 LoginContext 对象。

参数：

name - 用作调用者指定的 Configuration 的索引的名称。

subject - 要进行身份验证的 Subject，或 null。

callbackHandler - LoginModules 用于与用户通信的 CallbackHandler 对象，或 null 。

config - 列出要调用以执行身份验证的登录模块的 Configuration，或 null。

抛出：

LoginException - 如果调用者指定的 name 没有出现在 Configuration 中并且没有 Configuration 条目“其他".

SecurityException - 如果设置了 SecurityManager，config是 null ，并且调用者没有 AuthPermission("createLoginContext.name“），或者如果一个配置条目name不存在并且调用者没有额外的 AuthPermission("createLoginContext.other")

自从：

1.5

方法详情

login

public void login() throws LoginException 
            

进行鉴权。

此方法为为name指定给 LoginContext 构造函数，由登录名 Configuration 确定。每个 LoginModule 然后执行其各自类型的身份验证（用户名/密码、智能卡密码验证等）。

如果整体认证成功（相关的 REQUIRED、REQUISITE、SUFFICIENT 和 OPTIONAL LoginModule 成功），此方法通过调用每个配置的 LoginModule 的 commit 方法来完成 2 阶段认证过程，或者如果整体认证失败，则调用每个配置的 LoginModule 的 abort 方法。如果身份验证成功，每个成功的 LoginModule 的 commit 方法都会将相关的 Principals 和 Credentials 与 Subject 相关联。如果身份验证失败，每个 LoginModule 的 abort 方法都会删除/销毁任何先前存储的状态。

如果身份验证过程的 commit 阶段失败，则整体身份验证失败，并且此方法为每个配置的 LoginModule 调用 abort 方法。

如果 abort 阶段因任何原因失败，则此方法传播在 login 阶段或 commit 阶段抛出的原始异常。在任何一种情况下，整体身份验证都会失败。

在多个 LoginModule 失败的情况下，此方法传播第一个失败的 LoginModule 引发的异常。

请注意，如果此方法进入 abort 阶段（login 或 commit 阶段失败），则此方法将调用为应用程序配置的所有登录模块，而不管它们各自的 Configuration 标志参数。本质上，这意味着 Requisite 和 Sufficient 语义在 abort 阶段被忽略。这保证可以进行适当的清理和状态恢复。

抛出：

LoginException - 如果身份验证失败。

logout

public void logout() throws LoginException 
            

注销 Subject 。

此方法为为此 LoginContext 配置的每个 LoginModule 调用 logout 方法。每个 LoginModule 执行其各自的注销程序，其中可能包括从 Subject 和状态清理中删除/销毁 Principal 和 Credential 信息。

请注意，此方法会调用为应用程序配置的所有 LoginModule，而不管它们各自的 Configuration 标志参数如何。本质上，这意味着此方法忽略了 Requisite 和 Sufficient 语义。这保证可以进行适当的清理和状态恢复。

抛出：

LoginException - 如果注销失败。

getSubject

public Subject  getSubject()
            

返回经过身份验证的主题。

返回：

经过身份验证的主题。如果调用者为此 LoginContext 的构造方法指定了 Subject，则此方法返回调用者指定的 Subject。如果未指定 Subject 且身份验证成功，则此方法返回此 LoginContext 实例化并用于身份验证的 Subject。如果未指定 Subject，并且身份验证失败或尚未尝试，则此方法返回 null。