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:


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:


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.


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.


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.


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:

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:


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:


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:


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


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.

loading table of contents...