Module  java.base

Class 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可以通过调用主题的各个被检索getPrincipalsgetPublicCredentials ,和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
    另请参见:
    SecurityAuthPermissionSubjectCallbackHandlerConfigurationLoginModulesecurity properties
    • 构造方法详细信息

      • 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条目,如果呼叫者指定的 subjectnull ,或者如果设置了 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 ”,或者如果来电者指定的 callbackHandlernull
        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条目,或者如果主叫方指定的 subjectnull ,或者主叫方指定的 callbackHandlernull
        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阶段( logincommit阶段失败),则此方法将调用为应用程序配置的所有LoginModule,而不管其各自的Configuration标志参数。 基本上这意味着在abort阶段, RequisiteSufficient语义被忽略。 这样可以保证适当的清理和状态恢复。

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

        public void logout​()
                    throws LoginException
        注销Subject

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

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

        异常
        LoginException - 如果注销失败。
      • getSubject

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