Add or Remove WS-Security Assertion

The Add or Remove WS-Security assertion is used to apply pending WS-Security decorations to a message or to remove security headers. You can control how to handle the WS-Security headers and the WS-Security options.
gateway90
The Add or Remove WS-Security assertion is used to apply pending WS-Security decorations to a message or to remove security headers. You can control how to handle the WS-Security headers and the WS-Security options.
This assertion should be placed after the following WS-Security assertions in a policy if the target message is the request message or a context variable:
Add Security Token
Add Timestamp
Configure WS-Security Decoration
Encrypt Element
Sign Element
 
Though it is not necessary to use the Add or Remove WS-Security assertion to apply pending decoration to the default response message, it will not cause harm and may be advantageous is some instances (for example, if you want to override the encryption recipient).
 
To learn about selecting the target message for this assertion, see Select a Target 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 <
    target
    >:
    [Apply|Clear] WS-Security
    in the policy window and choose
    WS-Security Properties
    or double-click the assertion in the policy window. The assertion properties are displayed. 
  3. Configure the properties as follows:
  4. Click [
    OK
    ]  when done.
Setting
Description
WS-Security header options
Remove and recreate matching security headers (if found)
Select this check box to remove the existing header before applying WS-Security, if there is an existing security header in the message that matches one of the target headers. This setting is the default behavior.
Clear this check box to retain the existing header(s) while applying WS-Security.
Remove all unmatched security headers
Choose this option to remove any existing WS-Security headers that do not match any of the target headers.
Clear this check box to retain all existing WS-Security headers.
This option can be used to remove all security headers when the Apply WS-Security check box is not selected.
Use MustUnderstand attribute
By default, the resulting security header will have a mustUnderstand attribute.
  • Select this check box to use the recommended mustUnderstand attribute from the resulting WS-Security header.
  • Clear this check box to omit the recommended mustUnderstand attribute from the Security header.
For the default recipient:
Indicate how to handle the default recipient for the security header:
  • Omit actor attribute
    : Do not use an actor. This setting is the default.
  • Use Layer 7 actor
    : Use the Layer 7 actor as the default actor.
Apply WS-Security
Select this check box to apply any pending WS-Security decorations, as specified in the WS-Security options displayed below.
When [
Apply WS-Security
] is used, any decorations that were applied will be cleared automatically.
Clear this check box to not apply pending WS-Security decorations to the header. The WS-Security options are disabled. Note: This is not the same as clearing the decorations, which is done using the [
Clear WS-Security
] option below .
Clear WS-Security
Select this check box to clear any pending WS-Security decorations and also any WS-Security decorations that would be applied automatically after the policy complete.
Clear this check box to allow all WS-Security decoration requirements to be processed normally.
About automatic WS-Security decoration
Automatic WS-Security decorations are those that are not currently "pending", but which will be applied automatically after the policy completes.
For example, the Require WS-SecureConversation assertion always signs the response and adds a timestamp. If this is not desirable—for example, the
API Gateway
is configured to pass-through secure conversation—choose [
Clear WS-Security
] to prevent automatic decoration.
When both [
Apply WS-Security
] and [
Clear WS-Security
] are selected, the assertion will apply all pending WS-Security and clear any automatic WS-Security decorations that would be applied automatically after the policy completes.
WS-Security options
Version
Choose the version of WS-Security to use: 1.0 or 1.1. The default <Not Specified> setting will use WSS 1.0, unless WSS 1.1 is detected or explicitly configured in the policy.
Select the default recipient certificate...
Choose which certificate to use with XML encryption:
  • Use default certificate
    : Use the default certificate for the recipient.
    The certificate is for the default recipient. To override this default recipient, see Change the WSS Assertion Recipient.
  • Use selected certificate for default recipient
    : Choose this option to browse for the certificate to use. Click [
    Select
    ] and then locate the certificate to use. Examine the certificate details displayed to ensure that it is the correct certificate.
  • Lookup default recipient by name
    : Choose this option to use the certificate of the specified default recipient. You may reference a context variable that will resolve to the recipient at run time. If more than one certificate matches the name, then the first valid certificate is used.
  • Use Certificate from Context Variable
    : Choose this option to use the context variable specified in the adjacent box.
    This context variable must contain a type X.509 certificate.