Web Services Security Guides › CA SiteMinder® Web Services Security Agent for IBM WebSphere Guide › Install the SiteMinder WSS Agent for WebSphere on a UNIX System › How to Configure Agents and Register a System as a Trusted Host

How to Configure Agents and Register a System as a Trusted Host

A trusted host is a client computer where one or more SiteMinder WSS Agents can be installed. The term trusted host refers to the physical system.

To establish a connection between the trusted host and the Policy Server, register the host with the Policy Server. When registration is complete the SmHost.conf file is created. After this file is created successfully, the client computer becomes a trusted host.

Gather Information Required for SiteMinder WSS Agent Configuration

The following information must be supplied during Trusted Host registration:

SM Admin User Name

The name of a Policy Server administrator allowed to register the host with the Policy Server.

This administrator should already be defined at the Policy Server and have the permission Register Trusted Hosts set. The default administrator is SiteMinder.

SM Admin Password

The Policy Server administrator account password.

Trusted Host Name

Specifies a unique name that represents the trusted host to the Policy Server. This name does not have to be the same as the physical client system that you are registering; it can be any unique name, for example, mytrustedhost.

Note: This name must be unique among trusted hosts and not match the name of any other Agent.

Host Configuration Object

The name of the Host Configuration Object in the Policy Server that defines the connection between the trusted host and the Policy Server. For example, to use the default, enter DefaultHostSettings. In most cases, you will have created your own Host Configuration Object.

Note: This value must match the Host Configuration Object entry preconfigured on the Policy Server.

Policy Server IP Address

The IP address, or host name, and authentication port of the Policy Server where you are registering the host. The default port is 44442. If you do not provide a port, the default is used.

You can specify a non-default port number, but if your Policy Server is configured to use a non-default port and you omit it when you register a trusted host, the following error is displayed:

