WAS v8.5 > Secure applications > Secure web services > Secure web services > Administer Web Services Security > Administer message-level security for JAX-WS web services > Secure messages using SAML

SAML sender-vouches token

We can configure the client and provider policy set attachments and bindings for the SAML sender-vouches token. A SAML sender-vouches token is a SAML token that uses the sender-vouches subject confirmation method. The sender-vouches confirmation method is used when a server needs to propagate the client identity or behavior of the client.

• Before we can use a SAML sender-vouches token, create one or more new server profiles, or add SAML configuration settings to an existing profile.

  Refer to the various topics that describe how to configure SAML for more information about how to add SAML configuration settings to an existing profile.

• Determine which type of security to use to protect the integrity of SOAP messages and SAML tokens so that a receiver can verify the message contents and SAML tokens were not modified by unauthorized parties. You must use either message-level security or HTTPS transport.

  As stated in section 3.5.2.1 of the SAML Token Profile specification:

  "To satisfy the associated confirmation method processing of the receiver, the attesting entity MUST protect the vouched for SOAP message content such the receiver can determine when it has been altered by another party. The attesting entity MUST also cause the vouched for statements (as necessary) and their binding to the message contents be protected such that unauthorized modification be detected."

  We can use either transport-level or message-level security to meet this SAML sender-vouches requirement:

  You must use either message-level security or HTTPS transport to protect the sender-vouches token.

  • To utilize HTTP transport-level security, configure the HTTPS transport.
  • To utilize message-level security, the SAML Token Profile Specification suggests the attesting entity "sign the relevant message content and assertions".

  To sign the relevant message content and assertions, you must at least sign the SAML token (the assertion). The relevant content is dependent on the application. The specification recommends that:

  • The sender at least sign the SOAP Body and SAML Assertion together to meet the relevant message content requirement.
  • The consumer verify the SAML token is signed with SOAP body when using SAML sender-vouches.

This procedure describes the steps you must complete to digitally sign a SAML token. It does not describe any of the SAML Token Profile OASIS standard requirements for SAML sender-vouches or SAML bearer tokens regarding message parts that must be signed.

The example provided in this procedure uses the sample web services application JaxWSServicesSamples.

The procedure for creating the sender-vouches policy set begins with creating a new SAML sender-vouches policy.

1. Create the SAML sender-vouches policy, and configure the message parts.

   You must create a SAML sender-vouches policy set, based on the SAML bear policy before we can configure the client and provider bindings for the SAML sender-vouches token, After creating the policy set, attach the bindings to the JAX-WS client and provider applications. For more information about the bearer policy sets, see the topic SAML bearer token.

   Several default SAML token application policy sets and several general client and provider binding samples are provided with the product. A policy set used for a SAML sender-vouches token is similar to one used for a SAML bearer token . The following procedure describes how to create a sender-vouches policy set based on a SAML bearer token policy set.

   Unless they are imported as a copy, the SAML20 Bearer WSSecurity default and SAML20 Bearer WSHTTPS default policies cannot be updated for use with SAML sender-vouches tokens. SAML20 Bearer WSSecurity default and SAML20 Bearer WSHTTPS default policies are not configured to sign the SAML token. To meet the requirement of SAML sender-vouches, the policy must be updated to sign the SAML token. Therefore, either the policy must be imported as a copy, or you must make a copy of the policy. The following procedure makes a copy of the policy.

   1. Import the required Policy Sets.

      The Before beginning section of the topic SAML bearer token describes how to import the Username WSHTTPS default and the SAML Bearer policy of the desired type. For example, SAML20 Bearer WSSecurity default is used for SAML 2.0 sender-vouches tokens using HTTP.

   2. Make a copy of the desired imported SAML Bearer policy that we can edit.
      1. In the dmgr console, click Services > Policy sets > Application policy sets.

      2. Select the imported SAML Bearer policy to copy.

         For example, you might select SAML20 Bearer WSSecurity default.

      3. Click Copy... .
      4. Specify the desired name in the Name field. For example, you might specify SAML20 sender-vouches.

      5. Click OK.

   3. Edit the new SAML sender-vouches policy to add digital signature of the SAML token.
      1. In the dmgr console, click Services > Policy sets > Application policy sets .

      2. Select the policy you just created.

         Using the preceding example, you would select SAML20 sender-vouches.

   4. From the dmgr console, edit the SAML policy set, then click WS-Security > Main policy > Request message part protection.

   5. Under Integrity protection, click Add.

   6. Enter a part name for Name of part to be signed; for example, saml_part.

   7. Under Elements in Part, click Add.

   8. Select XPath Expression.

   9. 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']

   10. Click Apply and Save.

   11. 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 configuration article, for the application server to reload the policy set.

