com.ibm.websphere.wssecurity.wssapi.trust

Class WSSTrustClient

java.lang.Object

com.ibm.websphere.wssecurity.wssapi.trust.WSSTrustClient

All Implemented Interfaces:

com.ibm.wsspi.wssecurity.core.token.config.WSSConstants

public abstract class WSSTrustClient
extends java.lang.Object
implements com.ibm.wsspi.wssecurity.core.token.config.WSSConstants

When a client application needs to communicate with a business service, the business service may require the client to authenticate with a third party Security Token provider. OASIS defines multiple specifications including WS-Trust 1.2 and WS-Trust 1.3 specifically for formatting Security Token trust requests. These requests include information required by a Security Token provider to issue one or more security tokens.

The WSSTrustClient provides an interface that encapsulates the logic for formating trust requests that meet the OASIS specifications. The response from the Security Token provider is parsed and corresponding Security Tokens are returned. The client application can utilize the WSSTrustClient to authenticate to and receive the required Security Token from a Security Token provider. The Security Token is then used for communication with the business service.

WSSTrustClient is a factory class for retrieving an instance of either a WS-Trust 1.2 or WS-Trust 1.3 trust client. It is also a factory for generating instances of the ProviderConfig and RequesterConfig required by the WSSTrustClient. ProviderConfig contains configuration settings required by the Trust Client to communicate with a Security Token provider. These settings specify how the WSSTrustClient should secure the trust request and dispatch it to the Security Token provider.

Settings contained in the ProviderConfig include items such as:

Binding name Binding scope PolicySet and Binding source Loaded PolicySetConfiguration PolicySet name Port name Security token provider Security token provider's service name System Class Loader WS-Trust Namespace Application Class Loader

RequesterConfig contains configuration settings that specify the contents of a trust request. The WSSTrustClient uses these settings to format the RequestSecurityToken or RequestSecurityTokenCollection trust request.

Settings contained in the RequesterConfig include items such as:

SOAP namespace Message ID Primary RSTT elements and attributes Secondary RSTT elements and attributes User formatted XML

WSSTrustClient Issue Example: This example demonstrates the minimum lines of code necessary to request a Security Token.

The steps necessary are

Get an instance of a ProviderConfig Get an instance of a RequesterConfig Set required request settings Get an instance of the WSSTrustClient Execute WSSTrustClient Issue request

Call the WSSTrustClient.newProviderConfig method to get an instance of ProviderConfig. This method requires the WS-Trust namespace and the Security Token provider webservice address as parameters. Additional settings can be set in the ProviderConfig instance. See documentation related to ProviderConfig for detailed information.

 ProviderConfig providerConfig = WSSTrustClient.newProviderConfig(Namespace.WST13, "http://mySTS.com");
 

Call the WSSTrustClient.newRequesterConfig method to get an instance of RequesterConfig. This method requires the WS-Trust namespace as a parameter. Additional settings can be set in the RequesterConfig instance. See documentation related to RequesterConfig for detailed information.

 RequesterConfig requestConfig = WSSTrustClient.newRequesterConfig(Namespace.WST13);
 

The OASIS WS-Trust specification requires either the AppliesTo or the TokenType to be specified in a trust Issue request. In this example we set the AppliesTo endpoint address to http://w3.ibm.com/.

 requestConfig.put(RequesterConfiguration.RSTT13.APPLIESTO_ADDRESS, "http://w3.ibm.com/");
 

Call the WSSTrustClient.getInstance method to get an instance of the Trust Client. This method requires an instance of ProviderConfig to be passed in as a parameter.

 WSSTrustClient client = WSSTrustClient.getInstance(providerConfig);
 

The WSSTrustClient's issue method is then called passing in the ProviderConfig and RequesterConfig instances. This method returns the issued Security Tokens.

 List securityTokens = client.issue(providerConfig, requestConfig);
 

