Authentication of web services clients with a UsernameToken

Providing a user name and password in a web services client

The WS-Security feature in Liberty provides more than one method for indicating the user name and password for a client application when generating a UsernameToken. You can set the user name and password programmatically or in the server.xml file.

A client can generate a UsernameToken with the user name and password provided in the server.xml file. The user name and password that is in the server.xml file is considered the default configuration and is overridden by what is provided on the RequestContext for the client's web service invocation.

<wsSecurityClient id="default"
    ws-security.username="alice"
    ws-security.callback-handler="com.acme.PasswordCallback"
</wsSecurityClient>

Map<String, Object> requestCtx = ((BindingProvider)port).getRequestContext();
requestCtx.put("ws-security.username", "bob_username");
requestCtx.put("ws-security.password", "bob_password");

Consuming a UsernameToken in a web services provider

When a UsernameToken is received, WS-Security automatically uses Liberty security user registry to validate the user name and password, if the password is required. If the password type in the UsernameToken is PasswordDigest or is using derived keys, you must provide the ws-security.callback-handler implementation of a password callback handler by configuring it in the server.xml file. This callback handler must return valid passwords for all expected user names so that the WS-Security run time can calculate digest values for comparison with the value in the SOAP message. After the digest value comparison completes successfully, the user name and password is validated against the user registry.

<wsSecurityProvider id="default"
    ws-security.callback-handler="com.acme.PasswordCallback"
</wsSecurityProvider>

Password CallbackHandler

The password CallbackHandler is used by WS-Security to retrieve a user password. In Liberty, this password CallbackHandler class must be packaged as a Liberty feature. For more information about the password CallbackHandler, see Developing a password callback handler for WS-Security.

For more information on requirements and limitations of a callback handler implementation, refer to the Private key password CallbackHandler section of Protection of web services with an X.509 token.

Protecting a UsernameToken in a SOAP message

<UsernameToken>
  <Username>myusername</Username>
  <Password
    Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText">
    mypassword
  </Password>
</UsernameToken>

When you want to send a UsernameToken with PasswordText, consider additional protections on the message, such as using HTTPS or encrypting the token using the EncryptedSupportingToken policy assertion. For more information on requiring the use of the HTTPS transport in the policy, see Liberty: Web services security HTTPS transport policy assertions.

UsernameToken key derivation

As stated in the Web Services Security UsernameToken Profile 1.1 specification:

The password associated with a username may be used to derive a shared secret key for the purposes of integrity or confidentiality protecting message contents.

It must be noted that passwords are subject to several kinds of attack, which in turn will lead to the exposure of any derived keys. This key derivation procedure is intended to minimize the risk of attacks on the keys, to the extent possible, but it is ultimately limited by the insecurity of a password that it is possible for a human being to remember and type on a standard keyboard.

Two additional elements are required to enable to derivation of a key from a password. They are <wsse11:Salt> and <wsse11:Iteration>. These values are not secret and must be conveyed in the Username token when key derivation is used. When key derivation is used the password must not be included in the Username token. The receiver will use its knowledge of the password to derive the same key as the sender.

If a UsernameToken is using key derivation, for a provider application, you must provide the ws-security.callback-handler implementation of a password callback handler by configuring it in the server.xml file.

<sp:SymmetricBinding>
  <wsp:Policy>
    <sp:ProtectionToken>
      <wsp:Policy>
        <sp:UsernameToken
          sp:IncludeToken="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702/IncludeToken/AlwaysToRecipient">
          <wsp:Policy>
            <sp:WssUsernameToken10 />
            <sp:RequireDerivedKeys />
          </wsp:Policy>
        </sp:UsernameToken>
      <wsp:Policy>
    </sp:ProtectionToken>
  </wsp:Policy>
</sp:SymmetricBinding>

<wsse:UsernameToken wsse:Id="...">
  <wsse:Username>...</wsse:Username>
  <wsse11:Salt>...</wsse11:Salt>
  <wsse11:Iteration>...</wsse11:Iteration>
</wsse:UsernameToken>