Registration Failed (bad ipAddress[:port] or unable to connect to Authentication server (-1)

Note also that if you specify a non-default port, that port is used for the Policy Server’s authentication, authorization, and accounting ports; however, the unified server responds to any Agent request on any port. The entry in the SmHost.conf file will look like:

policyserver="ip_address,5555,5555,5555"

FIPS Encryption Mode

Determines whether the Agent communicates with the Policy Server using certified Federal Information Processing Standard (FIPS) 140-2 compliant cryptographic libraries.

FIPS Compatibility Mode (Default)

Specifies non-FIPS mode, which lets the Policy Server and the Agents read and write information using the existing CA SiteMinder® encryption algorithms. If your organization does not require the use of FIPS-compliant algorithms, the Policy Server and the Agents can operate in non-FIPS mode without further configuration.

FIPS Only Mode

Specifies full-FIPS mode, which requires that the Policy Server and Web Agents read and write information using only FIPS 140-2 algorithms.

Important! A CA SiteMinder® installation that is running in Full FIPS mode cannot interoperate with, or be backward compatible to, earlier versions of CA SiteMinder®, including all agents, custom software using older versions of the Agent API, and custom software using PM APIs or any other API that the Policy Server exposes. You must re-link all such software with the corresponding versions of the respective SDKs to achieve the required support for Full FIPS mode.

Configure a SiteMinder WSS Agent and Register a Trusted Host

You configure a SiteMinder WSS Agent and register the system that hosts it as a trusted host using the CA SiteMinder® Web Services Security Configuration Wizard.

Run the SiteMinder WSS Agent Configuration Program on UNIX or Linux Systems

You can configure your SiteMinder WSS Agents and register a trusted host immediately after installing the SiteMinder WSS Agent or at a later time; however, the host must be registered to communicate with the Policy Server.

Note: You only register the host once, not each time you install and configure a SiteMinder WSS Agent on your system.

These instructions are for GUI and Console Mode registration. The steps for the two modes are the same, with the following exceptions for Console mode:

• You may be instructed to select an option by entering a corresponding number for that option.
• You press Enter after each step to proceed through the process. The prompts should guide you through the process.
• All passwords that you enter are displayed in clear text. To workaround this issue, run the installation in GUI or unattended mode.

To configure Agents and register a trusted host

1. If necessary, start the Configuration Wizard as follows:
   1. Open a console window.
   2. Navigate to agent_home/install_config_info, where agent_home is the installed location of the SiteMinder WSS Agent.
   3. Enter one of the following commands:

      GUI Mode: ./ca-pep-config.bin

      Console Mode: ./ca-pep-config.bin -i console

   The Configuration Wizard starts.

2. Use gathered system and component information to configure the SiteMinder WSS Agent and register the host.

   Note: If you choose to configure multiple Agents, you can set the Register with same Policy Server option to register them all with the same Policy Server.

When the wizard completes, the host is registered and a host configuration file, SmHost.conf, is created in agent_home/config. You can modify this file.

agent_home

Is the installed location of the SiteMinder WSS Agent.

Installation and Configuration Log Files

To check the results of the installation or review any specific problems during the installation or configuration of a SiteMinder WSS Agent, check the CA_SiteMinder_Web_Services_Security_Install_date-time_InstallLog.log file located in WSS_Home\install_config_info.

date-time

Specifies the date and time of the CA SiteMinder® Web Services Security installation.

Modify the SmHost.conf File

SiteMinder WSS Agents act as trusted hosts by using the information in the SmHost.conf file to locate and make initial connections to a Policy Server. Once the Agent connects to the Policy Server, the initial connections are closed. Any further communication between the Agent and the Policy Server is based on settings in the Host Configuration Object that is located on the Policy Server.

You can modify portions of the SmHost.conf file to change the initial Agent-to-Policy Server connection.

To modify the SmHost.conf file

1. Navigate to the agent_home/config directory.

   agent_home

   Is the installed location of the SiteMinder WSS Agent.

2. Open the SmHost.conf file in a text editor.
3. Enter new values for the any of the following settings that you want to change:

   Important! Change only the settings of the parameters listed here. Do not modify the settings of any other parameters in the SmHost.conf file.

   hostconfigobject

   Specifies the host configuration object that defines connectivity between the Agent that is acting as trusted host and the Policy Server. This name must match a name defined in the Administrative UI.

   If you want to change the host configuration object an object so the SOA Agent uses it, you need to modify this setting.

   Example: hostconfigobject="host_configuration_object"

   policyserver

   Specifies the Policy Server to which the trusted host will try to connect. The proper syntax is as follows:

   "IP_address, port,port,port"

   The default ports are 44441,44442,44443, but you can specify non-default ports using the same number or different numbers for all three ports. The unified server responds to any Agent request on any port.

   To specify additional bootstrap servers for the Agent, add multiple Policy Server entries to the file. Multiple entries provide the Agent with several Policy Servers to which it can connect to retrieve its Host Configuration Object. After the Host Configuration Object is retrieved, the bootstrap servers are no longer needed for that server process.

   Multiple entries can be added during host registration or by modifying this parameter. If a Policy Server is removed from your CA SiteMinder® environment or is no longer in service, delete the entry.

   Important: If an Agent is configured on a multi-process web server, specifying multiple Policy Server entries is recommended to ensure that any child process can establish a connection to the secondary Policy Server if the primary Policy Server fails. Each time a new child process is started, it will not be able to initialize the Agent if only one Policy Server is listed in the file and that Policy Server is unreachable.

   Default: IP_address, 44441,44442,44443

   Example (Syntax for a single entry): "IP_address, port,port,port"

   Example (Syntax for multiple entries, place each Policy Server on a separate line):
   policyserver="123.122.1.1, 44441,44442,44443"
   policyserver="111.222.2.2, 44441,44442,44443"
   policyserver="321.123.1.1, 44441,44442,44443"

   requesttimeout

   Specifies an interval of seconds during which the Agent that is acting as a trusted host waits before deciding that a Policy Server is unavailable. You can increase the time-out value if the Policy Server is busy due to heavy traffic or a slow network connection.

   Default: 60

   Example: requesttimeout="60"

4. Save and close the SmHost.Conf file.

   The changes to the SmHost.conf file are applied.

Re-register a Trusted Host Using the Registration Tool (UNIX)

When you install a SiteMinder WSS Agent on a server for the first time, you are prompted to register that server as a trusted host. After the trusted host is registered, you do not have to re-register with subsequent agent installations. There are some situations where you may need to re-register a trusted host independently of installing an Agent, such as the following:

• To rename the trusted host if there has been a change to your CA SiteMinder® environment.
• To register a trusted host if the trusted host has been deleted in the Administrative UI.
• To register a trusted host if the trusted host policy objects have been deleted from the policy store or the policy store has been lost.
• To change the shared secret that secures the connection between the trusted host and the Policy Server.
• To recreate the SmHost.conf configuration file if it is lost.
• To overwrite an existing trusted host without deleting it first.

The registration tool, smreghost, re-registers a trusted host. This tool is installed in the agent_home/bin directory when you install a SiteMinder WSS Agent.

agent_home

Is the installed location of the SiteMinder WSS Agent.

To re-register a trusted host using the registration tool

1. Open a command prompt window.
2. Ensure that the library path environment variable contains the path to the agent bin directory.
3. Enter the following two commands:

   LD_LIBRARY_PATH=${LD_LIBRARY_PATH}:agent_home/bin

   export LD_LIBRARY_PATH

   For example, enter the following two commands:

   LD_LIBRARY_PATH=${LD_LIBRARY_PATH}:/usr/Web Services Security/wasagent/bin
   export LD_LIBRARY_PATH
   

4. Enter the smreghost command using the following required arguments:

   smreghost -i policy_server_IP_address:[port]
   -u administrator_username -p Administrator_password
   -hn hostname_for_registration -hc host_configuration_ object
   

   Note: Separate each command argument from its value with a space. Surround any values that contain spaces with double quotes (").

   See the following example:

   smreghost -i 123.123.1.1 -u SiteMinder -p mypw -hn "host computer A" 
   -hc DefaultHostSettings
   

   The following example contains the -o argument:

   smreghost -i 123.123.1.1 -u SiteMinder -p mypw -hn "host computer A"
   -hc DefaultHostSettings -o
   

   The following arguments are used with the smreghost command:

   -i policy_server_IP_ address:port

   Indicates the IP address of the Policy Server where you are registering this host. Specify the port of the authentication server only if you are not using the default port.

   If you specify a port number, which can be a non-default port, that port is used for all three Policy Server processes (authentication, authorization, accounting). The Policy Server responds to any Agent request on any port.

   Use a colon between the IP address and non-default port number, as shown in the following examples.

   Default: (ports) 44441,44442,44443

   Example: (IPv4 non-default port of 55555) -i 127.0.0.1:55555

   Example: (IPv4 default ports) -i 127.0.0.1

   Example: (IPv6 non-default port of 55555) -i [2001:DB8::/32][:55555]

   Example: (IPv6 default ports) -i [2001:DB8::/32]

   -u administrator_username

   Indicates the name of the CA SiteMinder® administrator with the rights to register a trusted host.

   -p Administrator_password

   Indicates the password of the Administrator who is allowed to register a trusted host.

   -hn hostname_for_registration

   Indicates the name of the host to be registered. This can be any name that identifies the host, but it must be unique. After registration, this name is placed in the Trusted Host list in the Administrative UI.

   -hc host_config_object

   Indicates the name of the Host Configuration Object configured at the Policy Server. This object must exist on the Policy Server before you can register a trusted host.

   -sh shared_secret

   Specifies the shared secret for the agent, which is stored in the SmHost.conf file on the local web server. This argument changes the shared secret on only the local web server. The Policy Server is not contacted.

   -rs

   Specifies whether the shared secret will be updated (rolled over) automatically by the Policy server. This argument instructs the Policy Server to update the shared secret.

   -f path_to_host_config_file

   (Optional) Indicates the full path to the file that contains the registration data. The default file is SmHost.conf. If you do not specify a path, the file is installed in the location where you are running the smreghost tool.

   If you use the same name as an existing host configuration file, the tool backs up the original and adds a .bk extension to the backup file name.

   -cf FIPS mode

   Specifies one of the following FIPS modes:

   • COMPAT--Specifies non-FIPS mode, which lets the Policy Server and the Agents read and write information using the existing CA SiteMinder® encryption algorithms. If your organization does not require the use of FIPS-compliant algorithms, the Policy Server and the Agents can operate in non-FIPS mode without further configuration.
   • ONLY--Specifies full-FIPS mode, which requires that the Policy Server and Web Agents read and write information using only FIPS 140-2 algorithms.

   Important! A CA SiteMinder® installation that is running in Full FIPS mode cannot interoperate with, or be backward compatible to, earlier versions of CA SiteMinder®, including all agents, custom software using older versions of the Agent API, and custom software using PM APIs or any other API that the Policy Server exposes. You must re-link all such software with the corresponding versions of the respective SDKs to achieve the required support for Full FIPS mode.

   If this switch is not used, or you use the switch without specifying a mode, the default setting is used.

   Default: COMPAT

   Note: More information on the FIPS Certified Module and the algorithms being used; the data that is being protected; and the CA SiteMinder® Cryptographic Boundary exists in the Policy Server Administration Guide.

   -o

   Overwrites an existing trusted host. If you do not use this argument, you will have to delete the existing trusted host with the Administrative UI before using the smreghost command. We recommend using the smreghost command with this argument.

   The trusted host is re-registered.

Register Multiple Trusted Hosts on One System (UNIX)

You typically register only one trusted host for each machine where web servers and Agents are installed. However, you can register multiple trusted hosts on one computer to create distinct connections for each CA SiteMinder® client. Using multiple trusted hosts ensures a unique shared secret and a secure connection for each client requiring communication with the Policy Server.

For most installations this is not a recommended configuration. However, it is an option for sites who require distinct, secure channels for each client or group of client applications protected by CA SiteMinder® Agents. For example, an application service provider may have many client computers with different applications installed. You may want a secure connection for each application, which you can achieve by registering multiple trusted hosts. The Policy Server then issues unique shared secrets for each client connection.

To register multiple trusted hosts, use one of the following methods:

• Registering with the Configuration Wizard: To register additional servers as trusted hosts, go through the registration process again; however, when prompted to specify a location for the SmHost.conf file, enter a unique path. Do not register a new host and use an existing web server’s SmHost.conf file or that file will be overwritten. You can use the name SmHost.conf or give the file a new name.

  Note: If you have registered a trusted host with a Policy Server and you run the Configuration Wizard to configure subsequent Agents without using a unique path for the SmHost.conf file, you will see a warning message in the Host Registration dialog box. The message reads:

  "Warning: You have already registered this Agent with a Policy Server."

• Registering with the smreghost command-line tool: Run the smreghost tool after you have completed the first Agent installation on a given computer. You can run this tool for each trusted host that you want to register.