Consuming SOAP STS Instances

You consume a SOAP STS instance by sending it SOAP messages to the instance's endpoint, or by calling it using the AM SOAP STS client SDK.

SOAP STS Instance URL

SOAP STS instances' URLs are comprised of the following parts:

The SOAP STS deployment context
The string sts
The realm in which the REST STS instance is configured
The deployment URL element, which is one of the configuration properties of an STS instance

The SOAP STS deployment context comprises the base URL of the web container to which the SOAP STS .war file is deployed, and the deployment web application name.

For example, a SOAP STS instance configured in the realm myRealm with the deployment URL element soap-username-transformer and the a deployment web application name openam-soap-sts would expose a URL similar to https://soap-sts-host.com:8443/openam-soap-sts/sts/myRealm/soap-username-transformer.

The WSDL for the service would be available at https://soap-sts-host.com:8443/openam-soap-sts/sts/myRealm/soap-username-transformer?wsdl.

Consuming SOAP STS Instances Using SOAP Messages

Because an AM SOAP STS instance is a WS-Trust 1.4-compliant security token service, users can consume the instance by sending it standard WS-Trust 1.4 SOAP STS framework messages, such as RequestSecurityToken messages, passed as the payload to WSDL ports that are implemented by the security token services.

For more information about WS-Trust 1.4 security token services, see the WS-Trust 1.4 specification.

Consuming SOAP STS Instances Using the SOAP STS Client SDK

You can consume an AM SOAP STS instance by calling it using the AM SOAP STS client SDK.

The SOAP STS client SDK is based on classes in Apache CXF, an open source service framework. Apache CXF provides the org.apache.cxf.ws.security.trust.STSClient class, which encapsulates consumption of a SOAP STS service. However, using this class requires considerable expertise.

The SOAP STS client SDK makes it easier to consume AM SOAP STS instances than using Apache CXF for the following reasons:

The org.forgerock.openam.sts.soap.SoapSTSConsumer class in the AM SOAP STS client SDK wraps the Apache CXF class org.apache.cxf.ws.security.trust.STSClient, providing a higher level of abstraction that makes consumption of SOAP STS instances easier to achieve.
The SoapSTSConsumer class' issueToken, validateToken, and cancelToken methods provide the three fundamental operations exposed by SOAP STS instances. Supporting classes facilitate the creation of state necessary to invoke these methods.
Classes in the SDK provide logic to allow AM session tokens to be presented in order to satisfy the security policy bindings that mandate AM sessions as supporting tokens. The STS client obtains secret password state—keystore entry passwords and aliases, username token credential information, and so forth—from a callback handler. The SoapSTSConsumerCallbackHandler class provides the means to create a callback handler initialized with state that will be encountered when consuming SOAP STS instances. The SoapSTSConsumerCallbackHandler instance can be passed to an STS client. The TokenSpecification class provides a way to create the varying token state necessary to obtain specific tokens and create any necessary supporting state.

You can use the classes in the SOAP STS client SDK as is, or you can tailor them to your needs. For more information about the SOAP STS client SDK classes, see the source code and the Javadoc.

The SOAP STS client SDK is not part of the AM client SDK. ^[1] To use the SOAP STS client SDK, you must compile the source code for the SOAP STS client SDK and create a .jar file.

To Build the SOAP STS Client SDK

Download the AM source code.
Change to the openam-sts/openam-soap-sts directory.
Run the mvn install command.
Locate the openam-soap-sts-client-7.0.2.jar file in the openam-sts/openam-soap-sts/openam-soap-sts-client/target directory.

^[1] The SOAP STS client SDK has a dependency on Apache CXF classes, which are not present in the AM API.