Configuring Load Balancing

Load balancing requires peer servers, which are used to distribute (balance) the usage loads of the ActivID CMS servers. These multiple instances of servers (ActivID CMS Peer Servers) are referred to as a server pool. You can use a Web browser to connect your workstation to any of the servers in the pool.

This section describes how to configure ActivID CMS to work in a load-balancing environment.

Prerequisites

• The SSL credentials (server, client and issuing CA certificate) must be the same for all ActivID CMS instances.

• Before you can add peer servers to the server pool, you must install ActivID CMS on each peer server.

For more information, see Set Up the Server Pool and Add Servers to the Pool.

The configuration examples in this section use the following conventions:

• Unique server name, such as “CMSPool” (used by each Operator Portal to connect to the ActivID CMS server pool, transparently through the load balancer).

• Server S1, IP Address 200.0.0.1

• Server S2, IP Address 200.0.0.2

• Server S3, IP Address 200.0.0.3

• Server Sn, IP Address 200.0.0.n, where n is the instance number

Rules for Issuance of Mobile App Certificates

When peer servers are used in conjunction with a load balancer, specific routing rules must be set for the Over-The-Air (OTA) and Simple Certificate Enrollment Protocol (SCEP) traffic that are used by mobile phones during mobile app certificate issuance.

Each peer server is referenced by its instance number (see Set Up the Server Pool). That instance number is part of the OTA and SCEP URIs.

The load balancer must be provided with each instance number and configured to route accordingly to the corresponding peer server, without “sticky sessions”. OTA and SCEP do not use extra cookies or URI parameters outside of those expected by the protocols. The routes have to be baked into the URIs. The individual peer servers expect the complete URI and request content to be transmitted with their query parameters without any alteration (the load balancer may still alter some headers if necessary).

The OTA URI pattern is /aims/mobile/n/action where n is the peer server instance number, and action is either profile or profileUpdate.

The SCEP URI pattern is /aims/scep/n where n is the peer server instance number.

For example, /aims/mobile/3/action and /aims/scep/3 must be routed to the peer server instance number 3.

Set Up the Server Pool

1. Select a unique name for the server pool. This name applies to all SSL-related configurations. The following examples use the name “CMSPool”.

2. Set up each server to handle server pool connectivity.

   Add an entry in each server’s hosts file that identifies its own IP address as the CMSPool address.

   • In the hosts file of S1 (%SystemDir%/system32/drivers/etc/hosts), insert: 200.0.0.1 CMSPool

   • In the hosts file of S2 (%SystemDir%/system32/drivers/etc/hosts), insert: 200.0.0.2 CMSPool

   • In the hosts file of Sn (%SystemDir%/system32/drivers/etc/hosts), insert: 200.0.0.n CMSPool

3. Get the SSL credentials for the:

   • ActivID CMS server – use the certificate subject: cn=CMSPool

   • Client certificate for ActivID CMS Operator

   • Client certificate for each ActivID CMS Peer Server (to be used by other peers to synchronize information). Note that this certificate is different from the Client certificate used by the ActivID CMS operators.

   All certificates need to be stored in the same location on each ActivID CMS server.

4. Get the Issuing CA certificate.

   These credentials are used for all ActivID CMS instances installation. For more information, refer to your CA documentation.

5. Install a complete ActivID CMS system (servers and databases). In the examples that follow, the name for this installed system is “S1.” You must enroll one operator for each ActivID CMS Peer Server, using client certificates.

   Important: When you specify the location of the database during the installation, be sure to point to the database you installed during the ActivID CMS installation for S1.

   • Do not select the automatic generation of SSL credentials during ActivID CMS installation. Use the certificates you generated in step 3 (except for the peer certificate).

   • You can install the database on the same machine as the servers, or on a remote workstation.

   • Specify the server pool name (in these examples, CMSPool) for the installation of the ActivID CMS servers, and specify the real name of the database machine. This should be the same name that you specified for S1. For example, S1 for the ActivID CMS server, or S1DB if the associated database is located on another machine (database).

   • Use the same ActivID CMS Security Key Password and Database Password used for S1.

6. Use the Key Management System (KMS) to clone the Hardware Security Module (HSM) used by S1. For information, refer to About HSMs and Configuring Connections to Peer Servers. The other ActivID CMS server uses the HSM clone to store keys securely and perform cryptographic operations.

   Important: If you are using Entrust Datacard (formerly Thales) nShield™ Connect, make sure that both ActivID CMS Peer Servers have access to the same Transport Key. You might need to manually copy the transport key from the C:\nfast\kmdata folder on the original ActivID CMS server to the same location on the peer server, and then restart ActivID CMS. For more information about nShield Connect and ActivID CMS Peer Servers, refer to Configuring Entrust Datacard HSMs for Use with ActivID CMS.

