Add Security Token Assertion
The Add Security Token assertion signifies that one of the following security tokens should be added to the SOAP security header in the target message:
Add Security Tokenassertion signifies that one of the following security tokens should be added to the SOAP security header in the target message:
SAML Assertion (Token)
To learn more about changing the WSS Recipient for this assertion, see Change the WSS Assertion Recipient.
Configure the Private Key for SAML Assertions
When you add a "SAML Assertion" as the Security Token Type, configure the Add Security Token assertion with the correct private key. The key that is used is based on the SAML Assertion type.
SAML Assertion type
Configured Private Key
Must be the subject's key.
Must be the sender's key.
Can be either the default private key for the Gateway or some other custom key.
For more information about the SAML Assertion types, see Configuring SAML Policies for Identity Bridging.
If this assertion targets a message other than the response, add the Add or Remove WS-Security Assertion after the Add Security Token assertion in the policy. This is required for the token to be applied.
Request: Add Security Token Request: Apply WS-Security
When WS-Security is involved, be sure to specify the appropriate WSS header handling option in the properties of the routing assertion. In most instances, the setting "
Don't modify the request Security header" is appropriate.
Using the Assertion
- 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.
- Right-click <target>:Add [Signed] Security Tokenin the policy window and chooseSecurity Token Propertiesor double-click the assertion in the policy window. The assertion properties are displayed.
- Choose a Security Token Type to add and configure as required:
- WS-S UsernameToken
- WS-SC SecurityContextToken
- SAML Assertion
- WS-S EncryptedKey
- Set theInclude Security TokeninMessage Signaturecheck box as required:
- Select this check box if you want the added token to be signed. (This occurs even if the token itself is responsible for the signing.) The assertion name in the policy window appears as "Add Signed Security Token".
- Clear this check box to include the token in the Security header but not sign it. Other parts of the message may still be signed if so configured. The assertion name in the policy window appears as "Add Security Token".
- Click [OK] when done.
Add a WS-S UsernameToken
Configure the settings specific to each security token type:
Select this check box to include the password in the token.
When the Include Password check box is selected, this adds a
wsse:Passwordelement to the security token in the target message:
This applies only where a password is:
Use Last Gathered Request Credentials
Choose this option to use the credentials from the most recently gathered request.
Use Specified Credentials
Choose this option to use credentials that you specify here:
Signature Key Reference
Choose the method to use to embed the signing certificate:
Add a WS-SC SecurityContextToken
- Session Variable Name: Enter the context variable containing theWS-SecureConversation Security Context. This is typicallyscLookup.session, which is defined in the Look Up Outbound Secure Conversation Session Assertion.You can use an indexing option to specify a value from a multivalued context variable. For example, use foo to select the second value in the multivalued variable foo. For more information, see "Indexing Options during Interpolation" in Multivalued Context Variables.
- Include SecurityContextToken in message: The default is to add a SecurityContextToken (SCT) in the message when it is decorated.Tip:You may need to clear this check box when decorating responses to a WCF client.
Add a SAML Assertion
When adding a SAML Assertion as the security token, ensure that the Add Security Token assertion is configured with the correct private key. For more information, see "Configure the Private Key for SAML Assertions" earlier in this topic.
- SAML Assertion Variable: Enter the context variable containing the SAML Assertion (Token). This is typicallyissuedSamlAssertion, which is defined in the Create SAML Token Assertion.You can use an indexing option to specify a value from a multivalued context variable. For example, use foo to select the second value in the multivalued variable foo. For more information, see "Indexing Options during Interpolation" in Multivalued Context Variables.
Add a WS-S EncryptedKey
No further configuration is required for token type WS-S EncryptedKey. The Gateway creates a new EncryptedKey and includes it in the target message when the security requirements are applied next.
The Gateway caches the generated key and will recognize it when processing future incoming messages that refer to it by its EncryptedKeySHA1.