Use Web Agent in Dynamically Scaled Environments

Using Docker containers and container platforms like OpenShift TM, introduces scenarios where containers with Web Agents can be frequently instantiated, or destroyed, as they are scaling up or down based on the load that is caused by incoming requests. These scenarios require taking a different approach when registering those Web Agent instances.
Using Docker containers and container platforms like OpenShift TM, introduces scenarios where containers with Web Agents can be frequently instantiated, or destroyed, as they are scaling up or down based on the load that is caused by incoming requests. These scenarios require taking a different approach when registering those Web Agent instances.
To encrypt the communication between Web Agents and the Policy Server, each Policy Server and Web Agent share an encryption key (also called Shared Secret) for establishing trusted connections. The agent stores this shared key in an encrypted format in the SmHost.conf file. To register a new agent in a conventional environment, a trusted host object with a shared secret is created in the policy store by executing smreghost on the Web Agent host. This shared secret is also encrypted with the agent's host id and then written to the SmHost.conf file of the agent host. To handle rapid registration and removal of containers that are running web servers with the Web Agents, it is required that instances of the same Web Agent would use the same trusted host. To do this, you must assign a trusted host to each logical application (rather than to each agent instance) and must use the shared secret of the trusted host whenever you are initializing a new Web Agent container of that application.
To use a specific shared secret when creating a SmHost.conf file, use the smreghost command with -sh option. When you use -sh option, smreghost does not contact the Policy Server and it expects the user to specify the shared secret that is stored in the trusted host object. The provided shared secret is then encrypted with the container's host id and stored in the SmHost.conf file of the agent. In this case, because there is no communication with the Policy Server, there is no need to provide the SSO administrator's user name and password. Ensure that the shared secret that is provided to the smreghost command is secured and treated as sensitive data.
Register the Web Agent
To register the Web Agents in dynamically scaled environments, you must specify the shared secret using smreghost. Do the following steps: 
  1. Register the application 
    For each application, create a trusted host using Java Agent API SDK. Using this method you can create a new trusted host and obtain its generated shared secret in an unencrypted string format. You must save this shared secret to use as part of the data initialization of the application. You can use this approach to register all versions of the Web Agents (6x and later). The following sample code can be used to register an application, the sample code uses SDK versions 12.5 and up. You can also use SDK version 12.0 by removing the lines that handle FIPS mode:
    import com.netegrity.util.Fips140Mode;
    public class RegisterApp {    
        private static final int EXIT_FAILURE = -1;
        private static final int EXIT_SUCCESS = 0;
        public static void main(String[] args) {    
        Fips140Mode fipsMode = Fips140Mode.getFips140ModeObject();    
        //Set the Fips Mode after reading it from the env variable    
        int status = EXIT_FAILURE;
        String address = "policyserverhostname";    
        String filename = "smhost.conf"; //note that this file, although generated, does not get used    
        String hostname = "mytrustedhostname";    
        String hostconfig = "my_hco";    
        String username = "siteminderadmin";    
        String password = "adminpassword";    
        boolean bRollover = false;    
        boolean bOverwrite = true;    
        SmRegHost reghost = new SmRegHost(address, filename,hostname,hostconfig,username,    
        try {
            status = EXIT_SUCCESS;    
        catch (Exception e)
           { //The Method close() is available only in CA SSO 12.7 and up.         
        System.out.println(reghost.getSharedSecret()); // the cleartext shared secret is displayed     
  2. Initialize Agent Instance 
    For each agent instance (for each web server instance running inside a container), use the smreghost -sh option to write an SmHost.conf file with the shared secret of the trusted host.  Example:
    C:\Program Files\CA\webagent\bin>smreghost.exe -i -hn test -hc hostconfig -sh "+G18kTDU6/16rO45S041FbfODxwSgSouNZe+ctxeDAJ4sHwoiQ4wOm+89cbaGSXIGCMQHH9+
     On successful registration and initialization of the application, the following message is displayed: “Host Registration written to SmHost.conf".
On Unix platforms, ensure that the sensitive information is not recorded in the .bash_history file. To do this, execute smreghost -sh from a script and not from bash. If sensitive information is recorded in the .bash_history file, use shred command to delete .bash_history file securely. Do not use remove (rm) command in this case.
Considerations When Using Web Agent in a Dynamically Scaled Environment
Agent Discovery
To avoid every agent container instance being reported separately as part of the Agent Discovery feature, and to avoid many agent instance objects created in the policy store, use the same AgentId.dat file with all the containers of the same application. Copy the AgentId.dat file to each container of the same application during its initialization.
Dynamic Shared Secret Rollover Configuration
Shared secret rollover is not supported in dynamically scaled environments and must be disabled for agents running in a container. Use the following option when you create the trusted host object to disable shared secret rollover, as shown in the sample code for registering an application:
bRollover = false
If you do not disable the rollover option, the running agent containers roll their original shared secret to the new shared secret when the rollover occurs, but new agent containers continue to be initialized using the old shared secret. Creating agents using the old shared secret continues to work until the next shared secret rollover, when the original shared secret is not going to be relevant anymore. This is because only two iterations of the shared secret are maintained on the Policy Server for each trusted host.
Manage FIPS mode in the dynamically scaled environments
In an environment where Policy Server is set to FIPS ONLY mode, clients that are not using FIPS ONLY mode will not be allowed to connect to the Policy Server. To set the SDK program to use FIPS ONLY mode, do one of the following: 
  1. Set the fipsMode value in the JAVA program code using Java Agent API Fips140Mode setMode method:
    For example:
  2. Configure the default FIPS mode by defining the CA_SM_PS_FIPS140 environment variable. To do this, set the following environment variable before running the SDK program (RegisterApp) :
Frequently Asked Questions
  1. How does this approach impact the ability to re-register the smhost file?
    Avoid using smreghost to overwrite a trusted host (-o). Using the overwrite option generates a new shared secret and overwrites the one currently stored in the trusted host. This prevents all the agents that are using the trusted host from connecting to the Policy Server. You can use one of the following options to resolve the scenario: :
    • Re-register the agents using smreghost -sh command and the new shared secret as detailed in step 2 of Register the Web Agent. 
    • Revert to the old shared secret of the trusted host. You can use XPSImport to restore the old shared secret back to the trusted host.
  2. If the data in the container is lost when it spins down, how can I save the agent logs outside the container?
     You can use tools such as Logstash or FluentD to collect and save the logs outside the container.
  3. Is it possible to isolate the container that is causing problem?
    When running agents in containers you might have many container instances of the same agent, serving the same application. Currently, you can retrieve the following information to identify the container that is causing problems:
    • Agent Name reported by the agent (which would be the same for all the container instances of that agent). This information can be found in the audit log and trace log of the Policy Server. 
    • Agent IP address reported in the trace log.
  4. Can I create additional containers when the performance load demands it?
    SSO Web Agent containers are expected to scale up by spinning up more instances to handle heavy load of requests. You should test your system against the expected load to ensure that the Policy Servers can handle the expected load coming from the agents.
  5. Do I need to apply JCE (Unlimited Cryptography) patch to the JRE in dynamically scaled environments? 
    Yes. As part of preparing the Java environment, you must configure JCE (Unlimited Cryptography) to support unlimited key strength.