7. Install ActivID CMS on machine S2 pointing to the shared database. For this, ActivID CMS has to be installed in custom installation mode (with server component only), using the same database and certificates as the ones used by S1. This machine is for load balancing. (There is no limit to the number of ActivID CMS servers in the pool.)

Add Servers to the Pool

You can add a server to the server pool:

• Using SSL communications (HTTPS). See below.

• Not using SSL communications (HTTP). See below.

The load balancing configuration you are using determines whether or not you configure the server using SSL communications.

• All the servers must point to the same database.

• Keys must be stored in the database for each configured peer server.

• Each ActivID CMS instance:

  • Has its own cache information. The peer server configuration allows each ActivID CMS instance to synchronize its internal cache.

  • Shares the same keystore, which is stored in the ActivID CMS database.

  • Shares the ActivID CMS Peer Server configuration. You must configure the Client Certificate for each peer server.

Add a Server Using SSL Communications

Important: Before adding a peer server, you must enroll the operator using the client certificate corresponding to the peer server you want to add. Refer to Managing Operators for details on how to enroll a new operator.

1. On the Operator Portal, select the Configuration tab.

2. Click Repositories. The Repositories Management page appears.

3. Click Add CMS Peer Server.

   The Peer Server Creation page appears:

   

4. In the URL field, enter the peer server URL used to access the batch API. Use the format: https:// {peer-server-hostname}:{port}/aims/enterprise/batch

5. In the Client Certificate field, enter the name of the authenticating .pfx file, which allows each server in the pool to check its status and synchronize its information to this server. For example, C:\CMS\loadbalancer\certificates\clientPeer1.pfx for PEER1, … certificates\clientPeer2.pfx for PEER2 and so on. (These certificates are stored in the same folder on every ActivID CMS peer.)

6. In the Password field, enter the password for the Client Certificate file. This is used to connect to this instance of the server. It is stored encrypted. For information about updating your password, refer to Managing Passwords.

7. In the Trusted Server Certificate field, paste the trusted CA certificate from the CA that issued the server certificate.

8. Next to Ignore Bad DNS, select Yes.

   You must select Yes when using an HTTPS connection and a load balancer because all servers share the same DNS name, and the connection between peer servers is made using IP addresses. If you do not select Yes, the server generates an error when a server certificate does not match the URL.

9. Click Create.

   The server is added under CMS Peer Servers on the Repositories Management page. For example:

   

10. Restart the IIS and CMS Server services in order to synchronize the peer servers.

Add a Server Not Using SSL Communications

1. On the Operator Portal, select the Configuration tab.

2. Click Repositories. The Repositories Management page appears.

3. Click Add CMS Peer Server.

   The Peer Server Creation page appears:

   

4. In the URL field, enter the server URL used to access the batch API in the peer server. Use the format http://hostname:port/aims/enterprise/batch.

5. In the Subject DN to insert field, paste the subject DN to insert for SSL-terminated environments. It can be a Base64 certificate or a plain subject DN string of the form CN=, depending on the setting for SSL termination.

6. Click Create.

   The server is added under CMS Peer Servers on the Repositories Management page. For example:

   

7. Restart the IIS and CMS Server services in order to synchronize the peer servers.

Check the Connectivity of the Server Pool

1. On the Operator Portal, select the Configuration tab.

2. Click Connectivity Check.

   The Connectivity Check page appears:

   

3. Click Check Connectivity.

   This runs a diagnostic that checks the connectivity of all the servers in the pool.

   

   The Diagnostic Results field shows the results from the server that is processing the request and those from each defined server instance.

Log On and Display the Operators in a Server Pool

When an operator attempts to log on, the processing server posts a transaction to each of the peer servers asking if the operator is already logged on. The server then accepts (if the operator is not already logged) or denies (if the operator is already logged on) the request.

Each server responds with the status of the logged-on operator (for example, Yes/No), IP Address, and so on. The ActivID CMS operator list shows all logged-on operators and the peer servers to which they are logged on. ActivID CMS shows the list of logged on users based on the operator name. An operator is added to the list at the beginning of the session and removed from the list when the session terminates (the operator logs off or the session expires).

Configuring Front-End SSL Termination

A load-balanced environment is not required for supporting front-end SSL termination. You can place any SSL termination product in front of the load balancer to use this functionality.

The following are two deployment examples of an ActivID CMS system with SSL termination.

• ActivID CMS running behind a load balancer with an integrated SSL module (SSL termination mode). Behind the load balancer, all connections are in HTTP or HTTPS.

• A front-end server running an Apache Web server in proxy mode, which handles the SSL connections and proxying of the requests to an ActivID CMS server. In this case, the ActivID CMS server does not need to handle the overhead of the SSL communications.

  In either configuration, ActivID CMS can process customized HTTP headers sent by the front end to validate the SSL client authenticator. For information about customizing the HTTP header, see step 6 and 7 in Configure SSL Termination.