Issue Example:

 ProviderConfig providerConfig = WSSTrustClient.newProviderConfig(Namespace.WST13, "http://mySTS.com");
 RequesterConfig requestConfig = WSSTrustClient.newRequesterConfig(Namespace.WST13);
 requestConfig.put(RequesterConfiguration.RSTT13.APPLIESTO_ADDRESS, "http://www.ibm.com/");
 
 WSSTrustClient client = WSSTrustClient.getInstance(providerConfig);
 List<SecurityToken> securityTokens = client.issue(providerConfig, requestConfig);
 

The Issue Example results in the WSSTrustClient dispatching a SOAP envelope similar the following:

 <soapenv:Envelope xmlns:soapenv="http://www.w3.org/2003/05/soap-envelope">
   <soapenv:Header>
      <wsa:To xmlns:wsa="http://www.w3.org/2005/08/addressing">http://mySTS.com</wsa:To>
      <wsa:MessageID xmlns:wsa="http://www.w3.org/2005/08/addressing">urn:uuid:46356E02B3F39399111250884974344</wsa:MessageID>
      <wsa:Action xmlns:wsa="http://www.w3.org/2005/08/addressing">http://docs.oasis-open.org/ws-sx/ws-trust/200512/RST/Issue</wsa:Action>
   </soapenv:Header>
   <soapenv:Body>
      <wst:RequestSecurityToken xmlns:wst="http://docs.oasis-open.org/ws-sx/ws-trust/200512">
          <wst:RequestType>http://docs.oasis-open.org/ws-sx/ws-trust/200512/Issue</wst:RequestType>
          <wsp:AppliesTo xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy">
              <wsa:EndpointReference xmlns:wsa="http://www.w3.org/2005/08/addressing">
                  <wsa:Address>http://www.ibm.com/</wsa:Address>
              </wsa:EndpointReference>
          </wsp:AppliesTo>
      </wst:RequestSecurityToken>
   </soapenv:Body>
</soapenv:Envelope>
 
 

Validate Example:

This example demonstrates the minimum lines of code necessary to validate a Security Token.

The steps necessary are

Get an instance of a ProviderConfig Get an instance of a RequesterConfig Set required request settings Get an instance of the WSSTrustClient Execute WSSTrustClient Validate request

Call the WSSTrustClient.newProviderConfig method to get an instance of ProviderConfig. This method requires the WS-Trust namespace and the Security Token provider webservice address as parameters. Additional settings can be set in the ProviderConfig instance. See documentation related to ProviderConfig for detailed information.

ProviderConfig providerConfig = WSSTrustClient.newProviderConfig(Namespace.WST13, "http://mySTS.com");
 

Call the WSSTrustClient.newRequesterConfig method to get an instance of RequesterConfig. This method requires the WS-Trust namespace as a parameter. Additional settings can be set in the RequesterConfig instance. See documentation related to RequesterConfig for detailed information.

RequesterConfig requestConfig = WSSTrustClient.newRequesterConfig(Namespace.WST13);
 

To include the entire token xml in the WS-Trust ValidateTarget

XMLStructure xml = securityTokens.get(0).getXML();
requestConfig.put(RequesterConfig.RSTT13.VALIDATE_TARGET, ((OMStructure) xml).getNode().toStringWithConsume());
 

Alternatively, specify a token reference for the ValidateTarget. To access the Secuirty Token RSTR properties ProviderConfig.setIncludeRSTRProperties(boolean) must have been set true at the time the Security Token was issued.

XMLStructure ref = (XMLStructure) ((GenericSecurityToken) securityToken).getProperties().get(
   ConsumerConfig.RSTR.REQUESTEDATTACHEDREFERENCE);
OMElement tok = OMAbstractFactory.getOMFactory().createOMElement(new QName(WSSConstants.Namespace.WSSE, "UsernameToken"));
tok.addChild(((OMStructure) ref).getNode());
XMLStructure xml = new OMStructure(tok);
requestConfig.put(RequesterConfig.RSTT13.VALIDATE_TARGET, ((OMStructure) xml).getNode().toStringWithConsume());
 

In addition to returning the current status of the token specified in ValidateTarget, The Validate method may also return an issued token. Per WS-Trust specification, setting the TokenType to "http://docs.oasis-open.org/ws-sx/ws-trust/200512/RSTR/Status" (WS-Trust 1.3) will indicate to the STS that the client is only interested in the status of the token specified in ValidateTarget.

