模块  java.base
软件包  javax.security.auth.login

Class LoginContext

  • public class LoginContextextends Object

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

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

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

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

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

    要注销主题，调用者调用logout方法。 如同login方法，此logout方法调用logout用于配置的模块方法。

    不应使用LoginContext来验证多个Subject。 应使用单独的LoginContext来验证每个不同的Subject。

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

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

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

          config = Configuration.getConfiguration();
        对于这两种情况，给构造函数赋予的name参数将传递给Configuration.getAppConfigurationEntry方法。 如果配置没有指定名称的条目，则LoginContext将使用名称“ other ”（默认条目名称）调用getAppConfigurationEntry 。 如果“ other ”没有条目，则抛出LoginException 。
      • 当LoginContext使用已安装的Configuration时，调用者需要createLoginContext。 name和可能的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安全属性的默认处理程序实现的完全限定类名。 如果未设置security属性，则底层模块将没有CallbackHandler用于与用户通信。 因此，呼叫者假定配置的模块具有用于认证用户的替代装置。
      • 当LoginContext使用已安装的Configuration（而不是调用者指定的Configuration，参见上文）时，此LoginContext必须在新的CallbackHandler实现中包装任何调用者指定的或默认的CallbackHandler实现，其实现的handle方法实现调用指定的CallbackHandler的handle方法。 java.security.AccessController.doPrivileged呼叫受呼叫方当前AccessControlContext 。
    从以下版本开始：
    1.4
    另请参见：
    Security ， AuthPermission ， Subject ， CallbackHandler ， Configuration ， LoginModule ， security properties

    • 构造方法详细信息

      • LoginContext

        public LoginContext​(String name)             throws LoginException
        使用名称实例化新的 LoginContext对象。
        参数
        name - 用作 Configuration索引的 Configuration 。
        异常
        LoginException - 如果调用者指定的 name未出现在 Configuration且没有“ other ”的 Configuration条目，或者设置了 auth.login.defaultCallbackHandler安全属性，但无法加载实现类。
        SecurityException - （“ createLoginContext 名称 ‘），如果安全管理器被设置并且呼叫者没有AuthPermission，或者如果配置条目 name不存在，并且调用者不另外具有AuthPermission（’createLoginContext.other”）

      • LoginContext

        public LoginContext​(String name,                    Subject subject)             throws LoginException
        实例化一个新 LoginContext的名称和一个对象 Subject对象。
        参数
        name - 用作 Configuration索引的 Configuration 。
        subject - 要验证的 Subject 。
        异常
        LoginException - 如果呼叫者指定的 name未出现在 Configuration且“ other ”没有 Configuration条目，如果呼叫者指定的 subject是 null ，或者如果设置了 auth.login.defaultCallbackHandler安全属性，则执行class无法加载。
        SecurityException - （“ createLoginContext 名称 ‘），如果安全管理器被设置并且呼叫者没有AuthPermission，或者如果 名称的配置条目不存在，并且调用者不另外具有AuthPermission（’createLoginContext.other”）

      • LoginContext

        public LoginContext​(String name,                    CallbackHandler callbackHandler)             throws LoginException
        实例化一个新 LoginContext的名称和一个对象 CallbackHandler对象。
        参数
        name - 用作 Configuration索引的 Configuration 。
        callbackHandler - LoginModules用于与用户通信的 CallbackHandler对象。
        异常
        LoginException - 如果呼叫者指定的 name未出现在 Configuration并且“ other ”没有 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索引的 Configuration 。
        subject - 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
        执行身份验证。

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

        如果整体身份验证成功（相关的REQUIRED，REQUISITE，SUFFICIENT和OPTIONAL LoginModules成功），或者如果整体身份验证失败，则通过调用每个已配置的LoginModule的abort方法，此方法通过调用每个已配置的LoginModule的commit方法来完成两阶段身份验证过程。 如果身份验证成功，则每个成功的LoginModule的commit方法都会将相关的Principal和Credentials与Subject相关联。 如果身份验证失败，则每个LoginModule的abort方法都会删除/销毁以前存储的任何状态。

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

        如果abort阶段因任何原因失败，则此方法会传播在login阶段或commit阶段期间抛出的原始异常。 在任何一种情况下，整体认证都会失败。

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

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

        异常
        LoginException - 如果身份验证失败。

      • logout

        public void logout()            throws LoginException
        注销Subject 。

        此方法为为此LoginContext配置的每个LoginModule调用logout方法。 每个LoginModule执行其各自的注销过程，其可以包括移除/破坏Principal和Credential从信息Subject和状态清除。

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

        异常
        LoginException - 如果注销失败。

      • getSubject

        public Subject getSubject()
        返回经过身份验证的主题。
        结果
        经过身份验证的主题。 如果调用者为此LoginContext的构造函数指定了Subject，则此方法返回调用者指定的Subject。 如果未指定Subject且身份验证成功，则此方法返回实例化的Subject，并由此LoginContext用于身份验证。 如果未指定Subject，并且身份验证失败或未尝试过，则此方法返回null。