STS / WS-Trust Client

Examine has a simple but effective WS-Trust client that can be used to interact with a Security Token Service (STS) to obtain a token such as a SAML 1.1/2.0 token from the issuer. The STS Client tools is accessible from the Tools->STS Client tab.

To configure the STS client to send a WS-Trust RequestSecurityToken (RST) SOAP request to an STS endpoint, select the Main tab. The main configuration screen is as shown below:

Figure 9.30. STS Client - Main configuration

STS Client - Main configuration


SOAP Version

The SOAP version radio box indicates the SOAP version of the request sent to the STS Endpoint. It defaults to SOAP 1.1.

WS-Trust Version

The WS-Trust Version can be either 1.0 or 1.3 and defaults to 1.3. The WS-Trust Version maps to the following request namespaces:

Table 9.2. WS-Trust version namespace mapping

VersionNamespace
1.0http://schemas.xmlsoap.org/ws/2005/02/trust
1.3http://docs.oasis-open.org/ws-sx/ws-trust/200512


STS Endpoint

This is a required field that points to the STS endpoint service.

Specifying the <wsp:AppliesTo/> value

You can specify the AppliesTo element value by selecting the Add AppliesTo checkbox and specifying the endpoint of the target/relying service as shown below:

Figure 9.31. STS Client - WS-Trust AppliesTo

STS Client - WS-Trust AppliesTo


Consider the e.g. where the Applies To value is specified as http://localhost:9090/services/EchoService. This translates to the following XML fragment in the WST RST request sent to the STS endpoint.

<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://localhost:9090/services/EchoService</wsa:Address>
    </wsa:EndpointReference>
</wsp:AppliesTo>

Specifying the Token Type

The Token Type field can be used to specify the URI of the type of token that the STS should issue to the requestor.

Figure 9.32. STS Client - Token Type configuration

STS Client - Token Type configuration


The specified value translates directly to the <wst:TokenType/> element in the RST request. The Options button provides a convenient way to select from a default set of pre-defined Token Type values that can be selected. Note that you are not restricted to using one of these default values. If the STS you are using supports issuing a different token than what is listed here, you can specify the Token Type value directly in the text field.

Figure 9.33. STS Client - Default Token Types

STS Client - Default Token Types


Specifying the <wst:Lifetime/> value

The <wst:Lifetime/> element value is used to specify the desired valid time range (time window during which the token is valid for use) for the returned security token.

Figure 9.34. STS Client - WS-Trust Lifetime

STS Client - WS-Trust Lifetime


Select the Add Lifetime checkbox and specify the duration in seconds that the requested token must be valid for. Note that the STS may choose to ignore this value even if it is specified. If the value is specified as 300 seconds, the Lifetime element is generated as follows in the RST request:

 <wst:Lifetime xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
    <wsu:Created>2011-02-05T21:45:07.476Z</wsu:Created>
    <wsu:Expires>2011-02-05T21:50:07.476Z</wsu:Expires>
</wst:Lifetime>

Specifying the <wst:KeyType/> value

The <wst:KeyType/> is an optional URI element that indicates the type of key desired in the security token being requested. The following are the key types that can be specified in the request:

PublicKey

This option indicates that a public key token is requested. The key algorithm URI value is: WST_NS + /PublicKey where WST_NS depends on the chosen WS-Trust Version

The configuration dialog for this key type is as shown below:

Figure 9.35. STS Client - PublicKey configuration

STS Client - PublicKey configuration


If the Specify Public Key to use checkbox is enabled, then you can select the X.509 certificate that will be sent in the <wst:UseKey/> element to the STS service. Selecting the checkbox, displays the available keystores dialog from which you can select a public key that holds the certificate to be sent. For e.g. selecting the public key 'client' results in the following XML fragment being sent as part of the RST request:

 <wst:UseKey>
    <dsig:KeyInfo xmlns:dsig="http://www.w3.org/2000/09/xmldsig#">
         <ds:X509Data xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
              <ds:X509Certificate>MIICvDCCAiWgAwIBAgIE...xqECxcUnN5NZ/+HTESk4vM=</ds:X509Certificate>
         </ds:X509Data>
    </dsig:KeyInfo>
</wst:UseKey>
SymmetricKey

This option indicates that a symmetric key token is requested. The key algorithm URI value is: WST_NS + /SymmetricKey where WST_NS depends on the chosen WS-Trust Version

The configuration dialog for this key type is as shown below:

Figure 9.36. STS Client - SymmetricKey configuration

STS Client - SymmetricKey configuration


When requesting a SymmetricKey key type, it is possible to indicate the desired key size in the request. To do this, enable the Specify Entropy checkbox and specify the value of the Key Size field. It defaults to 256.

Note

