Introduction

STS client pooling is a way to create a pools of STS clients on the server side to increase the performance as the bottleneck may be the STS client creation.

Client pooling can be configured and utilized automatically from login modules that need STS client to obtain SAML tickets or manually using STSClientPoolFactory class (org.picketlink.identity.federation.bindings.stspool.STSClientPoolFactory).

Using STSClientPoolFactory

STS clients are inserted into the sub pools using their configuration as a key. Therefore we have to first obtain STSClientPool instance and then initialize sub pool based on configuration with initial number of STS clients or rely on default number.

final STSClientPool pool = STSClientPoolFactory.getPoolInstance();
pool.createPool(20, stsClientConfig);
final STSClient stsc = fact.getClient(stsClientConfig);

The pool of clients is created automatically when PicketLink Federation subsystem is enabled in WildFly or EAP.

In case of pool is not created one can create own implementation of STSClientPool interface and set its instance as pool using STSClientFactory.setInstance(mySTSClientPoolInstance).

Default implementation is part of PicketLink Bindings with name  org.picketlink.identity.federation.bindings.stspool.STSClientPoolFactory.

So default pool initializatiob can look like this: STSClientFactory.setInstance(STSClientPoolFactory.getPoolInstance()).

When there is no use for STS client any more it can be returned back to the pool using:

fact.returnClient(stsc);

For checking whether given configuration has already sub pool initialized we can use

if (!fact.configExists(stsClientConfig) {
  fact.createPool(stsClientConfig);
}

When PicketLink Federation Subsystem is enabled it WildFly/EAP all pools used by our deployment are destroyed and cannot be further used.

It can be destroyed manually as well by calling following from our application.

fact.destroyPool(stsClientConfig);

Use of STSClientFactory without pooling

To use STSClientfactory without pooling, do not call setInstance() method nor enable PicketLink Federation Subsystem in WildFly/EAP.

To obtain STSClient without pooling any time call STSClientfactory.create(stsClientConfig).

Configuring login modules

To use STS client pooling with STS login modules there is one login module option:

initialNumberOfClients - set initiual number of clients for each new sub pool based on STS client configuration.

Login Module that can utilize STS client pooling:

1. org.picketlink.identity.federation.core.wstrust.auth.STSIssuingLoginModule
2. org.picketlink.identity.federation.core.wstrust.auth.STSValidatingLoginModule
3. org.picketlink.trust.jbossws.jaas.JBWSTokenIssuingLoginModule