How To - 10.1.3 OWSM: Propagate identity by inserting SAML token using OWSM client agent or gateway

When an application or web service calls another web service, you may want to propagate the identity of the user that first logged into the application or service.
OWSM client agent or gateway can be used to accomplish it.
The basic design is to read the user identity from the java Subject and then convert it into a SAML token.

Step 1: Read java Subject in your application, and create a custom SOAP header.
Subject subject = Subject.getSubject(AccessController.getContext());
Now, using the subject value to lookup username and roles, create the following custom SOAP header. Propagating roles is optional.

<env:Envelope ...>
  <env:Header>
    <custom:userInfo xmlns:custom="http://custom/ns">
      <username>JSmith</username>
      <roles>role1,role2</roles>
    </custom:userInfo>
  </env:Header>
  <env:Body>
  ...
  </env:Body>
</env:Envelope>

Step 2: Convert custom header to SAML token in OWSM client agent or client gateway
Add the following steps in the request pipeline of a client agent or client side gateway.

a. Custom step - Create a custom step that will read the custom SOAP header from the request and set the values in the message context that would be picked up the "Insert SAML step". Refer to OWSM extensibility guide for details on how to develop custom steps.

// read the username from custom header, and set it using API below
// this value will be used to represent SAML Subject
ctx.setUnverifiedUserid(username);

// if roles needs to passed
SOAPElement customHeader = ...
HashMap userMap = new HashMap();
ArrayList roles = new ArrayList();
//add the roles read from custom header. roles.add(...);
userMap.put("roles", roles);
msgCtxt.setProperty(MessageContext.USER_ATTRIBUTES, userMap);

// delete the custom SOAP header from the request message
customHeader.detachNode();

b. Insert SAML step - this will generate the SAML sender-vouches token, and add it to the SOAP Security header.