Signing SAML tokens at the message level

Secure SAML tokens at the message level by enabling assertion signing.

Before you begin

Before configuring signing for SAML tokens, you must configure SAML policy sets and bindings to create SAML tokens as authentication supporting tokens, with message level integrity protection. For more information, read about securing messages using SAML. In addition, the attached SAML bindings must be application-specific bindings, not general bindings. The transform algorithm used for signing SAML assertions is different from other signed parts, while only one transform algorithm is used with general bindings.

About this task

This task specifically addresses steps for how to digitally sign a SAML token. This task does not address any of the SAML Token Profile OASIS standard requirements for SAML sender-vouches or SAML bearer tokens with regards to message parts that must be signed. To sign SAML assertions, a SOAP message must include a <wsse:SecurityTokenReference> element in the <wsse:Security> header block. The SecurityTokenReference (STR) is referenced by the message signature using a <ds:Reference> element. The security token reference must include a <wsse:KeyIdentifier> element with the ValueType value, http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.1#SAMLID, or http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.0#SAMLAssertionID, specifying the referenced assertion identifier. The <ds:Reference> element must include the URI of the STR-transform algorithm, http://docs.oasis-open.org/wss/2004/01/oasis-200401-wsssoap-message-security-1.0#STR-Transform. Use of STR-transform ensures that the SAML assertion itself is signed, not only the <wsse:SecurityTokenReference> element.

Follow these configuration steps to enable signing SAML tokens at the message level.

Avoid trouble: Using a SAML attribute callback handler is the only way to add custom attributes to a SAMLToken upon initial creation. Although you can add attributes to your SAMLToken object using the SAMLToken.addAttribute method, it will remove the digital signature on the token if it exists. It also cannot be used with encrypted SAML tokens or encrypted attributes.

Procedure

  1. Configure the message parts.
    1. From the administrative console, edit the SAML policy set, then click WS-Security > Main policy > Request message part protection.
    2. Under Integrity protection, click Add.
    3. Enter a part name for Name of part to be signed; for example, saml_part.
    4. Under Elements in Part, click Add.
    5. Select XPath Expression.
    6. Add two XPath expressions. 
      /*[namespace-uri()='http://schemas.xmlsoap.org/soap/envelope/' 
and local-name()='Envelope']/*[namespace-uri()='http://schemas.xmlsoap.org/soap/envelope/' 
and local-name()='Header']/*[namespace-uri()='http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd' 
and local-name()='Security']/*[namespace-uri()='http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd' 
and local-name()='SecurityTokenReference']
      /*[namespace-uri()='http://www.w3.org/2003/05/soap-envelope' 
and local-name()='Envelope']/*[namespace-uri()='http://www.w3.org/2003/05/soap-envelope' 
and local-name()='Header']/*[namespace-uri()='http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd' 
and local-name()='Security']/*[namespace-uri()='http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd' 
and local-name()='SecurityTokenReference']
    7. Click Apply and Save.
    8. If an application has never been started using this policy, no further action is required. Otherwise, either restart the application server or follow the instructions in the Refreshing policy set configurations using wsadmin scripting article, for the application server to reload the policy set.
  2. Modify the client bindings to sign the SAML token.
    1. From the Service client policy set and bindings panel, click WS-Security > Authentication and protection.
    2. Modify the currently configured outbound Signed message part bindings to include the new SAML part that you created.

      Under Request message signature and encryption protection, select the part reference whose status is set to Configured. This part reference will most likely be request:app_signparts.

      1. From the Available list under Message part reference, select the name of the part to be signed, as created in step 1; for example, saml_part.
      2. Click Add, and then click Apply.
      3. In the Assigned list under Message part reference, highlight the name of the part you added; for example, saml_part.
      4. Click Edit.
      5. For the Transform algorithms setting, click New.
      6. Select http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soap-message-security-1.0#STR-Transform.
      7. Click OK, click OK, and then click OK one more time.
    3. Update the SAML token GENERATOR with the custom property to indicate a digital signature with a Security Token Reference.

      Under Authentication tokens, select and edit the SAML token you want to sign.

      1. Under Custom property, click New.
      2. Enter com.ibm.ws.wssecurity.createSTR as the custom property name.
      3. Enter true as the value of the custom property.
      4. Click Apply, and then click Save.
    4. Restart the application.
  3. Modify the provider bindings to accept a signed SAML token.
    1. From the Service provider policy sets and bindings panel, click WS-Security > Authentication and protection.
    2. Modify the currently configured inbound Signed message part bindings to include the new SAML part that you created.

      Under Request message signature and encryption protection, select the part reference whose status is set to Configured. This part reference will most likely be request:app_signparts.

      1. From the Available list under Message part reference, select the name of the part to be signed, as created in step 1; for example, saml_part.
      2. Click Add, and then click Apply.
      3. In the Assigned list under Message part reference, highlight the name of the part you added; for example, saml_part.
      4. Click Edit.
      5. For the Transform algorithms setting, click New.
      6. Select http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soap-message-security-1.0#STR-Transform.
      7. Click OK, click OK, and then click OK one more time.
      8. Click Save.
    3. Restart the application.