Adapters

The adapter may specify multiple servers. Servers with equal priorities are grouped into server pools. When executing a request, the adapter will use the load-balancing settings from each individual server pool, until a successful response has been received or until all server pools have been exhausted. (Lower priority numbers indicate higher priorities.)

Load Balancing settings

The load balancing settings specify timeouts for connections and requests, the number of request attempts and eventual penalties in case a server fails to respond correctly. In the absence of failures, the load-balancer proceeds in a round-robin way. In case of failure the behavior of the load-balancer depends on the type of error. If, say, an authenticate request does not succeed because the HTTP server does not accept the credentials, the load-balancing algorithm considers the response as technically correct, and returns this response. (We assume that the various servers are properly synchronized and that e.g. failure to authenticate against one server implies failure to authenticate against all servers.) Failure to connect because a server is temporarily down, however, will cause the load-balancer to try another server (or other servers), up to the maximum number of request attempts. The offending server is penalized, which may cause it to be skipped a number of times if servers with a lower penalty are available. Since the load-balancing algorithm is adapter type agnostic, is uses callbacks to the adapter to interpret the status of a server response and to generate a proper response in case of failure.

General information

Some adapters may specify multiple servers in their configuration. when specifying multiple servers, loadbalancing settings can be configured. these adapters are:

LDAP
HTTP
Radius
GEMALTO
OCSP

Priorities

Servers with equal priorities are grouped into server pools. Lower priority numbers indicate higher priorities.

When executing a request, the adapter will use the load-balancing settings from each individual server pool, until a successful response has been received or until all server pools have been exhausted. The server configured last in the adapter configuration will be checked first. The load balancing settings specify timeouts for connections and requests, the number of request attempts and eventual penalties in case a server fails to respond correctly. In the absence or failures, the load-balancer proceeds in a round-robin way. In case of failure the behavior of the load-balancer depends on the type of error. If, say, an authenticate request does not succeed because the HTTP server does not accept the credentials, the load-balancing algorithm considers the response as technically correct, and returns this response. (We assume that the various servers are properly synchronized and that e.g. failure to authenticate against one server implies failure to authenticate against all servers.) Failure to connect because a server is temporarily down, however, will cause the load-balancer to try another server (or other servers), up to the maximum number of request attempts. The offending server is penalized, which may cause it to be skipped a number of times if servers with a lower penalty are available. Since the load-balancing algorithm is adapter type agnostic, is uses callbacks to the adapter to interpret the status of a server response and to generate a proper response in case of failure.

The XML example below lists the available load-balancing settings. Example Load-Balancing Settings

CODE

<stb:LoadBalancing>
 <stb:ConnectionTimeout>3000</stb:ConnectionTimeout>
 <stb:RequestTimeout>5000</stb:RequestTimeout>
 <stb:RequestAttempts>2</stb:RequestAttempts>
 <stb:ServerRequestAttempts>1</stb:ServerRequestAttempts>
 <stb:PenaltyLimit>100</stb:PenaltyLimit>
 <stb:ConnectionFailureWeight>50</stb:ConnectionFailureWeight>
 <stb:ConnectionFailureThreshold>4</stb:ConnectionFailureThreshold>
 <stb:HighLoadThreshold>1000</stb:HighLoadThreshold>
 <stb:HighLoadWeight>2</stb:HighLoadWeight>
</stb:LoadBalancing>

Server Pool and ServerRequestAttempts

If a server pool contains 3 servers and the number of requests per server is 2, then the load-balancer will attempt at most 6 requests for that pool. If the maximum number of requests for the server pool is smaller, say 4, then at most 4 attempts will be made. In the degenerate case of a pool with a single server, only the RequestAttempts value will be used.

Load-balancing Settings reference

Parameter	Description	Required
ConnectionTimeout	Timeout to connect (milliseconds)
RequestTimeout	Timeout to read the response (milliseconds)
RequestAttempts	Maximum number of request per server pool if set to 0 there is no limit this number must be at least equal to the number of servers configured in the adapter
ServerRequestAttempts	Maximum number of requests per sever	x
PenaltyLimit	Limit for server penalties if set to 0 there is no limit
ConnectionFailureThreshold	Number of times for connection or request to timeout before increasing the server penalty
ConnectionFailureWeight	The step to use to increase the amount up to the penalty limit
HighLoadThreshold	If the request takes longer than this amount, increase the server penalty (milliseconds)
HighLoadWeight	The step to use to increase the amount up to the server penalty if the server responds slowly

Key & Truststores

The following adapters can be configured to use SSL for communication to a third-party backend system:

HTTP
LDAP

The use of SSL requires the creation of a trust and/or keystore:

Trust store: stores public certificates
Key store: stores either private keys or the combination of private key with their corresponding certificate

Some important remarks:

Both the stores can co-exist,
the keystore is used as truststore if no explicit truststore is defined.

From security point of view, it is recommended to make a clear distinction between a truststore and a keystore:

A truststore does only contain public certificates making it ideal to share with other people.
A keystore on the other hand does contain private keys, which must be kept private.

Configuration

Type

Both the key- and truststore are Java Keystores (JKS), a repository of security certificates, which can be created by broad range of free and commercial tools

Location

The location of the stores depends on the parameter "SecurityProtocol" selected in the adapter:

Where

Default: uses the configuration as configured in the underlying application server
WAS: uses the key- and truststore as configured in WebSphere
NONE: no SSL is used
TLSV1, SSLV3: uses the key- and/or truststore as defined in the TrustBuilder config.xml

Usage

Certificate Validation

If required a specific adapter can allow you to specify a certificate to validate against, if not the truststore is being used as a validation mechanism. Ie. if a certificate in the truststore can be used to validate the connection it will be allowed.

Mutual SSL

As for the validation against the certificate, if a private key is needed this can be identified in the specific adapter and looked up in the keystore defined either in the config.xml or externally.

Classpath

It is possible to use the stores in your classpath. To use the key/truststore in your classpath you must include the leading / in front of you keystore file in the config.

Available adapters

The template beneath is used to describe the functionality for each adapter and how it can be used.

Functionality A short description describing the function of the adapter

Prerequisites Things to do before the adapter can be used

Connection Settings Details the parameters required to connect to a third-party resource

Workflow Settings Details the parameters that must be set to use the adapter in a workflow.

Request - API List of methods made available by the adapter

Response - API The response returned by the adapter as a result of a request

Response Codes List of possible response codes

Additional Notes Some side remarks