Requesting SAML holder-of-key tokens with asymmetric 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 a public key in an X.509 certificate with the Java™ API for XML-Based Web Services (JAX-WS) programming model and Web Services Security APIs (WSS APIs).

Before you begin

This task assumes that you are familiar with the JAX-WS programming model, the WSS API interfaces, SAML concepts, and the use of policy sets to configure and administer web services settings. Complete the following actions before you begin this task:
  • Read about propagating self-issued SAML holder-of-key tokens with asymmetric key by using WSS APIs.
  • Become familiar with using embedded key materials in SAML tokens for message protection by using WSS APIs. Your usage scenario requires requesting SAML tokens from an external STS instead of using self-issued SAML tokens.
  • Read about requesting SAML sender-vouches tokens from an external STS to propagate by using WSS APIs with message level protection.
  • Read about requesting SAML sender-vouches tokens from an external STS to propagate by using WSS APIs with transport level protection.
  • Read about requesting SAML bearer tokens from an external STS, which you propagate by using WSS APIs with transport level protection.
  • Become familiar with accessing an external STS by using WSS APIs.

About this task

This task shows example code to request SAML tokens with the holder-of-key subject confirmation method and the embedded public key in an X.509 certificate by using WSS APIs, from an external STS. This task focuses on sending an X.509 certificate to an external STS when requesting SAML holder-of-key tokens.

Procedure

  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");
cbackMap1.put(SamlConstants.SAML_APPLIES_TO, "http://myhost:9080/myService");
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");

    For the holder-of-key subject confirmation method, you must specify whether a public key or a symmetric key is embedded in SAML tokens. This example specifies a public key type. It then specifies the location of a certificate that contains the public key, and the location of the corresponding private key for the sender to digitally sign elements of SOAP messages to satisfy the holder-of-key subject confirmation requirements.

  2. Specify the location of an X.509 certificate to embed in SAML tokens and a corresponding private key for using to digitally sign message elements; for example: 
    cbackMap1.put(SamlConstants.KEY_TYPE,
              "http://docs.oasis-open.org/ws-sx/ws-trust/200512/PublicKey");
cbackMap1.put(SamlConstants.KEY_ALIAS, "soapinitiator" );
cbackMap1.put(SamlConstants.KEY_NAME, "CN=SOAPInitator, O=Example");
cbackMap1.put(SamlConstants.KEY_PASSWORD, "myinitatkeypass");
cbackMap1.put(SamlConstants.KEY_STORE_PATH, "keystores/initiator.jceks");
cbackMap1.put(SamlConstants.KEY_STORE_PASSWORD, "myinitatstorepass");
cbackMap1.put(SamlConstants.KEY_STORE_TYPE, "jceks");

SAMLGenerateCallbackHandler cbHandler1 = new SAMLGenerateCallbackHandler(cbackMap1);
cbHandler1.setWSSConsumingContextForTrustClient(concont1);
cbHandler1.setWSSGenerationContextForTrustClient(gencont1);

SecurityToken samlToken = factory.newSecurityToken(SAMLToken.class,
                                                   cbHandler1, "system.wss.generate.saml");

    The specified X.509 certificate is sent in WS-Trust requests to the external STS in the trust:UseKey element. For more information read about SAML assertions defined in the SAML Token Profile standard. SSL is used to protect integrity and confidentiality of WS-Trust request and response messages in this example.

Results

You have learned key building blocks to request SAML tokens with the holder-of-key subject confirmation method and asymmetric key from an external STS using WSS APIs. To use the SAML token to sign request messages, become familiar with the example code in the Propagating self-issued SAML holder-of-key tokens with asymmetric key by using WSS APIs topic.