Currently, the WS-Trust 1.3 Bearer Token Key Type ( http://docs.oasis-open.org/ws-sx/wstrust/200512/Bearer) is not supported

Specifying the <wst:OnBehalfOf/> element

To simulate the scenario of obtaining a token on behalf of another party, you can add the <wst:OnBehalfOf/> element that indicates that the requester is requesting a token on behalf of another entity.

The identity on whose behalf the request is being made is specified by placing a security token, <wsse:SecurityTokenReference> element, or <wsa:EndpointReference> element within the <wst:OnBehalfOf> element. To add this security token, copy-paste a valid XML fragment that represents the Security Token or EPR in the 'OnBehalfOf Element contents' text field.

The Options button provides a convenient way to add a <wsse:UsernameToken/> element directly as a child of the <wst:OnBehalfOf/> element. For e.g specifying the user as 'admin' results in the OnBehalfOf element configured as follows:

Figure 9.37. STS Client - OnBehalfOf w/UsernameToken

STS Client - OnBehalfOf w/UsernameToken


Specifying the <wst14:ActAs/> element

Even though, the STS client doesn't currently support the WS-Trust 1.4 specification in its entirety, it does provide support for the <wst14:ActAs/> element that provides some delegation functionality. Note that the <wst14:ActAs/> element is in the WS-Trust 1.4 namespace of http://docs.oasis-open.org/ws-sx/ws-trust/200802

To quote the WS-Trust 1.4 spec about the ActAs element:

This OPTIONAL element indicates that the requested token is expected to contain information about the identity represented by the content of this element and the token requestor intends to use the returned token to act as this identity. The identity that the requestor wants to act-as is specified by placing a security token or <wsse:SecurityTokenReference> element within the <wst14:ActAs> element.

The behavior is similar to the <wst:OnBehalfOf/> element, though the semantics of it are slightly different. To add this security token, copy-paste a valid XML fragment that represents the requestor's Security Token or EPR in the 'ActAs Element contents' text field.

The Options button provides a convenient way to add a <wsse:UsernameToken/> element directly as a child of the <wst14:ActAs/> element. For e.g specifying the user as 'admin' results in the OnBehalfOf element configured as follows:

Figure 9.38. STS Client - ActAs w/UsernameToken

STS Client - ActAs w/UsernameToken


HTTP configuration

The HTTP-level Authentication and/or SSL-usage for the STS client can be specified through the HTTP tab. Note that by default, neither HTTP authentication nor SSL usage is enabled for any communication initiated by the STS client.

Tip

Other aspects of the HTTP client configuration such as the Connect Timeout are configured through the global HTTP configuration page accessible through Settings->HTTP

HTTP Authentication Configuration

To specify the HTTP Authentication credentials when sending the WST RST to the STS endpoint, select the Enable HTTP Auth button as shown below:

Figure 9.39. STS Client - HTTP Authentication

STS Client - HTTP Authentication


Specify the values for the Username and Password fields and select the Authentication Type to use - which can be Basic or Digest.

The Do Preemptive Authentication checkbox if enabled, will cause the STS client to send the 'Authorization' header even before the STS endpoint prompts/challenges for authentication credentials.

SSL Configuration

If the STS endpoint is accessible over HTTPS, the SSL section can be used to configure the required Server and Client SSL Authentication settings. The Enable SSLcheckbox must be checked to enable SSL configuration. The KeyStore and TrustStore combo boxes lists all the previously configured keystores. Both the fields are optional. The KeyStore value is only required if the server requires SSL client authentication.

The TrustStore value is required if you would like Examine to verify the server certificate when performing a SSL handshake with the server. If a truststore is not configured, Examine will accept any server provided certificate.

Tip

You can leave the TrustStore value unconfigured for Web Services under development or when using self-signed certificates for the SSL endpoint

Figure 9.40. STS Client - SSL configuration

STS Client - SSL configuration


The ‘Verify Hostname’ field determines if the hostname specified in the X.509 certificate obtained during SSL handshake will be compared against the hostname of the endpoint to which the request is sent.

The ‘Refresh keystores’ link reloads all the available keystores and truststores.

WS-Security configuration

If the STS endpoint to which the STS client is sending the WST RST request is secured using WS-Security (such as UsernameToken, Signature or Encryption), then you can configure the STS client to conform to the WS-Security requirements of the endpoint by applying a pre-defined WS-SecurityPolicy-based Security Configuration as shown below:

Figure 9.41. STS Client - WSS configuration

STS Client - WSS configuration


The Available Configurations drop-down box displays all the available WS-SecurityPolicy-based Security Configurations. This option allows for re-using a global security configuration when sending the WST RST request

Please refer to the section on Global Policy-based Security Configuration for more information on how to create a security configuration that can be used by the STS client.