|
|||||||||
摘要: 嵌套 | 字段 | 构造方法 | 方法 | 详细信息: 字段 | 构造方法 | 方法 |
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 构造方法:
Subject
- 如果构造方法有一个 Subject 输入参数,则 LoginContext 使用调用方指定的 Subject 对象。
- 如果调用方指定一个
null
Subject,并且null
值是允许的,则 LoginContext 将实例化一个新 Subject。 - 如果构造方法没有 Subject 输入参数,则 LoginContext 将实例化一个新 Subject。
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 时存储的上下文)必须具有足够的权限去执行该模块可以执行的任何与安全有关的任务。
- 如果构造方法有一个 Configuration 输入参数,并且调用方指定一个非 null Configuration,则 LoginContext 使用调用方指定的 Configuration。
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 安全属性文件中静态设置的。
构造方法摘要 | |
---|---|
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。