Module java.base

Package javax.security.auth.login

Class Configuration

java.lang.Object

javax.security.auth.login.Configuration

直接已知的子类:

ConfigFile

       public abstract class Configuration extends Object
      

Configuration对象负责指定哪些LoginModules应该用于特定应用程序，以及LoginModules应该以什么顺序被调用。

登录配置包含以下信息。请注意，此示例仅代表Configuration的默认语法。此类的子类实现可以实现替代语法，并可以从文件、数据库或服务器等任何源检索Configuration。

      Name {
            ModuleClass  Flag    ModuleOptions;
            ModuleClass  Flag    ModuleOptions;
            ModuleClass  Flag    ModuleOptions;
      };
      Name {
            ModuleClass  Flag    ModuleOptions;
            ModuleClass  Flag    ModuleOptions;
      };
      other {
            ModuleClass  Flag    ModuleOptions;
            ModuleClass  Flag    ModuleOptions;
      };
 

Configuration中的每个条目都通过应用程序名称Name进行索引，并包含为该应用程序配置的LoginModules列表。每个LoginModule都通过其完全限定的类名指定。身份验证按照指定的确切顺序在模块列表中进行。如果应用程序没有特定条目，则默认为"other"的特定条目。

Flag值控制身份验证在堆栈中进行时的整体行为。以下是Flag的有效值及其各自的语义描述：

      1) Required     - LoginModule必须成功。
                      如果成功或失败，身份验证仍将继续进行
                      继续进行LoginModule列表。

      2) Requisite    - LoginModule必须成功。
                      如果成功，身份验证继续进行
                      LoginModule列表。如果失败，
                      控制立即返回到应用程序
                      (身份验证不会继续进行
                      LoginModule列表)。

      3) Sufficient   - LoginModule不需要
                      成功。如果成功，控制立即
                      返回到应用程序(身份验证不会
                      继续进行LoginModule列表)。
                      如果失败，身份验证继续进行
                      LoginModule列表。

      4) Optional     - LoginModule不需要
                      成功。如果成功或失败，
                      身份验证仍将继续进行
                      LoginModule列表。
 

只有所有Required和Requisite LoginModules成功身份验证，整体身份验证才会成功。如果配置了一个SufficientLoginModule并成功，则只有在该SufficientLoginModule之前的Required和Requisite LoginModules成功，整体身份验证才会成功。如果没有为应用程序配置Required或Requisite LoginModules，则至少一个Sufficient或OptionalLoginModule必须成功。

ModuleOptions是一个以空格分隔的LoginModule-特定值列表，这些值直接传递给底层的LoginModules。选项由LoginModule本身定义，并控制其中的行为。例如，LoginModule可以定义选项以支持调试/测试功能。在Configuration中指定选项的正确方法是使用以下键值对：debug="true"。键和值应该用等号分隔，并且值应该用双引号括起来。如果值中出现形式为${system.property}的字符串，则它将扩展为系统属性的值。请注意，LoginModule可能定义的选项数量没有限制。

以下是基于上述语法的示例Configuration条目：

 Login {
   com.sun.security.auth.module.UnixLoginModule required;
   com.sun.security.auth.module.Krb5LoginModule optional
                   useTicketCache="true"
                   ticketCache="${user.home}${/}tickets";
 };
 

此Configuration指定名为"Login"的应用程序要求用户首先对com.sun.security.auth.module.UnixLoginModule进行身份验证，这是必须成功的。即使UnixLoginModule身份验证失败，com.sun.security.auth.module.Krb5LoginModule仍会被调用。这有助于隐藏失败的来源。由于Krb5LoginModule是Optional的，因此只有UnixLoginModule（Required）成功，整体身份验证才会成功。

还请注意，LoginModule特定的选项useTicketCache="true"和ticketCache=${user.home}${/}tickets"被传递给Krb5LoginModule。这些选项指示Krb5LoginModule在指定位置使用票证缓存。系统属性user.home和/（文件分隔符）被扩展为它们各自的值。

在任何给定时间，运行时中只安装一个Configuration对象。可以通过调用setConfiguration方法来安装Configuration对象。可以通过调用getConfiguration方法获取安装的Configuration对象。

如果在运行时没有安装Configuration对象，则调用getConfiguration会安装默认Configuration实现的实例（此抽象类的默认子类实现）。可以通过将login.configuration.provider安全属性的值设置为所需Configuration子类实现的完全限定名称来更改默认Configuration实现。

应用程序代码可以直接对Configuration进行子类化以提供自定义实现。此外，可以通过使用标准类型调用getInstance工厂方法之一来构造Configuration对象的实例。默认策略类型为"JavaLoginConfig"。请参阅Java安全标准算法名称规范中的Configuration部分，了解标准Configuration类型的列表。

自1.4版本起:

1.4

参见:

• LoginContext
• security properties

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static interface	Configuration.Parameters	这代表Configuration参数的标记接口。

Constructor Summary

Constructors

Modifier	Constructor	Description
protected	Configuration()	唯一的构造函数。

Method Summary

Modifier and Type	Method	Description
abstract AppConfigurationEntry[]	getAppConfigurationEntry(String name)	从此Configuration中检索指定name的AppConfigurationEntries。
static Configuration	getConfiguration()	获取已安装的登录Configuration。
static Configuration	getInstance(String type, Configuration.Parameters params)	返回指定类型的Configuration对象。
static Configuration	getInstance(String type, Configuration.Parameters params, String provider)	返回指定类型的Configuration对象。
static Configuration	getInstance(String type, Configuration.Parameters params, Provider provider)	返回指定类型的Configuration对象。
Configuration.Parameters	getParameters()	返回Configuration参数。
Provider	getProvider()	返回此Configuration的提供程序。
String	getType()	返回此Configuration的类型。
void	refresh()	刷新并重新加载Configuration。
static void	setConfiguration(Configuration configuration)	设置登录Configuration。

