WS-Security Username Authentication



A WS-Security Username Token enables an end-user identity to be passed over multiple hops before reaching the destination Web Service. The user identity is inserted into the message and is available for processing at each hop on its path.

The client user name and password are encapsulated in a WS-Security <wsse:UsernameToken>. When the Enterprise Gateway receives this token, it can perform one of the following tasks, depending on the requirements:

  • Ensure that the timestamp on the token is still valid
  • Authenticate the user name against a repository
  • Authenticate the user name and password against a repository

The following sample SOAP message contains two <wsse:UsernameToken> blocks:

<?xml version="1.0" encoding="iso-8859-1"?>
<soap:Envelope xmlns:soap="">
  <wsse:Security xmlns:wsse="">
   <wsse:UsernameToken wsu:Id="sample" 
    <wsse:Password Type="wsse:PasswordText">oracle</wsse:Password>
  <wsse:Security soap:actor="oracle" 
   <wsse:UsernameToken wsu:Id="oracle" 
    <wsse:Password Type="wsse:PasswordText">oracle</wsse:Password>
   <getHello xmlns=""/>

This topic explains how to configure the Enterprise Gateway to authenticate users using a WS-Security <wsse:UsernameToken>.

General Configuration

To configure general settings, complete the following fields:

Enter an appropriate name for this filter.

The example SOAP message at the top of this page contains two <wsse:UsernameToken> blocks. You must specify which block contains the <wsse:UsernameToken> used to authenticate the end-user. Specify the SOAP Actor/Role of the WS-Security block that contains the token.

Credential Format:
The Enterprise Gateway can authenticate users against a user profile repository based on User Names, X.509 Distinguished Names, or email addresses. Unfortunately, the WS-Security specification does not provide a means of specifying the type of <wsse:UsernameToken>, and so it is necessary for the administrator to do so using the Credential Format field. The type specified here is used internally by the Enterprise Gateway in subsequent authorization filters.

Token Validation

Each wsse:UsernameToken contains a timestamp inserted into the <wsu:Created> element. Using this timestamp together with the details entered in this section, the Enterprise Gateway can determine whether the WS-Security UsernameToken has expired. The <wsu:Created> element is as follows:

 <wsse:UsernameToken wsu:Id="oracle"

To configure token validation settings, complete the following fields:

Drift Time:
Specified in seconds to account for differences in the clock times between the machine on which the token was generated and the machine running the Enterprise Gateway. Using the start time, end time, and drift time, the token is considered valid if the current time falls between the following times:

[start - drift] and [start + drift + end]

Validity Period:
Specifies the lifetime of the token, where the value of the <wsu:Created> element represents the start time of the assertion, and the time period entered represents the end time.

Timestamp Required:
Select this option if you want to ensure that the Username Token contains a timestamp. If no timestamp is found in the Username Token, a SOAP Fault is returned.

Nonce Required:
Select this option to ensure that the Username Token contains a <wsse:Nonce> element. You can use the combination of a timestamp and a nonce to help prevent replay attacks.

Token Verification via Repository

Having validated the timestamp on the token, the Enterprise Gateway can then optionally authenticate the user name and password contained in the token. The following options are available:

  • No Verification
    No verification of the user name and password is performed. Only the timestamp on the token is validated. This is the default behavior.
  • Verify Username Only
    Only the user name is looked up in the selected repository. If the user name is found in this repository, the user is authenticated. Select the No password allowed checkbox to block messages that contain a Username Token with a <wsse:Password> element.
  • Verify Username and Password
    The user name is looked up in the selected repository and is only authenticated if the corresponding password matches the one configured in the repository. If you select this option, you must select the type of the password. Both cleartext and digest formats are supported. Select the appropriate option.

Repository Name:
The Enterprise Gateway attempts to authenticate users against the selected Authentication Repository. User profiles can be stored in the local store, a database, or an LDAP directory. For details on adding a new repository, and editing or deleting a repository, see the Authentication Repository tutorial.

Remove enclosing WS-Security element on successful validation:
Select this option if you wish to remove the WS-Security block that contains the Username Token after the token has been successfully authenticated. For example, in the above sample SOAP message that contains two <wsse:UsernameToken> elements in two different WS-Security blocks, you could configure the Enterprise Gateway to remove one of these on successful authentication.