Username token

You can use the <UsernameToken> element to propagate a user name and, optionally, password information. Also, you can use this token type to carry basic authentication information. Both a user name and a password are used to authenticate the SOAP message.

OASIS: Web Services Security UsernameToken Profile 1.0

A UsernameToken element containing the user name is used in identity assertion. Identity assertion establishes the identity of the user based on the trust relationship.

The following example shows the syntax of the <UsernameToken> element:

<wsse:UsernameToken wsu:Id="Example-1">
   <wsse:Username> 
   ... 
   </wsse:Username>
   <wsse:Password Type="..."> 
   ... 
   </wsse:Password>
   <wsse:Nonce EncodingType="..."> 
   ... 
   </wsse:Nonce>
   <wsu:Created> 
   ... 
   </wsu:Created>
</wsse:UsernameToken>

The Web services security specification defines the following password types:

wsse:PasswordText (default)

This type is the actual password for the user name.

wsse:PasswordDigest

The type is the digest of the password for the user name. The value is a base64-encoded SHA1 hash value of the UTF8-encoded password.

WebSphere Application Server supports the default PasswordText type. However, it does not support password digest because most user registry security policies do not expose the password to the application software. The following example illustrates the use of the <UsernameToken> element:

<S:Envelope 
       xmlns:S="http://schemas.xmlsoap.org/soap/envelope/"
       xmlns:wsse="http://docs.oasis-open.org
      /wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
    <S:Header>
            ...
        <wsse:Security>
            <wsse:UsernameToken>
                <wsse:Username>Joe</wsse:Username>
                <wsse:Password>ILoveJava</wsse:Password>
            </wsse:UsernameToken>
        </wsse:Security>
    </S:Header>
</S:Envelope>

Example

The following example provides sample code for creating Username tokens:

WSSFactory factory = WSSFactory.getInstance();
   WSSGenerationContext gencont = factory.newWSSGenerationContext();
 
// Attach the username token to the message.
   UNTGenerationCallbackHandler ugCallbackHandler = 
      newUNTGenerationCallbackHandler("alice", "ecila");
   SecurityToken ut = factory.newSecurityToken(ugCallbackHandler, 
                                               UsernameToken.class);
   gencont.add(ut);

// Generate the WS-Security header
gencont.process(msgctx);

Related concepts

Related tasks