Creating custom security tokens for Web services security using the GenericSecurityTokenFactory SPIs

Use the GenericSecurityTokenFactory SPIs to create custom security tokens for use by the WS-Security runtime. These security tokens can be used for, but are not be limited to, WSSAPIs, JAAS login modules, and custom security tokens.

About this task

The GenericSecurityTokenFactory provides several SPIs to create custom tokens that can be emitted with the GenericIssuedTokenGenerateLoginModule.

A custom security token that is created with the GenericSecurityTokenFactory is the complete form of a security token that can be emitted by the WS-Security run time. You do not have to write an emitter or receiver, such as writeExternal or readExternal, for the token you create using these SPIs. Only two pieces of information are required:

The token element, which is either Axiom or w3c.dom implementation
The value type

In the following steps, the custom token being created is a UsernameToken. We selected this token as the custom token to create because it is a well-known form, and has a good mix of elements, sub-elements, and attributes. To determine the methods you need to use to build your own custom tokens, look at the XML for a UsernameToken, and match up that XML with what is being done in the methods included in one of the following steps.

Procedure

Create a custom token from a String

import javax.xml.namespace.QName;
import com.ibm.websphere.wssecurity.wssapi.token.GenericSecurityTokenFactory;
import com.ibm.websphere.wssecurity.wssapi.token.SecurityToken;

//Create a UsernameToken SecurityToken from a String
final String untString="<sec:UsernameToken utl:ID=\"_unt999\" xmlns:sec=\"http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd\"xmlns:utl=\"http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd\">"+
"<sec:Username>myUsername</sec:Username>"+
"<sec:Password Type=\"http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText\">myPassword</sec:Password>"+
"</sec:UsernameToken>";

GenericSecurityTokenFactory gst = GenericSecurityTokenFactory.getInstance();
QName valueType =  new QName("", "http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#UsernameToken");
SecurityToken unt = gst.getToken(untString,valueType);


//Create a custom SecurityToken from a String
final String customString="<acme:MyToken xmlns:acme=\"https://www.acme.com\""+
"xmlns:utl=\"http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd\" utl:Id=\"cust_3\">"+
"<acme:Email>joe.smith@acme.com</acme:Email>"+
"</acme:MyToken>";

QName custValueType = new QName("https://www.acme.com","MyToken");
SecurityToken custSt = gst.getToken(customString, custValueType);

Create a custom token from a w3c.dom element.

import javax.xml.soap.SOAPElement;
import com.ibm.websphere.wssecurity.wssapi.token.GenericSecurityTokenFactory;
import com.ibm.websphere.wssecurity.wssapi.token.SecurityToken;
import javax.xml.namespace.QName;
...

GenericSecurityTokenFactory gstFactory = GenericSecurityTokenFactory.getInstance();

SOAPElement untElement = getDomUntElement("myUsername", "myPassword", gstFactory.createUniqueId());

QName valueType =  new QName("", "http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#UsernameToken");

SecurityToken unt = gstFactory.getToken(untElement, valueType);

Create a custom token from an Axiom element.

import org.apache.axiom.om.OMElement;
import com.ibm.websphere.wssecurity.wssapi.token.GenericSecurityTokenFactory;
import com.ibm.websphere.wssecurity.wssapi.token.SecurityToken;
import javax.xml.namespace.QName;
...

GenericSecurityTokenFactory gstFactory = GenericSecurityTokenFactory.getInstance();

OMElement untElement = getAxiomUntElement("myUsername", "myPassword", gstFactory.createUniqueId());

QName valueType =  new QName("", "http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#UsernameToken");

SecurityToken unt = gstFactory.getToken(untElement, valueType);

Create a w3c.dom custom token element.

import javax.xml.soap.SOAPFactory;
import javax.xml.soap.SOAPElement;

SOAPElement getDomUntElement(String username, String password, String uniqueId) {
  SOAPFactory factory = SOAPFactory.newInstance();

  //Create the UsernameToken element
  SOAPElement untElement = factory.createElement("UsernameToken", "sec", "http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd");
  untElement.addAttribute(new QName("http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd", "Id", "utl"), uniqueId);

  //Create the Username element
  SOAPElement unameElement = factory.createElement("Username", "sec", "http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd");
  unameElement.addTextNode(username);

  //Add the Username element to the UsernameToken
  untElement.addChildElement(unameElement);

  if (password != null) {
      //Create the Password element
      SOAPElement passElement = factory.createElement("Password", "sec", "http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd");
      passElement.addAttribute(new QName("Type"), "http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText");
      passElement.addTextNode(password);

      //Add the Password element to the UsernameToken
      untElement.addChildElement(passElement);
  }

  return untElement;
}

Create an Axiom custom token element.

import org.apache.axiom.om.OMAbstractFactory;
import org.apache.axiom.om.OMFactory;
import org.apache.axiom.om.OMElement;
import org.apache.axiom.om.OMNamespace;

OMElement getAxiomUntElement(String username, String password, String uniqueId) {
  
  OMFactory factory = OMAbstractFactory.getOMFactory();

  //Create the UsernameToken element
  OMElement untElement = factory.createOMElement("UsernameToken", "http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd", "sec");
  OMNamespace idNs = factory.createOMNamespace("http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd", "utl");
  untElement.addAttribute("Id", uniqueId, idNs);

  //Create the Username element
  OMElement unameElement = factory.createOMElement("Username", "http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd", "sec");
  unameElement.setText(username);

  //Add the Username element to the UsernameToken
  untElement.addChild(unameElement);

  if (password != null) {
      //Create the Password element
      OMElement passElement = factory.createOMElement("Password", "http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd", "sec");
      passElement.addAttribute("Type", "http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText", null);
      passElement.setText(password);

      //Add the Password element to the UsernameToken
      untElement.addChild(passElement);
  }

  return untElement;
}