Module java.base

Package javax.security.auth.spi

Interface LoginModule

所有已知的实现类:

JndiLoginModule, KeyStoreLoginModule, Krb5LoginModule, LdapLoginModule, NTLoginModule, UnixLoginModule

       public interface LoginModule
      

认证技术提供者的服务提供者接口。LoginModules被插入到应用程序中，以提供特定类型的认证。

虽然应用程序编写LoginContext API，认证技术提供者实现LoginModule接口。一个Configuration指定要与特定登录应用程序一起使用的LoginModule(s)。因此，可以在应用程序下插入不同的LoginModules，而无需对应用程序本身进行任何修改。

LoginContext负责读取Configuration并实例化适当的LoginModules。每个LoginModule都使用一个Subject，一个CallbackHandler，共享的LoginModule状态和LoginModule特定的选项进行初始化。

Subject表示当前正在进行身份验证的Subject，如果身份验证成功，则会更新相关的凭据。LoginModules使用CallbackHandler与用户进行通信。例如，CallbackHandler可用于提示用户名和密码。请注意，CallbackHandler可能为null。绝对需要CallbackHandler来认证Subject的LoginModules可能会抛出LoginException。LoginModules可以选择使用共享状态来在它们之间共享信息或数据。

LoginModule特定的选项表示由管理员或用户在登录Configuration中为此LoginModule配置的选项。这些选项由LoginModule本身定义，并控制其中的行为。例如，一个LoginModule可以定义支持调试/测试功能的选项。选项使用键值语法定义，例如debug=true。LoginModule将选项存储为Map，以便可以使用键检索值。请注意，LoginModule选择定义的选项数量没有限制。

调用应用程序将认证过程视为单个操作。但是，在LoginModule内部，认证过程分为两个明确的阶段。在第一阶段中，由LoginContext的login方法调用LoginModule的login方法。然后，LoginModule的login方法执行实际的身份验证（例如提示并验证密码），并将其身份验证状态保存为私有状态信息。完成后，LoginModule的login方法要么返回true（如果成功），要么返回false（如果应该被忽略），或者抛出LoginException以指定失败。在失败情况下，LoginModule不得重试身份验证或引入延迟。此类任务的责任属于应用程序。如果应用程序尝试重新尝试身份验证，则将再次调用LoginModule的login方法。

在第二阶段中，如果LoginContext的整体身份验证成功（相关的REQUIRED、REQUISITE、SUFFICIENT和OPTIONAL LoginModules成功），则会调用LoginModule的commit方法。LoginModule的commit方法检查其私下保存的状态，以查看自己的身份验证是否成功。如果整体的LoginContext身份验证成功，并且LoginModule自身的身份验证成功，则commit方法将将相关的Principal（经过身份验证的身份）和Credential（身份验证数据，如加密密钥）与位于LoginModule内的Subject关联起来。

如果LoginContext的整体身份验证失败（相关的REQUIRED、REQUISITE、SUFFICIENT和OPTIONAL LoginModules未成功），则会调用每个LoginModule的abort方法。在这种情况下，LoginModule将删除/销毁最初保存的任何身份验证状态。

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

LoginModule实现必须具有无参数的构造函数。这允许加载LoginModule的类实例化它。

自版本:

1.4

参见:

• LoginContext
• Configuration

Method Summary

Modifier and Type	Method	Description
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的方法。

Method Details

initialize

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

初始化这个LoginModule。

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

参数:

subject - 要进行身份验证的Subject。

callbackHandler - 用于与最终用户进行通信的CallbackHandler（例如提示用户名和密码）。

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

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

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 LoginModules成功），则调用此方法。

如果此LoginModule自身的身份验证尝试成功（通过检索login方法保存的私有状态进行检查），则此方法将将相关的Principal和Credential与位于LoginModule中的Subject关联起来。如果此LoginModule自身的身份验证尝试失败，则此方法将删除/销毁最初保存的任何状态。

返回:

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

抛出:

LoginException - 如果提交失败

abort

             boolean abort() throws LoginException
            

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

如果LoginContext的整体身份验证失败（相关的REQUIRED、REQUISITE、SUFFICIENT和OPTIONAL LoginModules未成功），则调用此方法。

如果此LoginModule自身的身份验证尝试成功（通过检索login方法保存的私有状态进行检查），则此方法将清理最初保存的任何状态。

返回:

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

抛出:

LoginException - 如果中止失败

logout

             boolean logout() throws LoginException
            

登出Subject的方法。

此方法的实现可能会删除/销毁Subject的Principal和Credential。

实现注意:

实现应在从Subject的Principals或Credentials集中删除变量之前检查变量是否为null，否则将抛出NullPointerException，因为这些集合禁止空元素。如果此方法在登录失败后调用，这一点尤为重要。

返回:

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

抛出:

LoginException - 如果登出失败