2. Configure the trust client

   If you will be using general bindings to access the external STS, skip to Attach the policy set and bindings to the client application step.

   If you will be using application specific bindings to access the external STS, complete the following substeps.

   1. Temporarily Attach a policy set for the trust client to the web services client application so that bindings can be configured.

      Attaching a policy set for the trust client allows you to use the dmgr console to create, and then modify the client binding document bindings. You only have to complete this action if an application-specific binding is used to access the external STS.

      1. In the dmgr console, click Applications > Application types > WebSphere enterprise applications > JaxWSServicesSamples > Service client policy sets and bindings.

      2. Select the web services client resource (JaxWSServicesSamples).

      3. Click Attach Client Policy Set.

      4. Select the policy set Username WSHTTPS default.

   2. Create the trust client binding.

      1. Select the web services client resource again (JaxWSServicesSamples).

      2. Click Assign Binding.

      3. Click New Application Specific Binding to create an application-specific binding.

      4. Specify a binding configuration name for the new application-specific binding. In this example, the binding name is SamlTCSample.

   3. Add the SSL transport policy type to the binding,

      Click Add > SSL transport and then click OK.

   4. Add the WS-Security policy type to the binding, then modify the authentication settings for the trust client.

      1. If the he WS-Security policy type is not already in the SamlTCSample binding definition, click Applications > Application types > WebSphere enterprise applications > JaxWSServicesSamples > Service client policy sets and bindings > SamlTCSample.

      2. Click Add > WS-Security > Authentication and protection > request:uname_token.

      3. Click Apply.

      4. Select Callback handler

      5. Specify a user name and password for the web services client to authenticate to the external STS.

      6. Click OK, and then click Save.

   5. After the binding settings are saved, return to the Service client policy sets and bindings panel, and detach the policy set and bindings.

      1. Click either Service client policy sets and bindings in the navigation for this page, or Applications > Application types > WebSphere enterprise applications > JaxWSServicesSamples > Service client policy sets and bindings.

      2. Select the web services client resource (JaxWSServicesSamples), and then click Detach client policy set.

      The application-specific binding configuration you just created is not deleted from the file system when the policy set is detached. Therefore, we can still use the application-specific binding you created to access the STS with the trust client.

3. Attach the SAML sender-vouches policy set and create new application specific bindings for the client application

   You must use application-specific custom bindings instead of general bindings for sender-vouches. If you configure sender-vouches policy sets and bindings from attached bearer token policy sets and bindings, ensure the assigned bindings are application-specific bindings.

   1. Attach the desired SAML policy set to the web services client application.

      1. Click Applications > Application types > WebSphere enterprise applications > JaxWSServicesSamples > Service client policy sets and bindings.

      2. Select the web services client resource (JaxWSServicesSamples).

      3. Click Attach Client Policy Set.

      4. Select the SAML policy created.

         For example, you might select SAML20 sender-vouches.

   2. Create new application specific bindings for the client.

      1. Select the web services client resource again (JaxWSServicesSamples).

      2. Click Assign Binding.

      3. Select New Application Specific Binding....

      4. Specify a binding configuration name for the new application-specific binding.

         In this example, the binding name is SamlSenderVouchesClient.

      5. Click Add > WS-Security.

