Oracle® Fusion Middleware
Part 11. 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 API Gateway receives this token, it can perform one of the following tasks, depending on the requirements:

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

<?xml version="1.0" encoding="iso-8859-1"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
 <soap:Header>	     
  <wsse:Security xmlns:wsse="http://schemas.xmlsoap.org/ws/2003/06/secext">
   <wsse:UsernameToken wsu:Id="sample" 
       xmlns:wsu="http://schemas.xmlsoap.org/ws/2003/06/utility">
    <wsse:Username>sample</wsse:Username>
    <wsse:Password Type="wsse:PasswordText">oracle</wsse:Password>
    <wsu:Created>2004-05-19T08:44:51Z</wsu:Created>
   </wsse:UsernameToken>
  </wsse:Security>
  <wsse:Security soap:actor="oracle" 
      xmlns:wsse="http://schemas.xmlsoap.org/ws/2003/06/secext">
   <wsse:UsernameToken wsu:Id="oracle" 
       xmlns:wsu="http://schemas.xmlsoap.org/ws/2003/06/utility">
    <wsse:Username>oracle</wsse:Username>
    <wsse:Password Type="wsse:PasswordText">oracle</wsse:Password>
    <wsu:Created>2004-05-19T08:46:04Z</wsu:Created>
   </wsse:UsernameToken>
  </wsse:Security>
 </soap:Header>
  <soap:Body>
   <getHello xmlns="http://www.oracle.com"/>
  </soap:Body>
</soap:Envelope>  

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

To configure general settings, complete the following fields:

Name:

Enter an appropriate name for this filter.

Actor:

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 API 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 API Gateway in subsequent authorization filters.

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

 <wsse:UsernameToken wsu:Id="oracle"
       xmlns:wsu="http://schemas.xmlsoap.org/ws/2003/06/utility">
   <wsu:Created>2006.01.13T-10:42:43Z</wsu:Created>
   ...
 </wsse:UsernameToken>

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 API 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. This is a randomly generated number that is added to the message. You can use the combination of a timestamp and a nonce to help prevent replay attacks.

Select cache to store WSS username token nonces in:

Click the button on the right, and select the cache that stores the nonce value (for example, Kerberos Session Keys). Defaults to the local WSS Username Token Nonce Cache.

To add a cache, right-click the Caches tree node, and select Add Local Cache or Add Distributed Cache. Alternatively, you can configure caches under the Libraries node in the Policy Studio tree. For more details, see the topic on Global Caches.

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

Repository Name:

The API 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 API Gateway to remove one of these on successful authentication.