requestConfig.put(RequesterConfiguration.RSTT13.TOKENTYPE, "http://docs.oasis-open.org/ws-sx/ws-trust/200512/RSTR/Status");
 

Call the WSSTrustClient.getInstance method to get an instance of the Trust Client. This method requires an instance of ProviderConfig to be passed in as a parameter.

WSSTrustClient client = WSSTrustClient.getInstance(providerConfig);
 

The WSSTrustClient's validate method is then called passing in the ProviderConfig and RequesterConfig instances. This method returns a WSSTrustClientValidateResult object.

WSSTrustClientValidateResult result = client.validate(providerConfig, requestConfig);
 
String status = result.getStatusCode();
 

Validate Example Source Code:

ProviderConfig providerConfig = WSSTrustClient.newProviderConfig(Namespace.WST13, "http://mySTS.com");
RequesterConfig requestConfig = WSSTrustClient.newRequesterConfig(Namespace.WST13);

XMLStructure xml = securityTokens.get(0).getXML();
requestConfig.put(RequesterConfig.RSTT13.VALIDATE_TARGET, ((OMStructure) xml).getNode().toStringWithConsume());
requestConfig.put(RequesterConfiguration.RSTT13.TOKENTYPE, "http://docs.oasis-open.org/ws-sx/ws-trust/200512/RSTR/Status");
 
WSSTrustClient client = WSSTrustClient.getInstance(providerConfig);
 
WSSTrustClientValidateResult result = client.validate(providerConfig, requestConfig);
String status = result.getStatusCode();
 

The Validate Example results in the WSSTrustClient dispatching a SOAP envelope similar the following:

 <soapenv:Envelope xmlns:soapenv="http://www.w3.org/2003/05/soap-envelope">
   <soapenv:Header>
      <wsa:To xmlns:wsa="http://www.w3.org/2005/08/addressing">http://coyote.austin.ibm.com:51962/TrustServerWST13/services/RequestSecurityToken</wsa:To>
      <wsa:MessageID xmlns:wsa="http://www.w3.org/2005/08/addressing">urn:uuid:7EE8CF0F4E77D4536F1252726495795</wsa:MessageID>
      <wsa:Action xmlns:wsa="http://www.w3.org/2005/08/addressing">http://docs.oasis-open.org/ws-sx/ws-trust/200512/RST/Validate</wsa:Action>
   </soapenv:Header>
   <soapenv:Body>
      <wst:RequestSecurityToken xmlns:wst="http://docs.oasis-open.org/ws-sx/ws-trust/200512">
         <wst:TokenType>http://docs.oasis-open.org/ws-sx/ws-trust/200512/RSTR/Status</wst:TokenType>
         <wst:RequestType>http://docs.oasis-open.org/ws-sx/ws-trust/200512/Validate</wst:RequestType>
         <wst:ValidateTarget>
            <wss:UsernameToken xmlns:wss="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd" wsu:Id="usernameac5168b8-0123-1b65-b8b4-9d6bd9a2f0bb">
               <wss:Username>testuser</wss:Username>
               <wss:Nonce EncodingType="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soap-message-security-1.0#Base64Binary">cUJPC0+7Bg/v3xEwvN6Fcg==</wss:Nonce>
               <wsu:Created>2009-09-12T03:34:59Z</wsu:Created>
            </wss:UsernameToken>
         </wst:ValidateTarget>
      </wst:RequestSecurityToken>
   </soapenv:Body>
</soapenv:Envelope>
 
 

The WSSTrustClient supports issuing and validating SAMLToken Security Tokens and GenericSecurityToken Security Tokens.

If the RequestSecurityTokenResponse from the STS contains a TokenType of http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.1#SAMLV1.1 or http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.1#SAMLV2.0 then the WSSTrustClient will return a SAMLToken Security Token. Other types of tokens are returned as a GenericSecurityToken Security Tokens.

Version:

1.5, 9/28/09