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:
The SOAP version radio box indicates the SOAP version of the request sent to the STS Endpoint. It defaults to SOAP 1.1.
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
| Version | Namespace |
|---|---|
| 1.0 | http://schemas.xmlsoap.org/ws/2005/02/trust |
| 1.3 | http://docs.oasis-open.org/ws-sx/ws-trust/200512 |
This is a required field that points to the STS endpoint service.
You can specify the AppliesTo element value by selecting the 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>
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 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.
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 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>
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:
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:
If the 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>
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:
When requesting a SymmetricKey key type, it is possible to
indicate the desired key size in the request. To do this, enable the
checkbox and specify the
value of the Key Size field. It defaults to
256.
Currently, the WS-Trust 1.3 Bearer Token Key Type (
http://docs.oasis-open.org/ws-sx/wstrust/200512/Bearer)
is not supported
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 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:
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 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.
Other aspects of the HTTP client configuration such as the Connect Timeout are configured through the global HTTP configuration page accessible through Settings->HTTP
To specify the HTTP Authentication credentials when sending the WST RST to the STS endpoint, select the 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 checkbox if enabled, will cause the STS client to send the 'Authorization' header even before the STS endpoint prompts/challenges for authentication credentials.
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 checkbox 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.
You can leave the TrustStore value unconfigured for Web Services under development or when using self-signed certificates for the SSL endpoint
The ‘’ 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 ‘’ link reloads all the available keystores and truststores.
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:
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.