Exchange Credentials Using WS-Trust Assertion

The Exchange Credentials using WS-Trust assertion takes credentials gathered by a preceding credential source assertion, such as the transport-level Require HTTP Basic Credentials or message-level Require WS-Security UsernameToken Profile Credentials assertions, and sends them via a WS-Trust RequestSecurityToken (RST) SOAP request to a WS-Trust Security Token Service (STS). If the resulting SOAP response is a RequestSecurityTokenResponse (RSTR) and not a fault, and its RequestedSecurityToken element contains a valid security token (either a SAML token or a UsernameToken) the assertion will replace the current request's credentials with that token. If the message's original credentials were XML-based, then the XML element containing those credentials will be removed from the message and replaced with the RequestedSecurityToken element.
gateway90
The
Exchange Credentials using WS-Trust
assertion takes credentials gathered by a preceding credential source assertion, such as the transport-level Require HTTP Basic Credentials or message-level Require WS-Security UsernameToken Profile Credentials assertions, and sends them via a WS-Trust RequestSecurityToken (RST) SOAP request to a WS-Trust Security Token Service (STS). If the resulting SOAP response is a RequestSecurityTokenResponse (RSTR) and not a fault, and its RequestedSecurityToken element contains a valid security token (either a SAML token or a UsernameToken) the assertion will replace the current request's credentials with that token. If the message's original credentials were XML-based, then the XML element containing those credentials will be removed from the message and replaced with the RequestedSecurityToken element.
For more information about the Security Token Service, see Working with the Security Token Service.
The Exchange Credentials using WS-Trust assertion will be invalidated if the routing assertion in the policy is set to remove processed Security headers. When using the Exchange Credentials using WS-Trust assertion, you must configure the Route via HTTP(S) assertion to maintain the Security header in the message. To do so, select the "Leave current Security header in request before routing" option in the HTTP(S) Routing Properties that is used by both assertions. If the credentials in a message are covered by an XML Signature using the Sign Element assertion, then the signature will be invalidated when the credentials are replaced by the Exchange Credentials using WS-Trust assertion.
Using the Assertion
  1. Do one of the following:
    • To add the assertion to the Policy Development window, see Adding an Assertion.
    • To change the configuration of an existing assertion, proceed to step 2 below.
  2. When adding the assertion, the
    WS-Trust Credential Exchange Properties
    automatically appear; when modifying the assertion, right-click
    Exchange Credentials using WS-Trust Request...
    in the policy window and select
    WS-Trust Credential Exchange Properties
    or double-click the assertion in the policy window. The assertion properties are displayed.
  3. Configure the properties as follows:
    Setting
    Description
    WS-Trust Namespace
    From the drop-down list, select the WS-Trust namespace to use. This will determine the version of WS-Trust used by the assertion.
    • <Not Specified>:
      The system default WS-Trust namespace is used.
    • http://docs.oasis-open.org/ws-sx/ws-trust/200512:
      When this namespace is selected, the RST request messages will no longer use the "wst:Base" element for the token in "Issue" requests. Instead, a security header will be added to the message containing the token and a timestamp.
    • http://schemas.xmlsoap.org/ws/2005/02/trust:
      When this namespace is selected, the RST message uses the selected namespace and corresponding "RequestType"; the "Base" element is used. This namespace is typically used when "
      <Not Specified>
      " is selected.
      When this namespace is used, the cluster property
      wss.decorator.wsTrustRequestTypeIndex
      is respected. Changes to this property requires a restart of the Gateway. For more information, see Gateway Cluster Properties
    • http://schemas.xmlsoap.org/ws/2004/04/trust:
      When this namespace is selected, the RST message uses the selected namespace and corresponding "RequestType"; the "Base" element is used.
    Token Service URL
    Enter the complete URL of the WS-Trust Security Token Service (STS).
    The STS must be running and configured to accept RequestSecurityToken (RST) requests containing the values configured below
    wsp:Applies to URI
    Enter a URI that describes the service for which the token will be used. For example:
    urn:example.com:services:echo
    or
    http://services.example.com/EchoService
    .
    wst:Issuer URI
    Enter a URI that describes the issuer (identity provider) of the security token being sent. For example,
    urn:example.com:users
    or
    http://example.com
    .
    Request Type
    Select the type of request from the drop-down list.
    Most WS-Trust Security Token Service implementations deal with validation requests.
  4. Click [
    OK
    ]
    when done.