javax.security.auth.login
类 LoginContext

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

public class LoginContext
extends Object

LoginContext 类描述用于验证 Subjects 的基本方法和提供开发与基础身份验证技术无关的应用程序的方法。Configuration 指定将与特定应用程序一起使用的身份验证技术或 LoginModule。可以将不同的 LoginModules 插入到应用程序中而无需修改应用程序本身。

除了支持可插入 身份验证之外，此类还支持堆栈式 身份验证的概念。可将应用程序配置为使用多于一个的 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_HOME> 指的是 JDK 的安装目录）的 Java 安全属性文件中静态设置的。

另请参见：

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。