4. Edit the SAML token generator in application specific client bindings.

   1. Click Authentication and protection.

   2. Under Authentication tokens, click either request:SAMLToken20Bearer or request:SAMLToken11Bearer.

   3. Click Apply.

   4. Click Callback handler.

   5. Add the following custom properties.
      • confirmationMethod=sender-vouches
      • keyType=http://docs.oasis-open.org/ws-sx/ws-trust/200512/Bearer
      • stsURI=SecurityTokenService_address

        For example, you might specify https://example.com/Trust/13/UsernameMixed for SecurityTokenService_address.

      • wstrustClientPolicy=Username WSHTTPS default.
      • wstrustClientBinding=value

        The value we specify for wstrustClientBinding must match the name of the application specific binding of the trust client created in the previous steps. For example, if in the previous steps, you created an application specific binding named SamlTCSample, specify SamlTCSample as the value for the wstrustClientBinding property.

      • wstrustClientSoapVersion=value

        Specify a value of 1.1 for this property to use SOAP v1.1.

        Specify a value of 1.2 for this property to use SOAP v1.2.

   6. Click OK.

   7. Click WS-Security in the navigation for this page.

5. Configure general digital signature in the client bindings.

   1. Configure a Certificate Store.

      1. Click Keys and Certificates.

      2. Under Certificate store, click New Inbound... .

      3. Specify name=clientCertStore.

      4. Specify Intermediate X.509 certificate=${USER_INSTALL_ROOT}/etc/ws-security/samples/intca2.cer.

      5. Click OK.

   2. Configure a Trust Anchor.

      1. Under Trust anchor, click New...

      2. Specify name=clientTrustAnchor.

      3. Click External Keystore .

      4. Specify Full path=${USER_INSTALL_ROOT}/etc/ws-security/samples/dsig-sender.ks.

      5. Specify Password=client.

      6. Click OK.

      7. Click WS-Security in the navigation for this page.

   3. Configure the Signature Generator.

      1. Click Authentication and protection > AsymmetricBindingInitiatorSignatureToken0 (signature generator), and then click Apply.

      2. Click Callback handler

      3. Specify Keystore=custom.

      4. Click Custom keystore configuration, and then specify
         • Full path==${USER_INSTALL_ROOT}/etc/ws-security/samples/dsig-sender.ks
         • Keystore password=client
         • Name=client
         • Alias=soaprequester
         • Password=client

      5. Click OK, OK, and OK.

   4. Configure the Signature Consumer.

      1. Click AsymmetricBindingRecipientSignatureToken0 (signature consumer), and then click Apply.

      2. Click Callback handler.

      3. Under Certificates, click the Certificate store radial button, and specify:
         • Certificate store=clientCertStore
         • Trusted anchor store=clientTrustAnchor

      4. Click OK, and OK.

   5. Configure the request Signing Information.

      1. Click request:app_signparts, and specify Name=clientReqSignInfo.

      2. Under Signing key information, click New , and then specify:
         • Name=clientReqSignKeyInfo

         • Type=Security Token reference
         • Token generator or consumer name=AsymmetricBindingInitiatorSignatureToken0

      3. Click Ok, and then click Apply.

      4. Under Message part reference, select request:app_signparts .

      5. Click Edit.

      6. Under Transform algorithms, click New

      7. Specify URL=http://www.w3.org/2001/10/xml-exc-c14n#.

      8. Click OK, OK, and OK.

   6. Configure the response Signing Information.

      1. Click response:app_signparts, and specify Name=clientRespSignInfo.

      2. Click Apply.

      3. Under Signing key information, click New , and then specify:
         • Name=clientRspSignKeyInfo
         • Token generator or consumer name=AsymmetricBindingRecipientSignatureToken0

      4. Click Ok.

      5. Under Signing key information, click clientRspSignKeyinfo , and then click Add.

      6. Under Message part reference, select response:app_signparts .

      7. Click Edit.

      8. Under Transform algorithms, click New

      9. Specify URL=http://www.w3.org/2001/10/xml-exc-c14n#.

      10. Click OK, OK, and OK.

6. Configure digital signature for the SAML token in the client bindings.
   1. Modify the currently configured outbound Signed message part bindings to include the new SAML part 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.

   2. Update the SAML token consumer with the custom property to indicate digital signature with Security Token Reference

      Under Authentication tokens, select and edit the SAML token 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.

   3. Restart the application.

