h1. J2EE Agent>Global>General>Agent Filter Mode
|| Property Label || Property Name || Hot Swappable ||
|Agent Filter Mode| com.sun.identity.agents.config.filter.mode |No|
See the [list of all agent properties | agent3properties] for a description of other agent properties.
h4. Description:
*+Summary+*
This is an extremely important property! It allows you to set the mode of operation for the J2EE agent. The filter mode is a security setting that relates primarily to authentication, but also relates in some sense to authorization. The values for this property that are valid vary depending on the specific J2EE agent. The greatest number of valid values possible for a J2EE agent is five, as such:
ALL, J2EE_POLICY, URL_POLICY, SSO_ONLY, NONE
However, not all these values are valid for all J2EE agents depending upon the deployment container. For example, some values do not apply to J2EE agents for portal servers. Since the values that are valid vary from J2EE agent to J2EE agent, consult the documentation specific to the J2EE agent you are configuring. The filter explanations provided farther below apply for agents that offer all five of the filter modes.
*+Setting this Property+*
*Valid key:* the web application name
*Valid values:* ALL, J2EE_POLICY, URL_POLICY, SSO_ONLY, NONE
For this property, a global value can be set to apply to all the applications that don't have their own specific filter mode. To assign such a value globally, leave the Map Key field empty.
Console Examples:
To set "ALL" as the global filter mode, leave the Map Key field empty, and enter "ALL" in the Corresponding Map Value field.
To set "URL_POLICY" as the filter mode for the application "BankApp," enter "BankApp" in the Map Key field, and enter "URL_POLICY" in the Corresponding Map Value field.
\\
\\
* Filter Mode: NONE
This mode of operation effectively disables the agent filter. When operating in this mode, the agent filter allows all requests to pass through. However, if the logging is enabled, the agent filter will still log all the requests that it intercepts.
{note:title=Caution}
This mode is provided to facilitate development and testing efforts in a controlled development or test environment. Do not to use this mode of operation in a production environment at any time.{note}
When the agent filter is operating in this mode, any declarative J2EE security policy or programmatic J2EE security API calls will return a negative result regardless of the user.
* Filter Mode: SSO_ONLY
This is the least restrictive mode of operation for the agent filter. In this mode, the agent simply ensures that all users who try to access protected web resources are authenticated using Federated Access Manager Authentication Service.
When operating in this mode, any declarative J2EE security policy or programmatic J2EE security API calls evaluated for the application will result in negative evaluation.
* Filter Mode: J2EE_POLICY
In the J2EE_POLICY mode, the agent filter and agent realm work together with Federated Access Manager to ensure the correct evaluation of J2EE policies. You can set these policies either in the application's deployment descriptors or, in cases where the application uses the J2EE programmatic security APIs, in the application code. URL policies that are defined in Federated Access Manager do not take effect in this mode.
If the application uses declarative security in the Web tier, you must configure the agent to enable that feature.
While running in the J2EE_POLICY mode, the Policy Agent ensures that the security principal is set in the system for all authorized accesses.
* Filter Mode: URL_POLICY
In the URL_POLICY mode, the agent filter enforces the URL policies that are defined in Federated Access Manager.
* Filter Mode: ALL
The ALL mode is the most restrictive mode: The filter enforces both the J2EE policies and URL policies that are defined in Federated Access Manager. This mode requires that you configure the agent realm in the application server. When running in this mode, the Policy Agent ensures that the security principal is set in the system for all authorized accesses.
The ALL mode is highly recommended for deployed production systems.
\\
\\
----
h4.{color:red}QUESTIONS/COMMENTS? Add them below!{color}
----
*Comments:*
The following are pending questions about this property. Here, all the questions have to do with the agent realm and how it interacts with the filter mode. Since the use of the agent realm and filter can vary from agent to agent, it seems best to make general statements that apply to all agents and then specify when certain property settings might not apply or might behave differently depending on the agent.
* *Should the following info be included generally about the filter mode:*
Regardless of what mode the agent filter is operating in, the agent realm will continue to function, if configured. This can therefore lead to a situation where the agent realm component may malfunction or may result in the negative evaluation of J2EE security policies configured in the application's deployment descriptors or being used through the J2EE programmatic security API. To avoid this, you may disable the agent realm component, if necessary. The sections that follow describe the different agent filter modes and also tell you how to disable the agent realm.
* *Should the following info be included about the NONE filter mode:*
NONE mode:
Although this mode disables the agent filter from taking any action on the incoming requests other than logging, it has no effect on the agent realm that may still be configured in your deployment container and may get invoked by the deployed application if the deployed application has J2EE security policies in its descriptors or uses programmatic security. With the agent filter disabled, these applications will fail to evaluate the J2EE security policies correctly and as a result the deployed application may malfunction. In order to fully disable the agent, you must therefore ensure that the agent realm is not active. Refer to the section Disabling the Agent Realm to find out how the agent realm can be disabled for your agent installation. Once you have disabled the agent realm and the filter mode is set to NONE, it is functionally equivalent to not having the agent in your system at all.
* *Should the following info be included about the SSO_ONLY filter mode:*
SSO_ONLY mode:
In this mode of operation the agent realm is not used and can be safely disabled.
* *Should the following info be included about the J2EE_POLICY filter mode:*
J2EE_POLICY mode:
This mode requires that you configure the agent realm in the application server.
* *Should the following info be included about the URL_POLICY filter mode:*
URL_POLICY mode:
This mode does not require the agent realm to be functional; you can safely disable the realm.
* *Should the following info be included about the ALL filter mode:*
ALL:
This mode requires that you configure the agent realm in the application server.
\\
\\
----
|| Property Label || Property Name || Hot Swappable ||
|Agent Filter Mode| com.sun.identity.agents.config.filter.mode |No|
See the [list of all agent properties | agent3properties] for a description of other agent properties.
h4. Description:
*+Summary+*
This is an extremely important property! It allows you to set the mode of operation for the J2EE agent. The filter mode is a security setting that relates primarily to authentication, but also relates in some sense to authorization. The values for this property that are valid vary depending on the specific J2EE agent. The greatest number of valid values possible for a J2EE agent is five, as such:
ALL, J2EE_POLICY, URL_POLICY, SSO_ONLY, NONE
However, not all these values are valid for all J2EE agents depending upon the deployment container. For example, some values do not apply to J2EE agents for portal servers. Since the values that are valid vary from J2EE agent to J2EE agent, consult the documentation specific to the J2EE agent you are configuring. The filter explanations provided farther below apply for agents that offer all five of the filter modes.
*+Setting this Property+*
*Valid key:* the web application name
*Valid values:* ALL, J2EE_POLICY, URL_POLICY, SSO_ONLY, NONE
For this property, a global value can be set to apply to all the applications that don't have their own specific filter mode. To assign such a value globally, leave the Map Key field empty.
Console Examples:
To set "ALL" as the global filter mode, leave the Map Key field empty, and enter "ALL" in the Corresponding Map Value field.
To set "URL_POLICY" as the filter mode for the application "BankApp," enter "BankApp" in the Map Key field, and enter "URL_POLICY" in the Corresponding Map Value field.
\\
\\
* Filter Mode: NONE
This mode of operation effectively disables the agent filter. When operating in this mode, the agent filter allows all requests to pass through. However, if the logging is enabled, the agent filter will still log all the requests that it intercepts.
{note:title=Caution}
This mode is provided to facilitate development and testing efforts in a controlled development or test environment. Do not to use this mode of operation in a production environment at any time.{note}
When the agent filter is operating in this mode, any declarative J2EE security policy or programmatic J2EE security API calls will return a negative result regardless of the user.
* Filter Mode: SSO_ONLY
This is the least restrictive mode of operation for the agent filter. In this mode, the agent simply ensures that all users who try to access protected web resources are authenticated using Federated Access Manager Authentication Service.
When operating in this mode, any declarative J2EE security policy or programmatic J2EE security API calls evaluated for the application will result in negative evaluation.
* Filter Mode: J2EE_POLICY
In the J2EE_POLICY mode, the agent filter and agent realm work together with Federated Access Manager to ensure the correct evaluation of J2EE policies. You can set these policies either in the application's deployment descriptors or, in cases where the application uses the J2EE programmatic security APIs, in the application code. URL policies that are defined in Federated Access Manager do not take effect in this mode.
If the application uses declarative security in the Web tier, you must configure the agent to enable that feature.
While running in the J2EE_POLICY mode, the Policy Agent ensures that the security principal is set in the system for all authorized accesses.
* Filter Mode: URL_POLICY
In the URL_POLICY mode, the agent filter enforces the URL policies that are defined in Federated Access Manager.
* Filter Mode: ALL
The ALL mode is the most restrictive mode: The filter enforces both the J2EE policies and URL policies that are defined in Federated Access Manager. This mode requires that you configure the agent realm in the application server. When running in this mode, the Policy Agent ensures that the security principal is set in the system for all authorized accesses.
The ALL mode is highly recommended for deployed production systems.
\\
\\
----
h4.{color:red}QUESTIONS/COMMENTS? Add them below!{color}
----
*Comments:*
The following are pending questions about this property. Here, all the questions have to do with the agent realm and how it interacts with the filter mode. Since the use of the agent realm and filter can vary from agent to agent, it seems best to make general statements that apply to all agents and then specify when certain property settings might not apply or might behave differently depending on the agent.
* *Should the following info be included generally about the filter mode:*
Regardless of what mode the agent filter is operating in, the agent realm will continue to function, if configured. This can therefore lead to a situation where the agent realm component may malfunction or may result in the negative evaluation of J2EE security policies configured in the application's deployment descriptors or being used through the J2EE programmatic security API. To avoid this, you may disable the agent realm component, if necessary. The sections that follow describe the different agent filter modes and also tell you how to disable the agent realm.
* *Should the following info be included about the NONE filter mode:*
NONE mode:
Although this mode disables the agent filter from taking any action on the incoming requests other than logging, it has no effect on the agent realm that may still be configured in your deployment container and may get invoked by the deployed application if the deployed application has J2EE security policies in its descriptors or uses programmatic security. With the agent filter disabled, these applications will fail to evaluate the J2EE security policies correctly and as a result the deployed application may malfunction. In order to fully disable the agent, you must therefore ensure that the agent realm is not active. Refer to the section Disabling the Agent Realm to find out how the agent realm can be disabled for your agent installation. Once you have disabled the agent realm and the filter mode is set to NONE, it is functionally equivalent to not having the agent in your system at all.
* *Should the following info be included about the SSO_ONLY filter mode:*
SSO_ONLY mode:
In this mode of operation the agent realm is not used and can be safely disabled.
* *Should the following info be included about the J2EE_POLICY filter mode:*
J2EE_POLICY mode:
This mode requires that you configure the agent realm in the application server.
* *Should the following info be included about the URL_POLICY filter mode:*
URL_POLICY mode:
This mode does not require the agent realm to be functional; you can safely disable the realm.
* *Should the following info be included about the ALL filter mode:*
ALL:
This mode requires that you configure the agent realm in the application server.
\\
\\
----