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:
-
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="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:
-
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 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.