javax.security.auth.spi
接口 LoginModule

public interface LoginModule

LoginModule 描述由验证技术提供者实现的接口。LoginModule 插入到应用程序中以提供特定类型的验证。

当应用程序写入 LoginContext API 时，验证技术提供者将实现 LoginModule 接口。Configuration 指定将与特定登录应用程序一起使用的 LoginModule(s)。因此可以将不同的 LoginModule 插入到应用程序中，而无需修改应用程序本身。

LoginContext 负责读取 Configuration 和实例化适当的 LoginModule。每个 LoginModule 都是使用 Subject、CallbackHandler、共享的 LoginModule 状态和特定于 LoginModule 的选项来实例化的。 Subject 表示当前正进行验证的 Subject，如果验证成功，则使用相关的 Credential 更新它。LoginModule 使用 CallbackHandler 与用户进行通信。例如，CallbackHandler 可以用于提示要求用户名和密码。注意，CallbackHandler 可以为 null。确实需要一个 CallbackHandler 来对 Subject 进行验证的 LoginModule 可以抛出 LoginException。LoginModule 可以有选择地使用共享状态来共享它们之间的信息或数据。

特定于 LoginModule 的选项表示由管理员或用户在 Configuration 中为此 LoginModule 配置的选项。这些选项由 LoginModule 自身定义，并在其中控制其行为。例如，LoginModule 可以定义支持调试/测试功能的选项。这些选项是使用键-值语法定义的，例如 debug=true。LoginModule 以 Map 形式存储这些选项，因此可以使用键来获取这些值。注意，对 LoginModule 选择定义的选项个数是没有限制的。

调用应用程序将验证过程视为单个操作。但是，LoginModule 中的验证过程分两个不同的阶段进行。在第一个阶段，LoginModule 的 login 方法由 LoginContext 的 login 方法调用。LoginModule 的 login 方法执行实际的验证（例如，提示并验证密码），并将验证状态作为私有状态信息保存。一旦完成上述操作，LoginModule 的 login 将返回 true（如果成功）或 false（如果应该忽略它），或抛出 LoginException 来指示失败。在失败的情况下，LoginModule 不必再尝试进行验证或者引入延迟。由应用程序完成这类任务。如果应用程序试图重新尝试验证，将会再次调用 LoginModule 的 login 方法。

在第二个阶段，如果 LoginContext 的整个验证成功（相关的 REQUIRED、REQUISITE、SUFFICIENT 和 OPTIONAL LoginModule 成功），则调用 LoginModule 的 commit 方法。LoginModule 的 commit 方法检查其私有保存状态，以查看自己的验证是否成功。如果整个 LoginContext 验证成功，并且 LoginModule 自己的验证也获得成功，则 commit 方法会将相关的 Principal（已进行验证的身份）和 Credential（验证数据，如加密密钥）与位于 LoginModule 中的 Subject 联系在一起。

如果 LoginContext 的整个验证失败（相关的 REQUIRED、REQUISITE、SUFFICIENT 和 OPTIONAL LoginModule 没有成功），则调用每个 LoginModule 的 abort 方法。在这种情况下，LoginModule 移除/销毁原先保存的任何验证状态。

注销 Subject 只涉及一个阶段。LoginContext 调用 LoginModule 的 logout 方法。然后 LoginModule 的 logout 方法执行注销过程，例如从 Subject 中移除 Principal 或 Credential，或者记录会话信息。

LoginModule 实现必须有一个无参数的构造方法。这允许加载 LoginModule 的类对其进行实例化。

另请参见：

LoginContext, Configuration

方法摘要

boolean	abort() 中止验证过程的方法（阶段 2）。
boolean	commit() 提交验证过程的方法（阶段 2）。
void	initialize(Subject subject, CallbackHandler callbackHandler, Map<String,?> sharedState, Map<String,?> options) 初始化此 LoginModule。
boolean	login() 对 Subject 进行验证的方法（阶段 1）。
boolean	logout() 注销 Subject 的方法。

方法详细信息

initialize

void initialize(Subject subject,
                CallbackHandler callbackHandler,
                Map<String,?> sharedState,
                Map<String,?> options)

初始化此 LoginModule。

在此 LoginModule 已经实例化后，由 LoginContext 调用此方法。此方法的目的是使用相关的信息初始化此 LoginModule。如果此 LoginModule 不理解存储在 sharedState 或 options 参数中的任何数据，则可以忽略它们。

参数：

subject - 要进行验证的 Subject。

callbackHandler - 用来与最终用户通信的 CallbackHandler（例如，提示要求用户名和密码）。

sharedState - 与其他已配置的 LoginModule 共享的状态。

options - 在登录 Configuration 中为此特定的 LoginModule 指定的选项。

login

boolean login()
              throws LoginException

对 Subject 进行验证的方法（阶段 1）。

此方法的实现对 Subject 进行验证。例如，它可以向 Subject 提示一些信息（比如用户名和密码），然后试图验证该密码。此方法将验证尝试的结果作为私有状态保存在 LoginModule 中。

返回：

如果验证成功，则返回 true；如果应该忽略此 LoginModule，则返回 false。

抛出：

LoginException - 如果验证失败

commit

boolean commit()
               throws LoginException

提交验证过程的方法（阶段 2）。

如果 LoginContext 的整个验证成功（相关的 REQUIRED、REQUISITE、SUFFICIENT 和 OPTIONAL LoginModule 成功），则调用此方法。

如果此 LoginModule 自己的验证尝试成功（通过获取 login 方法保存的私有状态检查），则此方法会将相关的 Principal 和 Credential 与位于 LoginModule 中的 Subject 联系在一起。如果此 LoginModule 自己的验证尝试失败，则此方法将移除/销毁原先保存的任何状态。

返回：

如果此方法成功，则返回 true；如果应该忽略此 LoginModule，则返回 false。

抛出：

LoginException - 如果提交失败。

abort

boolean abort()
              throws LoginException

中止验证过程的方法（阶段 2）。

如果 LoginContext 的整个验证失败（相关的 REQUIRED、REQUISITE、SUFFICIENT 和 OPTIONAL LoginModule 没有成功），则调用此方法。

如果此 LoginModule 自己的验证尝试成功（通过获取 login 方法保存的私有状态检查），则此方法将清除任何原先保存的状态。

返回：

如果此方法成功，则返回 true；如果应该忽略此 LoginModule，则返回 false。

抛出：

LoginException - 如果中止失败

logout

boolean logout()
               throws LoginException

注销 Subject 的方法。

此方法的实现可以移除/销毁 Subject 的 Principal 和 Credential。

返回：

如果此方法成功，则返回 true；如果应该忽略此 LoginModule，则返回 false。

抛出：

LoginException - 如果注销失败