CA API Gateway 9.1

9.4 9.1

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:
gateway90
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:
WS-S UsernameToken
WS-SC SecurityContextToken
SAML Assertion (Token)
WS-S EncryptedKey
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.
Contents:
The Add Security Token assertion only adds the token to the list of pending decoration requirements for the message. The token is added when the Add or Remove WS-Security Assertion executes. 
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
Holder-of-Key
Must be the subject's key.
Sender Vouches
Must be the sender's key.
Bearer
Can be either the default private key for the Gateway or some other custom key.
None
Can be either the default private key for the Gateway or some other custom key.
To learn more about selecting a private key for this assertion, see Select a Custom Private Key.
For more information about the SAML Assertion types, see Configuring SAML Policies for Identity Bridging.
Applying WS-Security
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
To learn about selecting the target message for this assertion, see Select a Target Message.
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
  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
    >:
    Add [Signed] Security Token
     in the policy window and choose
    Security Token Properties
     or double-click the assertion in the policy window. The assertion properties are displayed.
  3. Choose a Security Token Type to add and configure as required:
    • WS-S UsernameToken
    • WS-SC SecurityContextToken
    • SAML Assertion
    • WS-S EncryptedKey
  4. Set the
    Include Security Token
     in
    Message Signature
     check 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".
  5. Click [
    OK
    ] when done.
Add a WS-S UsernameToken
Configure the settings specific to each security token type:
Setting
Description
Include Password
Select this check box to include the password in the token.
When the Include Password check box is selected, this adds a
wsse:Password
element to the security token in the target message:
<wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText">password>
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:
  • Username
    : Enter the user name to use.
  • Password
    : Enter the password to use. Available only when the password is included.
    • Choose [
      Show Password
      ] if you want the password text to be visible as it is typed in.
    • Clear [
      Show Password
      ] to display an obfuscated password, for more security.
  • Include Nonce
    : Select this check box to include a nonce in the token.
  • Use Password Digest
    : Select this check box to calculate and display a digest password in the Password element of the UsernameToken. Clear this check box to use the basic password as entered in the Password field for the Password element. Available only when [Include Password] is selected.
  • Encrypt: Select this check box to encrypt the token.
Signature Key Reference
Choose the method to use to embed the signing certificate:
  • BinarySecurityToken
    : The certificate is embedded within the message and does not require the recipient to possess a copy of the signing certificate already. This results in larger messages, but is more compatible. This setting is the default.
  • SecurityTokenReference with SKI
    : Use SecurityTokenReference containing the SubjectKeyIdentifier (SKI). This produces smaller messages, but at the risk of decreased compatibility.
  • Issuer Name/Serial Number
    : Use a SecurityTokenReference containing the certificates issuer distinguished name and serial number. This produces smaller messages, but at the risk of decreased compatibility.
Add a WS-SC SecurityContextToken
  • Session Variable Name
    : Enter the context variable containing the
    WS-SecureConversation Security Contex
    t. This is typically
    scLookup.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[1] 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 typically
    issuedSamlAssertion
    , 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[1] 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.

Content feedback and comments