Consume 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.
Consume 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.
Consume 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.SoapSTSConsumerclass in the AM SOAP STS client SDK wraps the Apache CXF classorg.apache.cxf.ws.security.trust.STSClient, providing a higher level of abstraction that makes consumption of SOAP STS instances easier to achieve. -
The
SoapSTSConsumerclass'issueToken,validateToken, andcancelTokenmethods 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
SoapSTSConsumerCallbackHandlerclass provides the means to create a callback handler initialized with state that will be encountered when consuming SOAP STS instances. TheSoapSTSConsumerCallbackHandlerinstance can be passed to an STS client. TheTokenSpecificationclass 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.
(The SOAP STS client SDK has a dependency on Apache CXF classes, which are not present in the AM API.)
To use the SOAP STS client SDK, you must compile the source code
for the SOAP STS client SDK and create a .jar file.