7. Attach the SAML sender-vouches policy set, and create new application specific bindings for the provider application.
   1. Attach the desired SAML policy set to the web services client application.

      1. Click Applications > Application types > WebSphere enterprise applications > JaxWSServicesSamples > Service provider policy sets and bindings.

      2. Select the web services client resource (JaxWSServicesSamples).

      3. Click Attach Policy Set.

      4. Select the SAML policy created.

         For example, you might select SAML20 sender-vouches.

   2. Create new application specific bindings for the provider.

      1. Select the web services client resource again (JaxWSServicesSamples).

      2. Click Assign Binding.

      3. Select New Application Specific Binding....

      4. Specify a binding configuration name for the new application-specific binding.

         In this example, the binding name is SamlSenderVouchesProvider.

      5. Click Add > WS-Security.

8. Edit the SAML token consumer in application specific provider bindings

   1. Click Authentication and protection.

   2. Under Authentication tokens, click either request:SAMLToken20Bearer or request:SAMLToken11Bearer.

   3. Click Apply.

   4. Click Callback handler.

   5. Add the following custom properties.
      • confirmationMethod=sender-vouches
      • keyType=http://docs.oasis-open.org/ws-sx/ws-trust/200512/Bearer
      • signatureRequired=true

   6. Optional: Set the trustAnySigner custom property to true to allow no signer certificate validation.

      The Trust Any certificate configuration setting is ignored for the purposes of SAML signature validation. This property is only valid if the signatureRequired custom property is set to true, which is the default value for that property.

   7. Complete the following actions if assertions are signed by the STS, the signatureRequired custom property is set to the default value of true, and the trustAnySigner custom property is set to the default value of false.

      • Add a certificate to the truststore for the provider that allows for the external STS signing certificate to pass the trust validation, such as the STS signing certificate itself or its root CA certificate.

      • Set the trustStorePath custom property to a value that matches the trust store file name. This value can be fully-qualified or use keywords such as ${USER_INSTALL_ROOT}.

      • Set the trustStoreType custom property to a value that matches the key store type. Supported keys store types include: jks, jceks, and pkcs12.

      • Set the trustStorePassword custom property to a value that matches the truststore password. The password is stored as a custom property and is encoded by the dmgr console.

      • Optional: Set the trustedAlias custom property to a value such as samlissuer. If this property is specified, the X.509 certificate represented by the alias is the only STS certificate that is trusted for SAML signature verification. If this custom property is not specified, the web services runtime environment uses the signing certificate inside the SAML assertions to validate the SAML signature and then verifies the certificate against the configured truststore.

   8. Optional: Configure the recipient to validate either the issuer name or the certificate SubjectDN of the issuer in the SAML assertion, or both.

      We can create a list of trusted issuer names, or a list of trusted certificate SubjectDNs, or we can create both types of lists. If you create both issuer name and SubjectDN lists, both issuer name and SubjectDN are verified. If the received SAML issuer name or signer SubjectDN is not in the trusted lists, SAML validation fails, and an exception is issued.

      The following example shows how to create a list of trusted issuers and trusted SubjectDNs. For each trusted issuer name, use trustedIssuer_n where n is a positive integer. For each trusted SubjectDN, use trustedSubjectDN_n where n is a positive integer. If you create both types of lists, the integer n must match in both lists for the same SAML assertion. The integer n starts with 1, and increments by 1.

      In this example, you trust a SAML assertion with the issuer name WebSphere/samlissuer, regardless of the SubjectDN of the signer, so you add the following custom property:

      <properties value="WebSphere/samlissuer" name="trustedIssuer_1"/>

      In addition, you trust a SAML assertion issued by IBM/samlissuer, when the SubjectDN of the signer is ou=websphere,o=ibm,c=us, so you add the following custom properties:

      <properties value="IBM/samlissuer" name="trustedIssuer_2"/> 
      <properties value="ou=websphere,o=ibm,c=us" name="trustedSubjectDN_2"/>  

   9. Click APPLY.

   10. Click WS-Security in the navigation for this page.

