compact1, compact2, compact3

javax.security.auth.login

Class LoginContext

java.lang.Object

javax.security.auth.login.LoginContext

public class LoginContext
extends Object

LoginContext类描述了用于验证主题的基本方法，并提供了独立于底层认证技术开发应用程序的方法。 甲Configuration指定认证技术，或LoginModule ，与特定应用中使用。 可以在应用程序下插入不同的LoginModules，而不需要对应用程序本身进行任何修改。

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

一个典型的调用者用一个名字来实例化一个LoginContext，一个CallbackHandler 。 LoginContext使用名称作为索引到配置中，以确定应使用哪个LoginModule，以及哪些必须成功才能使整体身份验证成功。 CallbackHandler被传递到底层的LoginModules，以便它们可以与用户进行通信和交互（例如通过图形用户界面提示用户名和密码）。

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

如果login方法返回而不抛出异常，那么整体认证成功。 呼叫者可以通过调用getSubject方法来检索新认证的主题。 与Subject相关的Principals和Credentials可以通过调用主题的各个被检索getPrincipals ， getPublicCredentials和getPrivateCredentials方法。

要退出主题，主叫方将呼叫logout方法。 与login方法一样，此logout方法调用配置的模块的logout方法。

不应该使用LoginContext来认证多个主题。 应该使用单独的LoginContext来认证每个不同的主题。

以下文档适用于所有LoginContext构造函数：

1. Subject
   • 如果构造函数具有Subject输入参数，则LoginContext将使用调用者指定的Subject对象。
   • 如果调用者指定了一个null主题，并且null一个null值，则LoginContext会实例化一个新的主题。
   • 如果构造函数没有 Subject输入参数，则LoginContext会实例化一个新的Subject。

2. Configuration
   • 如果构造函数具有配置输入参数，并且调用者指定非空配置，则LoginContext将使用调用者指定的配置。

     如果构造函数没有配置输入参数，或者如果调用者指定了一个null配置对象，则构造函数使用以下调用来获取已安装的配置：

       config = Configuration.getConfiguration(); 

     对于这两种情况，给构造函数的name参数都传递给Configuration.getAppConfigurationEntry方法。 如果配置没有指定名称的条目，则LoginContext调用getAppConfigurationEntry ，名称为“ other ”（默认条目名称）。 如果没有“ 其他 ”条目，则抛出LoginException 。
   • 当LoginContext使用已安装的配置时，调用者需要createLoginContext。 名称和可能的createLoginContext.other AuthPermissions。 此外，则LoginContext将调用配置模块从内AccessController.doPrivileged呼叫以便执行安全敏感的任务（例如，连接到远程主机，并更新主题）模块将所需要的相应的权限，但则LoginContext的呼叫者将不需要那些权限。
   • 当LoginContext使用调用者指定的配置时，调用者不需要任何createLoginContext AuthPermission。 AccessControlContext为呼叫者保存AccessControlContext ，并从由该上下文限制的AccessController.doPrivileged调用中调用配置的模块。 这意味着调用者上下文（在创建LoginContext时存储）必须具有足够的权限来执行模块可能执行的任何对安全敏感的任务。

3. CallbackHandler
   • 如果构造函数有一个CallbackHandler输入参数，那么LoginContext使用调用者指定的CallbackHandler对象。
   • 如果构造函数没有 CallbackHandler输入参数，或者如果调用者指定了一个null CallbackHandler对象（并且null使用null值），那么LoginContext会查询默认处理程序实现的完全限定类名的auth.login.defaultCallbackHandler security属性。 如果未设置安全属性，则底层模块将不具有用于与用户通信的CallbackHandler。 因此，呼叫者假设所配置的模块具有用于认证用户的替代手段。
   • 当LoginContext使用已安装的配置（而不是调用者指定的配置，请参见上文）时，此LoginContext必须将新的CallbackHandler实现中的所有调用者指定或默认CallbackHandler实现包装，其中handle方法实现将调用指定的CallbackHandler的handle方法java.security.AccessController.doPrivileged通话受限于呼叫者当前的AccessControlContext 。

另请参见：

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

构造方法摘要

构造方法

Constructor and Description
LoginContext(String name) 使用名称实例化一个新的 LoginContext对象。
LoginContext(String name, CallbackHandler callbackHandler) 实例化一个新 LoginContext的名称和一个对象 CallbackHandler对象。
LoginContext(String name, Subject subject) 实例化一个新 LoginContext的名称和一个对象 Subject对象。
LoginContext(String name, Subject subject, CallbackHandler callbackHandler) 实例化一个新的 LoginContext对象，一个名称，一个 Subject要认证，一个 CallbackHandler对象。
LoginContext(String name, Subject subject, CallbackHandler callbackHandler, Configuration config) 实例化一个新 LoginContext对象有一个名字，一个 Subject要进行身份验证，一个 CallbackHandler对象，登录 Configuration 。