Configure SSL Termination

1. On the Operator Portal, select the Configuration tab.

2. Click Customization.

   The Customization page appears:

   

3. In the Select a Topic drop-down list, click SSL Termination.

4. Next to SSL Termination, select Enabled.

   This enables the handling of SSL termination by allowing access using HTTP as well as HTTPS. It also specifies if this server is working with an SSL termination device in front.

5. Select Enabled or Disabled for the Accept header certificate information for HTTPS connections option.

6. In the Certificate information type drop-down list, click SubjectString or base64cert.

   This specifies what kind of information is included in the HTTP header: either a subject string directly, or a certificate image. The format of the data passed by the SSL termination device to supply certificate information depends on the vendors. The possibilities include a full certificate image or the subject DN.

7. In the HTTP Header attribute used to supply the certificate information field, enter the name of the custom HTTP header that contains information about the client certificate used to connect to the SSL termination device. For example, "https-frontend-subject".

8. In the Host used for client card synchronization field, enter the host name of the CMS Server.

9. In the Port used for client card synchronization field, enter the port of the CMS Server (for example, 8080).

10. Click Set.

11. On the Peer Server Creation page, change the URL of each specific ActivID CMS instance in the server pool from “https” to “http”. For more information, see step 10 in Add a Server Using SSL Communications.

12. Reconfigure the IIS to remove the SSL from each ActivID CMS server instance for the following Web server instances. Refer to the Microsoft IIS documentation for more information.

    • Subdirectories

    • Administration

    • MyDigitalID

Flexibility for SSL DNS Server Verification Code

This functionality accesses the AIMS portal from inside of the DMZ. This is necessary because the URL used (for example, https://AIMS1.AnyCompany.com) does not match the server certificate https://AIMS.AnyCompany.com. You can also use this functionality to handle cases of server mismatch by client code.

For ActivID CMS to obtain the logged on status from the peer servers, the following functionality is supported:

• Support for standard HTTPS connection using a client certificate.

• Support for not validating the DNS name of the server certificate. (Needed if running in a load-balanced environment without SSL termination.)

• Support for HTTP access to the peer server using custom headers to supply operator identification. (Required if running with SSL termination.)

Monitor the Server Pool Status

It is possible to retrieve the ActivID CMS server status by using a URI. It is meant to be integrated into a monitoring system to check the server status and error conditions. This API returns the status of the server in a format suitable for monitoring. It also checks the availability and status of the other backend servers required by ActivID CMS.

The syntax for this API call is:

https://<server>:<port>/aims/enterprise/batch?action=SynchronizeServers&CHECKCONNECTIVITY=YES

In order to authorize the use of this URI, you must change the value of the property AIMS.API.GetAllowed to yes in the AP_PROPERTIES table of the AIMSEE database. Then, you must restart the IIS and CMS Server services.

For example, if the audit server is not reachable or a Directory Server becomes unavailable, this API returns an HTTP error. The syntax for this API call is:

https://server:port/aims/enterprise/batch?action=SynchronizeServers&CHECKCONNECTIVITY=SERVER-ERROR

The API returns the standard HTTP Status 503 if the check connectivity fails for anything other than connectivity with peer servers.

Disable Multiple Servers Synchronization

An entry point has been added to the API to disable multiple servers temporarily from synchronizing (for example, if one of the servers is down). In this case, server synchronization is not done, but the check connectivity is still active.

The syntax used for this API call is:

https://server:port/aims/enterprise/ batch?action=SynchronizeServers&DISABLEINSTANCE=nn

where nn is the instance number.

GetStatus

This function provides information about an operator’s logged-on status. It returns information indicating whether an operator is logged on or off. ActivID CMS servers use this function internally to check if the operator is connected to another server in the pool. This function posts a transaction to the other servers when an operator logs on to check if anyone is logged on to another server.

Syntax

https://host:port/aims/batch?action=SynchronizeServers&OPERATOR=Operator,Kill=NO/YES

where:

• Operator is the name of the operator being controlled.

• Kill specifies whether the operation should be logged out (forced). Possible value is NO or YES.

For example:

https://moon:49153/aims/enterprise/batch?action=SynchronizedServers&OPERATOR=Administrator,Kill=NO

The response to the request is returned in an HTML page that contains the following:

<Response> loggedon=yes 
remoteaddress=192.168.2.211 
errorcode=0
message= 
</Response>

where message is one of the following errors.

The response to the request is returned in an HTML page that contains the following:

<Response> loggedon=yes
remoteaddress=192.168.2.211 
errorcode=0 
message=errorMessage
</Response>

where errorMessage is one of the following errors.