Methods declared in class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

Configuration

             protected Configuration()
            

唯一的构造函数。（通常由子类构造函数隐式调用。）

Method Details

getConfiguration

             public static Configuration getConfiguration()
            

获取已安装的登录Configuration。

返回:

登录Configuration。如果通过Configuration.setConfiguration方法设置了Configuration对象，则返回该对象。否则，返回默认的Configuration对象。

抛出:

SecurityException - 如果调用者没有权限检索Configuration。

参见:

• setConfiguration(javax.security.auth.login.Configuration)

setConfiguration

             public static void setConfiguration(Configuration configuration)
            

设置登录Configuration。

参数:

configuration - 新的Configuration

抛出:

SecurityException - 如果当前线程没有权限设置Configuration。

参见:

• getConfiguration()

getInstance

             public static Configuration getInstance(String type, Configuration.Parameters params) throws NoSuchAlgorithmException
            

返回指定类型的Configuration对象。

此方法遍历已注册的安全提供程序列表，从最首选的提供程序开始。返回一个新的Configuration对象，该对象封装了支持指定类型的第一个提供程序的ConfigurationSpi实现。

请注意，已注册提供程序的列表可以通过Security.getProviders()方法检索。

实现注意事项:

JDK参考实现还使用jdk.security.provider.preferred Security 属性来确定指定算法的首选提供程序顺序。这可能与由Security.getProviders()返回的提供程序顺序不同。

参数:

type - 指定的配置类型。请参阅Java安全标准算法名称规范中的配置部分，获取标准配置类型列表。

params - 配置的参数，可以为null。

返回:

新的Configuration对象

抛出:

IllegalArgumentException - 如果所指定的参数不被所选Provider的ConfigurationSpi实现理解

NoSuchAlgorithmException - 如果没有Provider支持指定类型的ConfigurationSpi实现

NullPointerException - 如果type为null

SecurityException - 如果调用者没有权限为指定类型获取Configuration实例

自版本:

1.6

另请参阅:

• Provider

getInstance

             public static Configuration getInstance(String type, Configuration.Parameters params, String provider) throws NoSuchProviderException, NoSuchAlgorithmException
            

返回指定类型的Configuration对象。

返回一个封装来自指定提供程序的ConfigurationSpi实现的新Configuration对象。指定的提供程序必须在提供程序列表中注册。

请注意，注册的提供程序列表可以通过Security.getProviders()方法检索。

参数:

type - 指定的配置类型。请参阅Java安全标准算法名称规范中的配置部分，获取标准配置类型列表。

params - 配置的参数，可以为null。

provider - 提供程序。

返回:

新的Configuration对象

抛出:

IllegalArgumentException - 如果指定的提供程序为null或空，或者如果指定的参数不被指定提供程序的ConfigurationSpi实现理解

NoSuchProviderException - 如果指定的提供程序未在安全提供程序列表中注册

NoSuchAlgorithmException - 如果指定的提供程序不支持指定类型的ConfigurationSpi实现

NullPointerException - 如果type为null

SecurityException - 如果调用者没有权限为指定类型获取Configuration实例

自版本:

1.6

另请参阅:

• Provider

getInstance

             public static Configuration getInstance(String type, Configuration.Parameters params, Provider provider) throws NoSuchAlgorithmException
            

返回指定类型的Configuration对象。

返回一个封装来自指定Provider对象的ConfigurationSpi实现的新Configuration对象。请注意，指定的Provider对象不必在提供程序列表中注册。

参数:

type - 指定的配置类型。请参阅Java安全标准算法名称规范中的配置部分，获取标准配置类型列表。

params - 配置的参数，可以为null。

provider - 提供程序。

返回:

新的Configuration对象

抛出:

IllegalArgumentException - 如果指定的Provider为null，或者如果指定的参数不被指定Provider的ConfigurationSpi实现理解

NoSuchAlgorithmException - 如果指定的Provider不支持指定类型的ConfigurationSpi实现

NullPointerException - 如果type为null

SecurityException - 如果调用者没有权限为指定类型获取Configuration实例

自版本:

1.6

另请参阅:

• Provider

getProvider

             public Provider getProvider()
            

返回此Configuration的Provider。

如果此Configuration实例是通过调用Configuration.getInstance获取的，则只会有一个Provider。否则，此方法返回null。

返回:

此Configuration的Provider，或null。

自版本:

1.6

getType

             public String getType()
            

返回此Configuration的类型。

如果此Configuration实例是通过调用Configuration.getInstance获取的，则只会有一个类型。否则，此方法返回null。

返回:

此Configuration的类型，或null。

自版本:

1.6

getParameters

             public Configuration.Parameters getParameters()
            

返回Configuration参数。

如果此Configuration实例是通过调用Configuration.getInstance获取的，则只会有参数。否则，此方法返回null。

返回:

配置参数，或null。

自版本:

1.6

getAppConfigurationEntry

             public abstract AppConfigurationEntry[] getAppConfigurationEntry(String name)
            

从此Configuration中检索指定name的AppConfigurationEntries。

参数:

name - 用于索引Configuration的名称。

返回:

来自此Configuration的指定name的AppConfigurationEntries数组，如果指定name没有条目，则返回null

refresh

             public void refresh()
            

刷新和重新加载Configuration。

此方法以实现相关的方式导致此Configuration对象刷新/重新加载其内容。例如，如果此Configuration对象将其条目存储在文件中，调用refresh可能导致文件被重新读取。

此方法的默认实现不执行任何操作。如果实现支持刷新操作，则应重写此方法。

抛出:

SecurityException - 如果调用者没有权限刷新其Configuration。