CA API Gateway 9.1

9.4 9.1

Change the WSS Assertion Recipient

 
gateway83
 
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:
Request security assertions:
How this affects the CA API - Gateway
On the Gateway, configuring the WSS recipient for these assertions has little effect: the Gateway will ignore 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 will immediately succeed 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:
How this affects the CA 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 will often cause the XML VPN Client to include security decorations not intended for the Gateway. When this happens, the Gateway will process the decorations that are intended for it and ignore 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.
Response security assertions
 These assertions control the responses returned by the Gateway to the client. The following are the response security assertions:
Add Security Token (with target set to "Response")
Encrypt Element (with target set to "Response")
Sign Element (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 CA 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 will encrypt 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 CA API Gateway - XML VPN Client
On the XML VPN Client, configuring the WSS recipient for these assertions will have little effect. The XML VPN Client will ignore 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 will immediately succeed on the XML VPN Client with no further checks on the response.
Routing assertions that support SAML sender-vouches attachment
These assertions control the requests from the Gateway to the back-end system. The following routing assertions support SAML sender-vouches attachment:
Route via HTTP(S)
Route via JMS
The security header is created by the Gateway while the routing assertion is executing.
How this affects the CA 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 will use the specified Actor attribute value for the security header that contains the SAML token.
How this affects the CA 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).
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, with a unique Actor attribute value, for the WSS decoration, essentially by-passing the Gateway. A policy can contain multiple alternate recipients, each resulting in a separate Security SOAP header with its associated unique Actor attribute.
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
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 WSS Header Handling section 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
    ].
 
 

Content feedback and comments