9. Configure general digital signature in the provider bindings.

   1. Configure a Certificate Store.

      1. Click Keys and Certificates.

      2. Under Certificate store, click New Inbound....
      3. Specify:
         • Name=providerCertStore
         • Intermediate X.509 certificate=${USER_INSTALL_ROOT}/etc/ws-security/samples/intca2.cer

      4. Click OK.

   2. Configure a Trust Anchor.

      1. Under Trust anchor, click New...

      2. Specify, Name=providerTrustAnchor.

      3. Click External Keystore, and specify:
         • Full path=${USER_INSTALL_ROOT}/etc/ws-security/samples/dsig-receiver.ks
         • Password=server

      4. Click OK, and then click WS-Security in the navigation for this page.

   3. Configure the Signature Generator.

      1. Click Authentication and protection > AsymmetricBindingRecipientSignatureToken0 (signature generator), and then clickApply.

      2. Click Callback handler

      3. Specify Keystore=custom.

      4. Click Custom keystore configuration, and then specify
         • Full path=${USER_INSTALL_ROOT}/etc/ws-security/samples/dsig-receiver.ks
         • Keystore password=server
         • Name=server
         • Alias=soapprovider
         • Password=server

      5. Click OK, OK, and OK.

   4. Configure the Signature Consumer.

      1. Click AsymmetricBindingInitiatorSignatureToken0 (signature consumer), and then click Apply.

      2. Click Callback handler.

      3. Under Certificates, click the Certificate store radial button, and specify:
         • Certificate store=providerCertStore
         • Trusted anchor store=providerTrustAnchor

      4. Click OK.

      5. Click Authentication and protection in the navigation for this page.

   5. Configure the request Signing Information.

      1. Click request:app_signparts, and specify Name=reqSignInf.

      2. Click Apply.

      3. Under Signing key information, click New , and then specify:
         • Name=reqSignKeyInfo
         • Token generator or consumer name=AsymmetricBindingInitiatorSignatureToken0

      4. Click Ok.

      5. Under Signing key information, click reqSignKeyinfo, and then click Add.

      6. Under Message part reference, click request:app_signparts.

      7. Click Edit.

      8. Under Transform algorithms, click New, and then specify URL=http://www.w3.org/2001/10/xml-exc-c14n#.

      9. Click OK, OK, and OK.

   6. Configure the response Signing Information.

      1. Click response:app_signparts, and specify Name=rspSignInfo.

      2. Click Apply.

      3. Under Signing key information, click New , and then specify:
         • Name=rspSignKeyInfo

         • Type=Security Token reference
         • Token generator or consumer name=AsymmetricBindingRecipientSignatureToken0

      4. Click Ok, and then click Apply.

      5. Under Message part reference, select response:app_signparts .

      6. Click Edit.

      7. Under Transform algorithms, click New.

      8. Specify URL=http://www.w3.org/2001/10/xml-exc-c14n#.

      9. Click OK, OK, and OK.

10. Configure digital signature for the SAML token in the provider bindings.

    1. Click WS-Security in the navigation for this page, and then click Authentication and protection.

    2. Modify the currently configured inbound Signed message part bindings to include the new SAML part 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.

11. Optional: We can configure the caller binding to select a SAML token to represent the requester identity. The Web Services Security runtime environment uses the specified JAAS login configuration to acquire the user security name and group membership data from the user registry using the SAML token NameId or NameIdentifier as the user name.

    1. Click WebSphere enterprise applications > JaxWSServicesSamples > Service provider policy sets and bindings > Saml Bearer Provider sample > WS-Security > Callers.

    2. Click New to create the caller configuration

    3. Specify a Name, such as caller.

    4. Enter a value for the Caller identity local part.

       For SAML 1.1 tokens enter: http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.1#SAMLV1.1

       For SAML 2.0 tokens enter: http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.1#SAMLV2.0

    5. Click Apply and Save.

12. Restart the web services provider application so the policy set attachment modifications can take effect.

Results

The JaxWSServicesSamples web services application is ready to use the new SAML sender-vouches policy set, SAML sender-vouches application specific client binding, and SAML sender-vouches application-specific provider binding.

Related concepts:

General sample bindings for JAX-WS applications
Secure Sockets Layer client certificate authentication

Related

Signing SAML tokens at the message level
Configure a policy set and bindings for XML Digital Signature with client and provider application specific bindings
SAML bearer token
Communicate with STS
Encoding passwords in files
Create application server profiles

+

Search Tips   |   Advanced Search