Build RSTR SOAP Response Assertion

gateway90
After a security token is issued by the Create Security Context Token assertion, the Build RSTR SOAP Response Assertion is used to create a SOAP response message containing a RequestSecurityTokenResponse (RSTR) element. This element does the following:
  • For token issuance, the RSTR will wrap the token issued.
  • For token cancellation, the RSTR will contain a RequestedTokenCanceled element.
This assertion can create two types of responses:
  • A response that indicates a security token is being issued.
  • A response that indicates a security token is being canceled.
The following is an example of the RSTR element in a response message:
<wst:RequestSecurityTokenResponse Context="..." xmlns:wst="..."> <wst:TokenType>...</wst:TokenType> <wst:RequestedSecurityToken> // The issued security token appears here </wst:RequestedSecurityToken> ... </wst:RequestSecurityTokenResponse>
To learn about selecting the target message for this assertion, see Select a Target Message. The target message is an inbound RST Request SOAP message that provides the following useful information for building the RSTR:
  • All related namespaces such as SOAP Envelope, WS-Trust, WS-Secure Conversation, WS-Addressing, WS-Policy, WS-Security, etc.
  • Entropy in the RST request, if applicable
  • Key size in the RST request, if applicable.
To learn more about selecting the target identity for this assertion, see Select a Target Identity.
To learn about selecting the target message for this assertion, see Select a Target Message".
To learn more about changing the WSS Recipient for this assertion, see Change the WSS Assertion Recipient.
Context Variables Created by This Assertion
The Build RSTR SOAP Response assertion sets the following context variables with details of the response.
The default <prefix> is "responseBuilder" and can be changed in the assertion properties.
Variable
Description
<prefix>.
rstrResponse
Contains the RSTR SOAP response message.
<prefix>.
wsaNamespace
Contains the WS-Addressing namespace that will be used when WS-Addressing is added to the RSTR SOAP response message.
<prefix>.
rstrWsaAction
Contains the RSTR WS-Addressing Action that will be used when WS-Addressing is added to the RSTR SOAP response message.
Using the Assertion
  1. Do one of the following:
    • To add the assertion to the Policy Development window, see Add an Assertion.
    • To change the configuration of an existing assertion, proceed to step 2 below.
  2. Right-click
    Build RSTR SOAP Response
    in the policy window and choose
    RSTR SOAP Response Builder Properties
    or double-click the assertion in the policy window. The assertion properties are displayed.
  3. Specify the
    Response Message Type
    to create:
    • A response message that includes an issued a security token
      : Choose this option to create a response with the <wst:RequestSecurityTokenResponse> element, which contains the security token that was issued (either a SAML Token or a Security Context Token).
      Enter the context variable that contains the issued token.
      For Security Context Tokens, this will be the ${<prefix>.issuedSCT} variable. For SAML Tokens, this should be the ${issuedSamlAssertion} variable.
      Optionally choose any of the following RSTR Configuration options to include:
      • Include an <AppliesTo> element with WS-Addressing Address
        : This optional element is used to specify the specify the address attribute of the endpoint reference.. For example, the service(s) to which this token applies.
      • Include a <RequestedAttachedReference> element
        : Since returned tokens are considered opaque to the requestor, this optional element is used to indicate how to reference the returned token when that token does not support references using URI fragments (XML ID).
      • Include a <RequestedUnattachedReference> element
        : In certain cases, tokens do not need to be present in the message. This optional element is used to indicate how to reference the token when it is not placed inside the message.
      • Include a <KeySize> element
        : The size of the session key for a secure conversation token will be included in the generated message.
      • Set Lifetime for the returned security token
        : This lifetime defines the expiry duration of the returned security token. It is not the same as the lifetime defined in the Create Security Context Token Assertion. The default expiry duration is 60 minutes for the returned security token. 
        It is recommended that the issuer return this element with issued tokens (in the RSTR) so the requestor knows the actual validity period without needing to parse the returned token.
        For more information about the RSTR Configuration elements, please refer to the specifications on WS-Trust and WS-Secure Conversation on www.oasis-open.org.
         
      • A response message that includes the results of a token cancellation
        : Choose this option to create a response with <wst:RequestedTokenCanceled/> in the <wst:RequestSecurityTokenResponse> element.
  4. Enter a prefix to be added to the context variables created by this assertion. The prefix allows you to uniquely identify the variables if the assertion appears more than once within a policy.The default variable prefix is
    responseBuilder
    .
  5. Click [
    OK
    ].