Change the WSS Assertion Recipient

You can change the default WSS assertion recipient in the Policy Manager. The effect of the change will differ depending on the type of assertion:
gateway90
You can change the default WSS assertion recipient in the Policy Manager. The effect of the change will differ depending on the type of assertion:
Impact on Request Security Assertions
How this affects the
Layer7 API Gateway
On the Gateway, configuring the WSS recipient for these assertions has little effect: the Gateway ignores any security decorations in a security header that is not addressed to the Gateway itself. If the assertion specifies a foreign WSS recipient, then the assertion immediately succeeds on the Gateway with no further checks on the request.
A security header is considered addressed to the
API Gateway
when it contains one of the following Actor attributes:
secure_span
http://www.layer7tech.com/ws/policy
http://schemas.xmlsoap.org/soap/actor/next/
an empty or unspecified Actor
How this affects the 
Layer7 API Gateway
- XML VPN Client
On the XML VPN Client, configuring the WSS recipient for these assertions will configure which security header and recipient certificate to use for the security decorations. Using these assertions often causes the XML VPN Client to include security decorations not intended for the Gateway. When this happens, the Gateway processes the decorations that are intended for it and ignores the others. The Gateway can be configured to promote the foreign security header to the default security header when the request is routed to the back-end system.
The XML VPN Client includes no Actor attribute on the Security header when it is intended for the default WSS Recipient for a generic (i.e., not a Gateway) web service.
Impact on Response Security Assertions
Response security assertions control the responses returned by the 
Layer7 API Gateway
to the client. The following are the response security assertions:
Add Security Token Assertion (with target set to "Response")
Encrypt Element Assertion (with target set to "Response")
Sign Element Assertion (with target set to "Response") 
The security header in the response is created by the Gateway after the policy is finished.
How this affects the
Layer7 API Gateway
On the Gateway, configuring the WSS recipient for these assertions causes the response security header to have a specific Actor attribute value; it also causes the Gateway to use the specified certificate for any message decorations that require a recipient certificate.
Example
: The Encrypt Element Assertion encrypts the element for the specified certificate's public key instead of using the public key in the client certificate from the request (if any).
How this affects the 
Layer7 API Gateway
- XML VPN Client
On the XML VPN Client, configuring the WSS recipient for these assertions has little effect. The XML VPN Client ignores any response security decorations within a security header not addressed to it (in other words, with an Actor attribute of "secure_span", or "http://schemas.xmlsoap.org/soap/actor/next/", or an empty or unspecified Actor). If the assertion specified a foreign WSS recipient, then the assertion immediately succeeds on the XML VPN Client with no further checks on the response.
Impact on Routing Assertions that Support SAML Sender-Vouches Attachment
These assertions control the requests from the
Layer7 API Gateway
to the back-end system. The following routing assertions support SAML sender-vouches attachment:
The security header is created by the Gateway while the routing assertion is executing.
How this affects the
Layer7 API Gateway
On the Gateway, configuring the WSS recipient for these assertions has no effect unless "Attach SAML sender vouches" is selected for the back-end authentication. When this is the case, the Gateway uses the specified Actor attribute value for the security header that contains the SAML token.
How this affects the 
Layer7 API Gateway
- XML VPN Client
On the XML VPN Client, this is not applicable since the XML VPN Client never receives the routing assertions (they are filtered out from the policy it downloads).
Using the Assertion
When a WSS assertion is added to a policy, the associated WSS decoration will be written in the Security header, intended by default for the "next-in-line" recipient (the Gateway) in the SOAP message. Changing the recipient of a WSS assertion configures a different downstream recipient for the WSS decoration, with a unique Actor attribute value. This essentially bypasses the Gateway. A policy can contain multiple alternate recipients, each resulting in a separate Security SOAP header with its associated unique Actor attribute.
WARNING:
If the intended recipient does not accept or recognize Security headers that contain Actor attributes, then you must configure the Route via HTTP(S) Assertion in the policy to instruct the 
Layer7 API Gateway
to promote one of the downstream WSS recipients as the next default WSS header. To do so, select the
Promote other Security header as default before routing
option in the Other tab of the HTTP(S) Routing Properties dialog.
The procedure below provides general instruction on how to change the WSS assertion recipient. For more information, refer to the configuration instructions for each assertion. The
API Gateway
 supports both versions 1.0 and 1.1 of the WS-Security standard.
To change the WSS recipient for an individual WSS assertion
:
  1. Right-click a WSS assertion in the policy development window and then select WSS Recipient. The assertion properties are displayed.
  2. The current
    API Gateway
    is selected as the default target recipient for the WSS decoration. To change the recipient, select the
    Specific Recipien
    t option.
  3. At this point, you can either choose an existing recipient to change to, or you can change to a new recipient.
    Task
    Description
    Choose an existing recipient
    If the intended downstream recipient was already defined for another WSS assertion in the policy, then:
    1. Select the corresponding recipient's Actor attribute value from the
      Security Header
      "
      Actor
      "
      Attribute
      drop-down list.The certificate subject information for the previously configured target appears in the
      Recipient Certificate Subject
      field. 
    2. Click [
      OK
      ]. The recipient's Actor attribute value appears as an extension of the WSS assertion's name in the policy development window.
    Adding a new recipient
     
    To create a new downstream recipient, you will need access to the recipient's certificate
    To configure a new recipient for use in the WSS assertions:
    1. Click [
      Add Recipient
      ].
    2. Complete the
      Add WSS Recipient Wizard
      . When the wizard is complete, the new recipient's information appears in the
      Security Header
      "
      Actor
      "
      Attribute
      and
      Recipient Certificate Subject
      fields.
    3. Click [
      OK
      ]. The recipient's Actor attribute value appears as an extension of the WSS assertion's name in the policy development window.
    To view or edit the recipient for a WSS assertion, right-click the assertion and select WSS Recipient from the drop-down menu.
  4. Click [
    OK
    ].