Previous Topic: Upgrade a SOA Agent to a 12.52 WSS AgentNext Topic: Set the WebLogic Environment for the SiteMinder WSS Agent


Configure the SiteMinder WSS Agent

This section contains the following topics:

How to Configure the SiteMinder WSS Agent

SiteMinder WSS Agent for WebLogic Agent Configuration File

Agent Configuration Object

SiteMinder WSS Agent Configuration Parameters

Configure the Username and Password Digest Token Age Restriction

How to Configure the SiteMinder WSS Agent

To configure the SiteMinder WSS Agent, you must specify the following:

Note: For detailed information about how to configure Agent-related objects, see the CA SiteMinder® Policy Server Configuration Guide and the CA SiteMinder® Implementation Guide.

Follow these steps:

  1. On the Policy Server:
    1. Duplicate or create a Host Configuration Object, which holds initialization parameters for a Trusted Host.

      The Trusted Host is a server that hosts one or more Agents and handles their connection to the Policy Server.

    2. As necessary, add or edit parameters in the Host Configuration Object that you just created.
    3. Duplicate or create an Agent Configuration Object, which holds Agent configuration parameters and can be used to centrally configure a group of Agents.
    4. Add or edit required Agent parameters in the Agent Configuration Object.

      The configuration object must include the DefaultAgentName or AgentName parameter to specify the Agent identity.

    5. Create an Agent identity for the SiteMinder WSS Agent. You must select Web Agent as the Agent type for a SiteMinder WSS Agent.
  2. On the system where the SiteMinder WSS Agent is installed:
    1. Run the Agent Configuration Wizard, which registers the Trusted Host.
    2. Enable the SiteMinder WSS Agent by setting the EnableWebAgent parameter in the Agent configuration file to Yes.

SiteMinder WSS Agent for WebLogic Agent Configuration File

By default, the SiteMinder WSS Agent for WebLogic installation creates a single agent configuration file, JavaAgent.conf. The agent configuration file is located in the WSS_Home/config directory.

WSS_Home

Specifies the location where the SiteMinder WSS Agent is installed.

Each agent configuration file is created with the following required default configuration parameters/values:

Parameter

Description

DefaultAgentName

The agent identity the Policy Server uses to associate policies with the SiteMinder WSS Agent.

The default value is "SoaAgent". Do not change this value.

EnableAgent

Specifies whether the SiteMinder WSS Agent is enabled. Possible values are Yes and No.

Default value is Yes.

AgentConfigObject

The Agent Configuration Object specified during installation.

SmHostFile

Path to the local Host Configuration File. Path can be specified in absolute terms or relative to WSS_HOME.

