Module java.base

软件包 javax.security.auth.login

Class LoginContext

java.lang.Object

javax.security.auth.login.LoginContext

public class LoginContext
extends Object

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

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

一个典型的调用者用一个名字和一个CallbackHandler实例化一个LoginContext。 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值，则LoginContext会实例化一个新的主题。
   • 如果构造没有一个主题输入参数，则LoginContext实例化一个新的主题。
2. Configuration
   • 如果构造函数具有配置输入参数，并且调用者指定非空配置，则LoginContext将使用调用者指定的配置。

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

       config = Configuration.getConfiguration(); 

     对于这两种情况，给构造函数的名称参数都传递给Configuration.getAppConfigurationEntry方法。 如果配置没有指定名称的条目，则LoginContext调用getAppConfigurationEntry名称为“ other ”（默认条目名称）。 如果没有“ 其他 ”条目，则抛出一个LoginException 。
   • 当LoginContext使用已安装的配置时，调用者需要createLoginContext。 名称和可能的createLoginContext.other AuthPermissions。 此外，LoginContext将从AccessController.doPrivileged调用中调用配置的模块，以便执行安全敏感任务（如连接到远程主机和更新主题）的模块将需要相应的权限，但是LoginContext的调用者将不需要那些权限。
   • 当LoginContext使用调用者指定的配置时，调用者不需要任何createLoginContext AuthPermission。 LoginContext为呼叫者保存AccessControlContext ，并在由该上下文限制的AccessController.doPrivileged调用中调用配置的模块。 这意味着调用者上下文（在创建LoginContext时存储）必须具有足够的权限来执行模块可能执行的任何对安全敏感的任务。
3. CallbackHandler
   • 如果构造函数有一个CallbackHandler输入参数，那么LoginContext使用调用者指定的CallbackHandler对象。
   • 如果构造没有给CallbackHandler输入参数，或者调用者指定一个null CallbackHandler对象（并且null值是允许的），则LoginContext查询auth.login.defaultCallbackHandler安全属性的默认处理程序实现的完全限定类名。 如果未设置安全属性，则底层模块将不具有用于与用户通信的CallbackHandler。 因此，呼叫者假设所配置的模块具有用于认证用户的替代手段。
   • 当LoginContext使用已安装的配置（而不是调用者指定的配置，请参见上文）时，这个LoginContext必须在一个新的CallbackHandler实现中包装任何调用者指定的或默认的CallbackHandler实现，该实现的handle方法实现会调用指定的CallbackHandler的handle方法java.security.AccessController.doPrivileged呼叫受到呼叫者当前的AccessControlContext 。

从以下版本开始：

1.4

另请参见：

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

构造方法摘要

构造方法

Constructor	描述
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	方法	描述
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条目为“ other ”，或者如果设置了 auth.login.defaultCallbackHandler安全属性，但实现类无法加载。

SecurityException - （“ createLoginContext 名称 ‘），如果安全管理器被设置并且呼叫者没有AuthPermission，或者如果配置条目 name不存在，并且调用者不另外具有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 - LoginModules用于与用户通信的 CallbackHandler对象。

异常

LoginException - 如果来电者指定的 name未出现在 Configuration并且没有 Configuration条目“ other ”，或者如果来电者指定的 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 - LoginModules用于与用户通信的 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 ，或者是 null 。

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

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

异常

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

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

从以下版本开始：

1.5

方法详细信息

login

public void login()
           throws LoginException

执行认证。

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

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

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

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

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

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

异常

LoginException - 如果身份验证失败。

logout

public void logout()
            throws LoginException

注销Subject 。

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

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

异常

LoginException - 如果注销失败。

getSubject

public Subject getSubject()

返回认证的主题。

结果

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