方法摘要

Modifier and Type	Method and Description
Subject	getSubject() 返回认证的主题。
void	login() 执行认证。
void	logout() 退出 Subject 。

Methods inherited from class 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 ，并且没有 Configuration条目为“ 其他 ”，或者如果 auth.login.defaultCallbackHandler安全性属性已设置，但实现类无法加载。

SecurityException - （“ createLoginContext 名称 ‘），如果安全管理器被设置并且呼叫者没有AuthPermission，或者如果 名称的配置条目不存在，并且调用者不另外具有AuthPermission（’createLoginContext.other”）

LoginContext

public LoginContext(String name,
                    Subject subject)
             throws LoginException

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

参数

name - 该名称用作 Configuration的索引。

subject - Subject认证。

异常

LoginException - 如果呼叫方指定的 name未出现在 Configuration ，并且没有 Configuration条目为“ 其他 ”，如果主叫方指定的 subject为 null ，或者如果 auth.login.defaultCallbackHandler安全属性已设置，但实现课程无法加载。

SecurityException - （“ createLoginContext 名称 ‘），如果安全管理器被设置并且呼叫者没有AuthPermission，或者如果 名称的配置条目不存在，并且调用者不另外具有AuthPermission（’createLoginContext.other”）

LoginContext

public LoginContext(String name,
                    CallbackHandler callbackHandler)
             throws LoginException

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

参数

name - 该名称用作 Configuration的索引。

callbackHandler - CallbackHandler使用的 CallbackHandler对象与用户进行通信。

异常

LoginException - 如果主叫方指定的 name未出现在 Configuration ，并且没有 Configuration条目为“ 其他 ”，或者呼叫方指定的 callbackHandler为 null 。

SecurityException - （“ createLoginContext 名称 ‘），如果安全管理器被设置并且呼叫者没有AuthPermission，或者如果 名称的配置条目不存在，并且调用者不另外具有AuthPermission（’createLoginContext.other”）

LoginContext

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

实例化一个新的 LoginContext对象，一个名称，一个 Subject要认证，一个 CallbackHandler对象。

参数

name - 该名称用作 Configuration的索引。

subject - Subject进行身份验证。

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

异常

LoginException - 如果呼叫方指定的 name未出现在 Configuration ，并且没有“ 其他 ”的 Configuration条目，或者主叫方指定的 subject为 null ，或者呼叫方指定的 callbackHandler为 null 。

SecurityException - （“ createLoginContext 名称 ‘），如果安全管理器被设置并且呼叫者没有AuthPermission，或者如果 名称的配置条目不存在，并且调用者不另外具有AuthPermission（’createLoginContext.other”）

LoginContext

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

实例化一个新 LoginContext对象有一个名字，一个 Subject要进行身份验证，一个 CallbackHandler对象，登录 Configuration 。

参数

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

subject - 要 Subject的Subject，或 null 。

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

config -所述 Configuration ，该目录的登录模块被调用来执行认证，或 null 。

异常

LoginException - 如果来电者指定的 name没有出现在 Configuration ，而没有 Configuration条目为“ 其他 ”。

SecurityException -如果安全管理器被设置， 配置为 null ，并且或者调用者没有AuthPermission（“。createLoginContext 名 ‘），或者如果为 名称的配置条目不存在，并且调用者不另外具有AuthPermission（’createLoginContext。其他”）

从以下版本开始：

1.5

方法详细信息

login

public void login()
           throws LoginException

执行认证。

此方法调用login配置用于指定给名称每个LoginModule方法LoginContext构造函数，如由登录确定Configuration 。 然后，每个LoginModule执行其相应类型的认证（用户名/密码，智能卡引脚验证等）。

此方法通过调用每一个被配置LoginModule的完成了2阶段认证过程commit方法，如果整个身份验证成功（相关的REQUIRED，REQUISITE，足够了，和可选的LoginModules成功），或者通过调用每个配置的LoginModule的abort方法如果整体验证失败。 如果认证成功，每个成功的LoginModule的commit方法将相关的主体和凭据与Subject相关Subject 。 如果身份验证失败，则每个LoginModule的abort方法将删除/销毁任何先前存储的状态。

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

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

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

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

异常

LoginException - 如果认证失败。

logout

public void logout()
            throws LoginException

退出Subject 。

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

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

异常

LoginException - 如果注销失败。

getSubject

public Subject getSubject()

返回认证的主题。

结果

认证主题。 如果调用者指定了一个Subject到此LoginContext的构造函数，则此方法返回调用者指定的Subject。 如果未指定主题并且验证成功，则此方法返回被实例化的主题，并用于此LoginContext的身份验证。 如果未指定主题，并且认证失败或未尝试，则此方法返回null。