Note: On Windows, specify paths using double backslashes ("\\") rather than single backslash ("\") to separate directories. On UNIX, use standard single slash ("/") separators.

Example values:

  • (Windows) C:\\Program Files\\CA\\Web Services Security\\wlsagent\\config\\SmHost.conf
  • (UNIX) /config/SmHost.conf

ServerName

A string that will be used in the SiteMinder WSS Agent log to identify the WebLogic Server.

Default value is "SOAWLS92".

appserverjaasloginhandler

Specifies the Application Server-specific SiteMinder WSS Agent handler class for WebLogic

Default value is "com.ca.soa.agent.appserver.jaas.wls.WlsLoginHandler". Do not change this value.

You need only edit the preconfigured values if the location of the Host Configuration File changes or you want to refer to a different Agent Configuration Object. If you use local configuration, you can add other Agent configuration parameters to these preconfigured values.

Note: Parameters that are held in the Agent configuration file are static. If you change these settings while the WebLogic server is running, the SiteMinder WSS Agent does not pick up the change until WebLogic is restarted.

The JavaAgent.conf file also contains a list of SiteMinder WSS Agent plugin classes; you do not need to alter this information.

Note: Leading and trailing whitespace in JavaAgent.conf value definitions is ignored. To include leading or trailing whitespace, quote the value (with either single or double quotes). Embedded, escaped quotes are unescaped during processing.

Sample JavaAgent.conf (Windows)

# Java Agent Configuration File
#
# This file contains bootstrap information required by
# the SiteMinder Java Agent
#
#
# Configuration for agent testagent
#
defaultagentname=soaagent
enablewebagent=yes
agentconfigobject=soaagentconfig
servername=wsdell110.systemtest.local
smhostfile=C:\\SOASecurityManager\\wlsagent\\config\\SmHost.conf
appserverjaasloginhandler=com.ca.soa.agent.appserver.jaas.wls.WLSLoginHandler
appserverjmshandler=com.ca.soa.agent.appserver.jaxrpc.jms.wls.WLSJMSMessageHandler
# Configure plugins for the agent testagent
transport_plugin_list=com.ca.soa.agent.httpplugin.pluginconfig.HttpPluginConfig, com.ca.soa.agent.jaxrpcplugin.pluginconfig.JaxRpcPluginConfig, com.ca.soa.agent.jmsplugin.pluginconfig.JMSPluginConfig
msg_body_plugin_list=com.ca.soa.agent.txmplugin.pluginconfig.TxmPluginConfig
credential_plugin_list=com.ca.soa.agent.httpplugin.pluginconfig.HttpPluginConfig, com.ca.soa.agent.txmplugin.pluginconfig.TxmPluginConfig
variable_resolver_plugin_list=com.ca.soa.agent.txmplugin.pluginconfig.TxmPluginConfig
# <EOF>

Agent Configuration Object

An Agent Configuration Object is a CA SiteMinder® policy object that holds Agent parameters for an Agent when using central agent configuration.

Note: Parameters held in an Agent Configuration Object are dynamic; if you change these settings while the WebLogic server is running, the SiteMinder WSS Agent will pick up the change.

SiteMinder WSS Agent Configuration Parameters

The following table contains a complete list of all Agent configuration parameters supported by SiteMinder WSS Agents for Application Servers.

Unless otherwise noted,you can define parameters in either the Agent Configuration Object or the Agent configuration file depending upon how you decide to configure the SiteMinder WSS Agent.

Parameter Name

Value

Description

AcceptTPCookie

 

YES or NO

(Optional) If set to yes, configures the SiteMinder WSS Agent to assert identities from third-party SiteMinder session cookies (that is, session cookies generated by custom Agents created using the SiteMinder and SiteMinder WSS SDKs.

Note: AcceptTPCookie must be set to Yes to assert identities from session cookies generated by CA SOA Security Gateway.

Default is Yes.

AllowLocalConfig

(Applies only in the Agent Configuration Object)

YES or NO

If set to yes, parameters set locally in the Agent configuration file take precedence over parameters in the Agent Configuration Object.

Default is NO.

AuthCacheSize

 

Number

(Optional) Size of the authentication cache for the SiteMinder WSS Agent (in number of entries). For example:

authcachesize="1000"

Default is 0.

To flush this cache, use the Policy Server User Interface.

AzCacheSize

 

Number

(Optional) Size of the authorization cache (in number of entries) for the SiteMinder WSS Agent. For example:

authcachesize="1000"

Default is 0.

To flush this cache, use the Policy Server User Interface.

CacheTimeout

Number

(Optional) Number of seconds before cache times out. For example:

cachetimeout="1000"

Default is 600 (10 minutes).

ConfigObject

(Applies only in Agent configuration file)

String

The name of the Agent Configuration Object associated with the SiteMinder WSS Agent.

No default value.

CookieDomain

 

String

(Optional) Name of the cookie domain. For example:

cookiedomain="ca.com"

No default value.

For more information, see the cookiedomainscope parameter.

CookieDomainScope

 

Number

(Optional) Further defines the cookie domain for assertion of SiteMinder session cookies by the SiteMinder WSS Agent. The scope determines the number of sections, separated by periods, that make up the domain name. A domain always begins with a period (.) character. For example:

cookiedomainscope="2"

Default is 0, which takes the domain name specified in the cookiedomain parameter.

DefaultAgentName

(Applies only in the Agent Configuration Object)

String

The agent identity the Policy Server will use to associate policies with the SiteMinder WSS Agent.

Default is "SoaAgent"; this value should not changed.

EnableWebAgent

(Applies only in Agent configuration file)

YES or NO

Enables or disables the SiteMinder WSS Agent. When set to 'yes', the SiteMinder WSS Agent will protect resources using the Policies configured in the Policy Server for the configured agent identity.

Default is Yes.

LogOffUri

String

(Optional) The URI of a custom HTTP file that will perform a full log off (removing the session cookie from a user’s browser). A fully qualified URI is not required. For example, LogOffUri could be set to: /Web pages/logoff.html

No default value.

PsPollInterval

Number

(Optional) The frequency with which the SiteMinder WSS Agent polls the Policy Server to retrieve information about policy changes.

Default is 30 seconds.

ResourceCacheSize

Number

(Optional) Size (in number of entries) of the cache for resource protection decisions. For example:

resourcecachesize="1000"

Default is 2000.

To flush this cache, use the Policy Server User Interface.

SAMLSessionTicketLogoffi

YES or NO

(Optional) Determines whether the SiteMinder WSS Agent should attempt to log off session tickets in SAML assertions.

Default is Yes.

ServerName

(Applies only in Agent configuration file.)

String

A string to be used in the SiteMinder WSS Agent log to identify the target application server.

SessionGracePeriod

Number

(Optional) Grace period (in seconds) between the regeneration of session tokens.

Default is 30

SmHostFile

(Applies only in Agent configuration file)

String

Path to the local Host Configuration File (typically WSS_Home\conf\SmHost.conf).

No default value.

XMLAgentSoapFaultDetails

YES or NO

(Optional) Determines whether or not the SiteMinder WSS Agent should insert the authentication/authorization rejection reason (if provided by the Policy Server) into the SOAP fault response sent to the web service consumer.

Default is No.

XMLSDKAcceptSMSessionCookie

YES or NO

(Optional) Determines whether or not the SiteMinder WSS Agent accepts an CA SiteMinder session cookie to authenticate a client.

Default is No.

If set to Yes, the SiteMinder WSS Agent uses information in a session cookie sent as an HTTP header in the request as a means of authenticating the client.

If set to No, session cookies are ignored and the SiteMinder WSS Agent requests credentials required by the configured authentication scheme.

XMLSDKMimeTypes

String

(Optional) A comma-delimited list of MIME types that the SiteMinder WSS Agent will accept for processing by CA SiteMinder® Web Services Security. All POSTed requests having one of the listed MIME types are processed. Examples:

  • text/xml
  • application/octet-stream
  • text/xml,multipart/related

If you do not add this parameter to the Agent Configuration Object, the SiteMinder WSS Agent defaults to accepting text/xml and application/soap+xml MIME types.

Configure the Username and Password Digest Token Age Restriction

By default, the WS-Security authentication scheme imposes a 60-minute restriction on the age of Username and Password Digest Tokens to protect against replay attacks.

To configure a different value for the token age restriction for a SiteMinder WSS Agent for Application Servers, set the WS_UT_CREATION_EXPIRATION_MINUTES parameter in the XmlToolkit.properties file for that agent.

Follow these steps:

  1. Navigate to WSS_Home\wlsagent\config.
  2. Open XmlToolkit.properties in a text editor.
  3. Uncomment and modify the WS_UT_CREATION_EXPIRATION_MINUTES parameter line to configure a different value for the token age restriction:
    WS_UT_CREATION_EXPIRATION_MINUTES=token_age_limit
    
    token_age_limit

    Specifies the token age limit restriction in minutes.

  4. Save and close the XmlToolkit.properties file.
  5. Restart the SiteMinder WSS Agent.