Fix Pack 8550

Protection of web services with endorsing tokens

An endorsing token is used to sign the SOAP message signature. An endorsing token is usually used to sign the entire <Signature> element and optionally to sign additional message parts. If transport security is used, the endorsing token must be used to sign the Timestamp in the SOAP Security header.

Endorsing supporting token assertions

Endorsing tokens are SupportingTokens in WS-Security, and can be signed and encrypted. There are four types of endorsing tokens.
  • EndorsingSupportingTokens - The token is not required to be signed or encrypted.
  • SignedEndorsingSupportingTokens - The token must be signed.
  • EndorsingEncryptedSupportingTokens - The token must be encrypted.
  • SignedEndorsingEncryptedSupportingTokens - The token must be signed.

X509Token as an endorsing token

You can configure an X509Token as an endorsing token. Configuring an X509Token as an endorsing token is similar to configuring an X509Token as an InitiatorToken in an AssymmetricBinding. To configure an X509Token as an endorsing token, you need a policy that has an X509Token contained within one of the endorsing token assertions described previously, and a <SignatureProperties> element in the server.xml file.

The following example shows a policy fragment for an X509 endorsing supporting token:
<sp:EndorsingSupportingTokens xmlns:sp="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702">
  <wsp:Policy>
    <sp:X509Token sp:IncludeToken="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702/IncludeToken/AlwaysToRecipient">
      <wsp:Policy>
        <sp:WssX509V3Token10/>
      </wsp:Policy>
    </sp:X509Token>
  </wsp:Policy>
</sp:EndorsingSupportingTokens>

After configuring the X509Token as an endorsing token, you must define the <signatureProperties> element in the server.xml file to identify the keystore and the signing key. The configuration for the <signatureProperties> element is the same as the configuration of the X509Token for the message signature. For more information, see Protection of web services with an X.509 token.

UsernameToken as an endorsing token

The configuration of a UsernameToken as an endorsingToken is similar to the configuration of a UsernameToken with PasswordDigest, except there is no HashPassword in the policy. To configure a UsernameToken as an endorsing token, you need a policy that has a UsernameToken contained within one of the endorsing token assertions described in the Endorsing supporting token assertions section.

The following example shows a policy fragment for a UsernameToken signed and encrypted endorsing supporting token. Key derivation is used:
<sp:SignedEndorsingEncryptedSupportingTokens>
  <wsp:Policy>
    <sp:UsernameToken
      sp:IncludeToken="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702/IncludeToken/AlwaysToRecipient">
      <wsp:Policy>
        <sp:WssUsernameToken10 />
        <sp:RequireDerivedKeys />
      </wsp:Policy>
    </sp:UsernameToken>
  </wsp:Policy>
</sp:SignedEndorsingEncryptedSupportingTokens>

In this sample policy fragment, the UsernameToken is signed and encrypted with the rest of the message. Then the key that is derived from the password from the UsernameToken is used to sign the message signature.

Since a UsernameToken endorsing token uses derived keys, you must implement and configure a password CallbackHandler for a provider application. For more information, see Authentication of web services clients with a UsernameToken.


Icon that indicates the type of topic Concept topic

Terms and conditions for information centers | Feedback


Timestamp icon Last updated: Monday, 21 April 2014
http://www14.software.ibm.com/webapp/wsbroker/redirect?version=phil&product=was-base-iseries&topic=cwlp_wssec_endorse_tokens
File name: cwlp_wssec_endorse_tokens.html