Requesting SAML holder-of-key tokens with symmetric key from external security token service using WSS APIs

You can request an external security token service (STS) to issue SAML tokens with the holder-of-key subject confirmation method with symmetric key that is encrypted for a target service. Use the Java™ API for XML-Based Web Services (JAX-WS) programming model and Web Services Security APIs (WSS APIs) to complete this task.

1. Specify an STS from which to request a SAML security token that contains holder-of-key subject confirmation method; for example:

   com.ibm.websphere.wssecurity.wssapi.WSSFactory factory =
       com.ibm.websphere.wssecurity.wssapi.WSSFactory.getInstance();
   WSSGenerationContext gencont1 = factory.newWSSGenerationContext();
   WSSConsumingContext concont1 = factory.newWSSConsumingContext();
   HashMap<Object, Object> cbackMap1 = new HashMap<Object, Object>();
   cbackMap1.put(SamlConstants.STS_ADDRESS, "https://www.example.com/sts");  //STS URL
   cbackMap1.put(SamlConstants.SAML_APPLIES_TO, "http://myhost:9080/myService");  //Target Service
   cbackMap1.put(IssuedTokenConfigConstants.TRUST_CLIENT_SOAP_VERSION, "1.1");
   cbackMap1.put(IssuedTokenConfigConstants.TRUST_CLIENT_WSTRUST_NAMESPACE,
                     "http://docs.oasis-open.org/ws-sx/ws-trust/200512"); 
   cbackMap1.put(IssuedTokenConfigConstants.TRUST_CLIENT_COLLECTION_REQUEST,
                 "true");   //RST or RSTC
   cbackMap1.put(SamlConstants.TOKEN_TYPE, 
                 "http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.1#SAMLV2.0");
   cbackMap1.put(SamlConstants.CONFIRMATION_METHOD, "holder-of-key");

   To request a holder-of-key SAML security token from the STS, you must specify whether to embed a symmetric key or a public key by way of a KeyType element in a trust request. This example requires a symmetric key type as shown in the next step.

2. Specify the symmetric key to be embedded in SAML security tokens; for example:

   cbackMap1.put(SamlConstants.KEY_TYPE,
                "http://docs.oasis-open.org/ws-sx/ws-trust/200512/SymmetricKey");
   
   SAMLGenerateCallbackHandler cbHandler1 = new SAMLGenerateCallbackHandler(cbackMap1);
   cbHandler1.setWSSConsumingContextForTrustClient(concont1);
   cbHandler1.setWSSGenerationContextForTrustClient(gencont1);
   
   SecurityToken samlToken = factory.newSecurityToken(SAMLToken.class, 
                                                      cbHandler1, "system.wss.generate.saml");

   The requested SAML token contains a symmetric key that is encrypted for the target service. The STS also returns the unencrypted symmetric key through the WS-Trust RequestedProofToken element. See the following example.

   <wst:RequestedProofToken>
       <wst:BinarySecret
         xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd"
         wsu:Id="_27325D34CE4BCC83141288966548620">n68rFQba+XTZLNBfEc4prg==</wst:BinarySecret>
   </wst:RequestedProofToken>

   The RequestedProofToken element is shown here for your information. The detailed processing is not exposed to WSS APIs users. The RequestedProofToken element and the symmetric key are handled by the Web Services Security runtime environment, or more precisely by the SAMLGenerateLoginModule that is specified in the system.wss.geenrate.saml JAAS login configuration.