Create WS-Trust message

Overview

You can configure the API Gateway to create various types of WS-Trust messages. The API Gateway can act both as a WS-Trust client when generating aRequestSecurityToken (RST) message. It can also act as a WS-Trust service, or Security Token Service (STS), when generating the following messages:

  • RequestSecurityTokenResponse (RSTR)
  • RequestSecurityTokenResponseCollection (RSTRC)

A token requestor generates an RST message and sends it to the STS, which generates the required token and returns it in an RSTR message. If several tokens are required, the requestor can send up multiple RST messages in a single RequestSecurityTokenCollection (RSTC) request. The STS generates an RSTR for each RST in the RSTC message and returns them all in batch mode in an RSTRC message.

For more details on the various types of WS-Trust messages and their semantics and format, see the WS-Trust specification. For details on consuming WS-Trust messages, see Consume WS-Trust message.

Configuration

Configure the fields in the following sections.

Message types

The Create WS-Trust filter can create the following types of WS-Trust message. Select the appropriate message type based on your requirements:

  • RST:RequestSecurityToken:
    The RST message contains a request for a single token to be issued by the STS.
  • RSTR:RequestSecurityTokenResponse:
    The RSTR message is sent in response to an RST message from a token requestor. It contains the token issued by the STS.
  • RSTRC:RequestSecurityTokenResponseCollection:
    The RSTRC message contains an RSTR (containing a single issued token) for each RST that was received in an RSTC message.

General message creation settings

The settings on this tab specify characteristics of the WS-Trust message. The following fields are available:

Insert Token Type:
Select the type of token requested from the list. The type of token selected here is returned in the response from the STS. By default, the Security Token Context type is used, which is identified by the URI http://schemas.xmlsoap.org/ws/2005/02/sc/sct.

Binary Exchange:
You can use a <BinaryExchange> when negotiating a secure channel that involves the transfer of binary blobs as part of another security negotiation protocol (for example, SPNEGO). The contents of the blob are always Base64-encoded to ensure safe transmission.

Select the Binary Exchange option to use a negotiation-type protocol for the exchange of keys, such as SPNEGO. The URI selected in the Value Type field identifies the type of the negotiation in which the blob is used. The URI is placed in the ValueType attribute of the <BinaryExchange> element.

Entropy:
The client can provide its own key material (entropy) that the token issuer may use when generating the token. The issuer can use this entropy as the key itself, it can derive another key from this entropy, or it can choose to ignore the entropy provided by the client altogether in favor of generating its own entropy.

Select this option to generate some entropy, which is included in the <wst:entropy> element of the <wst:RequestSecurityToken> block.

Insert Key Size:
The client can request the key size (in number of bits) required in a<RequestSecurityToken> request. However, the WS-Trust token issuer does not have to use the requested key size. It is merely intended as an indication of the strength of security required.The default request key size is 256 bits.

Insert Lifetime:
Select this option to insert a <Lifetime> element into the WS-Trust message. Use the associated fields to specify when the message expires. The lifetime of the WS-Trust message is expressed in terms of <Created> and <Expires> elements.

Lifetime Format:
The specified date and time pattern string determines the format of the<Created> and <Expires> elements. The default format is yyyy-MM-dd'T'HH:mm:ss.SSS'Z' ,which can be altered if necessary. For more details on how to use this format, see the Javadoc for the java.text.SimpleDateFormat Java class in the Java API specification.

Insert RequestedTokenCancelled:
Select this option to insert a <RequestedTokenCancelled> element into the generated WS-Trust message.

RST creation settings

The following configuration fields specify the way in which a WS-Trust RST message is created:

Insert Request Type:
You can create two types of RST message. Select one of the following request types from the list:

  • Issue: RST message used to request the STS to issue a token for the requestor
  • Cancel: RST message used to cancel a specific token

Insert Key Type:
Select this option to insert the key type into the RST WS-Trust message.

Insert Computed Key Algorithm:
Select this option to insert the computed key algorithm into the message.

Insert Endpoint Reference:
Select this option and enter a suitable endpoint to include an endpoint reference in the RST message.

RSTR creation settings

The following configuration fields determine the way in which a WS-Trust RSTR message is created:

Insert RequestedProofToken:
Select this check box to insert a <RequestedProofToken> element into the generated WS-Trust message. The type of this token can be set to eithercomputedKey or encryptedKey using the associated list.

Insert Authenticator:
Select this option to insert an authenticator into the RSTR message.

Advanced settings

This section enables you to configure certain advanced aspects of the SOAP message that is sent to the WS-Trust service.

WS-Trust Namespace:
Enter the WS-Trust namespace to bind all WS-Trust elements to in this field. The default namespace is http://schemas.xmlsoap.org/ws/2005/02/trust .

WS-Addressing Namespace:
Select the WS-Addressing namespace version to use in all created WS-Trust messages.

WS-Policy Namespace:
Select the appropriate WS-Policy namespace from the list. The selected version selected can affect the ordering of tokens that are inserted into the WS-Security header of the SOAP message.

SOAP Version:
Select the SOAP version to use when creating the WS-Trust message.

Overwrite SOAP Method:
Select this option if the WS-Trust token should overwrite the SOAP method in the request. In this case, the token appears as a direct child of the SOAP Body element. Use this option to preserve the contents of the SOAP Header, if present.

Overwrite SOAP Envelope:
Select this option if the generated WS-Trust message should form the entire contents of the message. In other words, the generated WS-Trust message replaces the original SOAP request.

Content-Type:
Specify the HTTP content-type of the WS-Trust message. For example, for Microsoft Windows Communication Foundation (WCF), you should use application/soap+xml .

Generate Authenticator Using:
You can verify the authenticator using the Generated or Consumed message. In either case, select the appropriate type of WS-Trust message from the available options.

Related Links