JavaTM Platform
Standard Ed. 6

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 的 getPrincipalsgetPublicCredentialsgetPrivateCredentials 方法来进行检索。

调用者可通过调用 logout 方法注销 Subject。与对待 login 方法类似,此 logout 方法对已配置的模块调用 logout 方法。

LoginContext 不应该用于对一个以上的 Subject 进行验证。单个 LoginContext 应该用于对每个不同的 Subject 进行验证。

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

  1. Subject
  2. Configuration
  3. CallbackHandler

注意,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、要进行验证的 SubjectCallbackHandler 对象实例化一个新 LoginContext 对象。
LoginContext(String name, Subject subject, CallbackHandler callbackHandler, Configuration config)
          使用 name、要进行验证的 SubjectCallbackHandler 对象和登录 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 - 如果调用者指定的 nameConfiguration 中没有出现,并且不存在用于 "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 - 如果调用者指定的 nameConfiguration 中没有出现,并且不存在用于 "other" 的 Configuration 条目,如果调用者指定的 subjectnull,或者设置了 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 - 如果调用者指定的 nameConfiguration 中没有出现,并且不存在用于 "other" 的 Configuration 条目,或者调用者指定的 callbackHandlernull

SecurityException - 如果设置了 SecurityManager 但调用者没有 AuthPermission("createLoginContext.name") 权限,或者 name 的配置条目不存在并且调用者又没有 AuthPermission("createLoginContext.other") 权限。

LoginContext

public LoginContext(String name,
                    Subject subject,
                    CallbackHandler callbackHandler)
             throws LoginException
使用 name、要进行验证的 SubjectCallbackHandler 对象实例化一个新 LoginContext 对象。

参数:
name - 用作为 Configuration 中的索引的名称。

subject - 要进行验证的 Subject

callbackHandler - LoginModules 用来与用户通信的 CallbackHandler 对象。
抛出:
LoginException - 如果调用者指定的 nameConfiguration 中没有出现,并且不存在用于 "other" 的 Configuration 条目,或调用者指定的 subjectnull,或调用者指定的 callbackHandlernull

SecurityException - 如果设置了 SecurityManager 但调用者没有 AuthPermission("createLoginContext.name") 权限,或者 name 的配置条目不存在并且调用者又没有 AuthPermission("createLoginContext.other") 权限。

LoginContext

public LoginContext(String name,
                    Subject subject,
                    CallbackHandler callbackHandler,
                    Configuration config)
             throws LoginException
使用 name、要进行验证的 SubjectCallbackHandler 对象和登录 Configuration 来实例化一个新 LoginContext 对象。

参数:
name - 用作为调用者指定的 Configuration 中的索引的名称。

subject - 要进行验证的 Subjectnull

callbackHandler - LoginModules 用来与用户通信的 CallbackHandler 对象,或者为 null

config - 列出将被调用来执行验证的登录模块的 Configuration,或者为 null
抛出:
LoginException - 如果调用者指定的 nameConfiguration 中没有出现,并且不存在用于 "other" 的 Configuration 条目。

SecurityException - 如果设置了 SecurityManager,confignull,且任一个调用者都没有 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 阶段(logincommit 阶段失败),不管它们各自的 Configuration flag 参数如何,此方法都将调用为应用程序配置的所有 LoginModules。这实质上意味着在 abort 阶段忽略 RequisiteSufficient 语义。这保证能发生正确的清除和状态恢复。

抛出:
LoginException - 如果验证失败。

logout

public void logout()
            throws LoginException
注销 Subject

此方法对为此 LoginContext 配置的每个 LoginModule 调用 logout 方法。每个 LoginModule 执行各自的注销过程,包括移除/销毁 SubjectPrincipalCredential 信息以及状态清除。

注意,不管 LoginModules 的 Configuration flag 参数如何,此方法都将调用为应用程序配置的所有 LoginModules。这实质上意味着忽略此方法的 RequisiteSufficient 语义。这保证能发生正确的清除和状态恢复。

抛出:
LoginException - 如果注销失败。

getSubject

public Subject getSubject()
返回已进行验证的 Subject。

返回:
已进行验证的 Subject。如果调用者为此 LoginContext 的构造方法指定一个 Subject,则此方法将返回调用者指定的 Subject。如果没有指定 Subject 并且验证成功,则此方法将返回由此 LoginContext 实例化且用于验证的 Subject。如果没有指定 Subject,并且验证失败或没有试图进行验证,则此方法返回 null。

JavaTM Platform
Standard Ed. 6

提交错误或意见
有关更多的 API 参考资料和开发人员文档,请参阅 Java SE 开发人员文档。该文档包含更详细的、面向开发人员的描述,以及总体概述、术语定义、使用技巧和工作代码示例。

版权所有 2007 Sun Microsystems, Inc. 保留所有权利。 请遵守许可证条款。另请参阅文档重新分发政策