Token type overview

A security token represents a set of claims made by a client that may include a name, password, identity, key, certificate, group, or privilege. Web services security provides a general-purpose mechanism to associate security tokens with messages for single-message authentication. A specific type of security token is not required by Web services security. Web services security is designed to be extensible and support multiple security token formats to accommodate a variety of authentication mechanisms. For example, a client may provide proof of identity and proof that they have a particular business certification.

A security token is embedded in the Simple Object Access Protocol (SOAP) message within the SOAP header. The security token within in the SOAP header is propagated from the message sender to the intended message receiver. On the receiving side, the WebSphere Application Server - Express security handler authenticates the security token and sets up the caller identity on the thread.

The proposed Web services security draft defines these types of security tokens:

• User name tokens
  A username token consists of a user name and, optionally, password information. You can include a username token directly in the <Security> header within the message.

• Binary security tokens
  Binary tokens require a special encoding for inclusion. The Web services security specification describes how to encode binary security tokens such as X.509 certificates and Kerberos tickets; and how to include opaque encrypted keys. The specification also includes extensibility mechanisms that you can use to further describe the characteristics of the credentials that are included with a message. For more information, see Web Services Security (WS-Security) (http://schemas.xmlsoap.org/specs/ws-security/ws-security.htm).

WebSphere Application Server - Express supports user name tokens. Basic authentication and identity assertion authentication both require user name tokens. The binary security token implementation supports both X.509 certificates and LTPA binary security. You can extended the implementation to generate other type of tokens. However, Kerberos tickets are not supported in WebSphere Application Server - Express.

Each type of token is processed by a corresponding token-generation and validation module. The binary token generation and validation modules are pluggable and are based on the Java Authentication and Authorization Service (JAAS) framework. For more information, see Pluggable token support. For example, arbitrary XML-based token format is supported using the JAAS pluggable framework. WebSphere Application Server - Express does not support an XML-based token that is used in SecurityTokenReference. For more information, see XML tokens.

You can define the types of tokens that the message can accept in the deployment descriptor extension file, ibm.webservices-ext.xmi. A message receiver may support one or more types of security tokens.

The following example shows that the receiver supports four types of security tokens:

<?xml version="1.0" encoding="UTF-8"?>
<com.ibm.etools.webservice.wsext:WsExtension xmi:version="2.0" xmlns:xmi="http://www.omg.org/XMI"  
 xmlns:com.ibm.etools.webservice.wsext="http://www.ibm.com/websphere/appserver/schemas/5.0.2/wsext.xmi"
 xmi:id="WsExtension_1052760331306" routerModuleName="StockQuote.war">
  <wsDescExt xmi:id="WsDescExt_1052760331306" wsDescNameLink="StockQuoteFetcher">
    <pcBinding xmi:id="PcBinding_1052760331326" pcNameLink="urn:xmltoday-delayed-quotes" scope="Session">
      <serverServiceConfig xmi:id="ServerServiceConfig_1052760331326"actorURI= "myActorURI">
        <securityRequestReceiverServiceConfig xmi:id="SecurityRequestReceiverServiceConfig_1052760331326">
          <loginConfig xmi:id="LoginConfig_1052760331326">
            <authMethods xmi:id="AuthMethod_1052760331326" text="BasicAuth"/>
            <authMethods xmi:id="AuthMethod_1052760331327" text="IDAssertion"/>
            <authMethods xmi:id="AuthMethod_1052760331336" text="Signature"/>
            <authMethods xmi:id="AuthMethod_1052760331337" text="LTPA"/>
          </loginConfig>
        <idAssertion xmi:id="IDAssertion_1052760331336" idType="Username" trustMode="Signature"/>
        ...

The message sender may choose one of the token types that are supported by the receiver when sending a message. You can define the type of token to be used by the sending side in the client descriptor extension file, ibm-webservicesclient-ext.xmi.

The following example shows that the sender chooses to send a UsernameToken to the receiver:

<?xml version="1.0" encoding="UTF-8"?>
<com.ibm.etools.webservice.wscext:WsClientExtension xmi:version="2.0"
 xmlns:xmi="http://www.omg.org/XMI" xmlns:com.ibm.etools.webservice.wscext=
 "http://www.ibm.com/websphere/appserver/schemas/5.0.2/wscext.xmi"
 xmi:id="WsClientExtension_1052760331496">
  <serviceRefs xmi:id="ServiceRef_1052760331506" serviceRefLink="service/StockQuoteService">
    <portQnameBindings xmi:id="PortQnameBinding_1052760331506" portQnameLocalNameLink="StockQuote">
      <clientServiceConfig xmi:id="ClientServiceConfig_1052760331506" actorURI="myActorURI">
        <securityRequestSenderServiceConfig xmi:id="SecurityRequestSenderServiceConfig_1052760331506"
         actor="myActorURI">
          <loginConfig xmi:id="LoginConfig_1052760331506" authMethod="BasicAuth"/>
          ...